Holger's Java API

## com.antelmann.cddb
Class FreeDB

    java.lang.Object
      com.antelmann.cddb.FreeDB

All Implemented Interfaces:
  CDDB

    public class FreeDB

extends Object
implements CDDB

FreeDB implements the connection to a freedb.org server or one of its mirrors.

The FreeDB.org server fully supports the CDDB protocol. You can configure the default connection settings by altering the following properties in `com.antelmann.util.Settings`:

- `cddb.client`
- `cddb.client.version`
- `user.email`

The `user.email` property is used when submitting an entry to the database as a return address. It defaults to cddb@antelmann.com if it is not set otherwise.
Also, the user name is taken from the system properties: `user.name` to identify the user connecting to the service.

Author:
  Holger Antelmann
See Also:
  `Settings`, `setServer(CDDBServer)`

Constructor Summary
`FreeDB()` uses CDDBServer.DEFAULT_SERVER
`FreeDB(CDDBServer server)`

Method Summary
`String[]` `getCategories()` returns the available categories under which the CDInfo entries are stored - in accordance to the CDDB standard
`String` `getMessageOfTheDay()` returns a 'message of the day' quote from freedb.org
`String` `getUserEmail()`
`boolean` `isInTestMode()` determines whether submissions will be treated as a test or a real submission; defaults to true
`CDDBServer[]` `listSites()` returns sites that can be used as a mirror for this service.
`protected String` `performCommand(String command)` This method is called for every command supported by the interface and returns the result as it is provided by the service.
`CDDBRecord[]` `queryCD(CDID cd)` queries the database and returns an array of matches.
`CDInfo` `readCDInfo(CDDBRecord record)` it is suggested that the given record was obtained through a call to queryCD(), so that the record is known to exist.
`void` `setServer(CDDBServer server)` changes the site location used to access the service; the protocol for the server must be http
`void` `setTestMode(boolean on)` determines whether submissions will be treated as a test or a real submission
`void` `setUserEmail(String userEmail)` used when submitting a CDInfo object to the server using `writeCDInfo()`.
`boolean` `verifyDiscID(CDID cd)` tries to verify the discid embedded in the CDID object by querying the service to recalculate the data
`void` `writeCDInfo(CDInfo cdinfo)` submits the CDInfo object to the FreeDB.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

### FreeDB

    public FreeDB()
           throws IOException

  uses CDDBServer.DEFAULT_SERVER

  Throws:
    `IOException`
  See Also:
    `CDDBServer.DEFAULT_SERVER`

### FreeDB

    public FreeDB(CDDBServer server)
           throws IOException

Throws:
  `IOException`
See Also:
  `setServer(CDDBServer)`

Method Detail

### setUserEmail

    public void setUserEmail(String userEmail)

  used when submitting a CDInfo object to the server using `writeCDInfo()`. If not set, the value defaults to `Settings.getProperty("user.email")` or "cddb@antelmann.com" if the user.email property is not present. #see #writeCDInfo(CDInfo)

### getUserEmail

    public String getUserEmail()

### isInTestMode

    public boolean isInTestMode()

  determines whether submissions will be treated as a test or a real submission; defaults to true

  See Also:
    `setTestMode(boolean)`

### setTestMode

    public void setTestMode(boolean on)

  determines whether submissions will be treated as a test or a real submission

  See Also:
    `isInTestMode()`

### setServer

    public void setServer(CDDBServer server)
                   throws IOException,
                          IllegalArgumentException

  changes the site location used to access the service; the protocol for the server must be http

  Throws:
    `IllegalArgumentException` - if the server protocol is not http
    `IOException` - if the local hostname could not be resolved
  See Also:
    `listSites()`, `CDDBServer`

### performCommand

    protected String performCommand(String command)
                             throws IOException

  This method is called for every command supported by the interface and returns the result as it is provided by the service.

  Currently, this method is implemented to use the HTTP protocol with GET. If other protocols were to be supported (i.e. HTTP POST or Telnet), only this method needs to be changed/overridden.

  Parameters:
    `command` - the entire client command as specified in the CDDB protocol; example: "cddb lscat"
  Throws:
    `IOException`

### getMessageOfTheDay

    public String getMessageOfTheDay()
                              throws IOException

  returns a 'message of the day' quote from freedb.org

  Throws:
    `IOException`

### listSites

    public CDDBServer[] listSites()
                           throws IOException,
                                  CDDBProtocolException

  returns sites that can be used as a mirror for this service.

  Throws:
    `IOException`
    `CDDBProtocolException`
  See Also:
    `setServer(CDDBServer)`, `Settings`, `CDDBServer`

### getCategories

    public String[] getCategories()
                           throws IOException,
                                  CDDBProtocolException

  Description copied from interface: `CDDB`
  returns the available categories under which the CDInfo entries are stored - in accordance to the CDDB standard

  Specified by:
    `getCategories` in interface `CDDB`
  Throws:
    `IOException`
    `CDDBProtocolException`

### verifyDiscID

    public boolean verifyDiscID(CDID cd)
                         throws IOException,
                                CDDBProtocolException

  tries to verify the discid embedded in the CDID object by querying the service to recalculate the data

  Returns:
    true only if the calculated discid by the service matches the id stored in the CDID object
  Throws:
    `IOException`
    `CDDBProtocolException`

### queryCD

    public CDDBRecord[] queryCD(CDID cd)
                         throws IOException,
                                CDDBProtocolException

  Description copied from interface: `CDDB`
  queries the database and returns an array of matches. These matches can be exact matches as well as inexact matches, which can be determined by calling `isExactMatch()` on any returned element.

  Specified by:
    `queryCD` in interface `CDDB`
  Throws:
    `IOException`
    `CDDBProtocolException`
  See Also:
    `CDDBRecord.isExactMatch()`

### readCDInfo

    public CDInfo readCDInfo(CDDBRecord record)
                      throws IOException,
                             CDDBProtocolException

  it is suggested that the given record was obtained through a call to queryCD(), so that the record is known to exist.

  Specified by:
    `readCDInfo` in interface `CDDB`
  Returns:
    a CDDBEntry instance
  Throws:
    `CDDBProtocolException` - if the record doesn't exist
    `IOException`
  See Also:
    `CDDBEntry`

### writeCDInfo

    public void writeCDInfo(CDInfo cdinfo)
                     throws IOException,
                            CDDBProtocolException

  submits the CDInfo object to the FreeDB. The method checks for errors and warnings using a CDDBXmcdParser before a sumbission takes place.

  Specified by:
    `writeCDInfo` in interface `CDDB`
  Throws:
    `IOException`
    `CDDBProtocolException`
  See Also:
    `setUserEmail(String)`, `setTestMode(boolean)`

(c) Holger Antelmann since 2001- all rights reserved (contact: info@antelmann.com)
see www.antelmann.com/developer for further details and available downloads