Holger's Java API

## com.antelmann.cddb
Interface CDCollection

All Known Implementing Classes:
  SimpleCDCollection

    public interface CDCollection

CDCollection represents what it says: a collection of CDs.

A CDCollection is specific to a user; it embedds a CDSet and maps user-specific properties to each CD in the set. For instance, the properties could contain information about how many CDs of a specific CD a user actually has (in case it was bought twice), or it can contain information on where the CD is physically located.

The information in a CDCollection is inherently different from the information in a CDDB, as the CDDB information is specific to the CD and the CDCollection information is specific to the user/owner of the CD.

CDCollection is an interface to allow full flexibility when implementing a collection (based on a database, file system, remote lookup server or whatever else you may think of), while allowing other classes to access some basic information (such as how many CDs there are and which ones are there).

Note that this interface does not specify any query methods on the content to allow for very simple implementations. You can still iterate through the properties and query the data (inefficiently) yourself. But clearly, for more effective usage, you want to consider using either a sub-interface or methods provided by the implementing class. Also, no methods are provided to explicitly change the content of a CD collection, as those may require an unknown set of parameters to verify that the write access is legitimate.

Author:
  Holger Antelmann
See Also:
  `CDSet`, `CDDB`

Method Summary
`boolean` `addCD(CDID cd)` adds the given cd to the collection and returns true only if the CD was added
`boolean` `contains(CDID cd)` returns true only if the given cd is in this collection
`CDInfo` `getCDInfo(CDID cd)` retrieves the information associated with the given CD in this collection; returns null if the cd is not in the collection or if no information has yet been associated with the given CD
`Properties` `getCDProperties(CDID cd)` returns all user-properties available for a specific CD (as far as applicable) or null if the CD is not in the collection.
`Set<CDID>` `getCDSet()` returns an unmodifiable view over the set of CDID instances in the collection
`boolean` `removeCD(CDID cd)` removes the given cd to the collection and returns true only if the CD was removed
`void` `setCDInfo(CDID cd, CDInfo info)` associates the given info with the given cd in this collection; if the given cd is not yet in the collection, it is added.

Method Detail

### getCDSet

    Set<CDID> getCDSet()

  returns an unmodifiable view over the set of CDID instances in the collection

### getCDProperties

    Properties getCDProperties(CDID cd)

  returns all user-properties available for a specific CD (as far as applicable) or null if the CD is not in the collection.

  (For instance, the properties could map keys like year.bought to the value 2002 or the alike.)

  Note: An implementing class should specify if the changes in the returned properties are reflected on the actual properties associated with the CD in the collection; otherwise you would assume being given a generated view of the properties that internally are maintained differently.

### setCDInfo

    void setCDInfo(CDID cd,
                   CDInfo info)

  associates the given info with the given cd in this collection; if the given cd is not yet in the collection, it is added.

### addCD

    boolean addCD(CDID cd)

  adds the given cd to the collection and returns true only if the CD was added

### removeCD

    boolean removeCD(CDID cd)

  removes the given cd to the collection and returns true only if the CD was removed

### getCDInfo

    CDInfo getCDInfo(CDID cd)

  retrieves the information associated with the given CD in this collection; returns null if the cd is not in the collection or if no information has yet been associated with the given CD

### contains

    boolean contains(CDID cd)

  returns true only if the given cd is in this collection

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