sk.baka.ambient.collection
Interface ICollection

All Known Implementing Classes:

AmpacheCollection, LibraryCollection, MediaStoreCollection

public interface ICollection

A collection strategy. Allows read-only access to underlying storage of artists, albums, tracks and genres.

The implementation must be thread-safe - any method may be called from multiple threads at once. The methods should periodically check for interrupted state and throw InterruptedException (or other kind of exception) if they are interrupted.

Author:

Martin Vysny

Method Summary

CategoryItem	deserializeItem(java.lang.String serializedItem) Deserializes item serialized by serializeItem(CategoryItem).
java.util.List<TrackMetadataBean>	findTracks(java.util.Map<CategoryEnum,java.lang.String> criteria) Search for tracks using given criteria search.
java.util.List<TrackMetadataBean>	findTracks(java.lang.String substring) A simpler version of findTracks(Map).
java.util.Map<java.lang.String,java.lang.String>	fixLocations(java.util.Collection<java.lang.String> locations) Given locations became invalid and need fixing.
java.util.List<CategoryItem>	getCategoryList(CategoryEnum request, CategoryItem context, java.lang.String substring, boolean sortByYear) Returns category list matching given criteria.
java.lang.String	getName() Returns short descriptive name of this collection backend.
Statistics	getStatistics() Returns statistics for this collection.
java.util.List<TrackMetadataBean>	getTracks(CategoryItem context) Returns all tracks contained in given category.
boolean	isLocal() Checks if the underlying strategy uses local resources to retrieve metadata (a DB backend), or it uses remote access to a server (for example Ampache).
IDynamicPlaylistTrackProvider	newTrackProvider(Random random) Returns a new instance of the track provider.
java.lang.String	serializeItem(CategoryItem item) Returns ID returned by this collection in the CategoryItem.id as String.
boolean	supportsLocationFix() Serves for optimalization purposes only: checks if this collection can perform obsolete locations fixup or not.

Method Detail

isLocal

boolean isLocal()

Checks if the underlying strategy uses local resources to retrieve metadata (a DB backend), or it uses remote access to a server (for example Ampache).

Returns:

true if the collection queries will tend to be performed fast, false otherwise.

getName

java.lang.String getName()

Returns short descriptive name of this collection backend.

Returns:

the name.

getTracks

java.util.List<TrackMetadataBean> getTracks(CategoryItem context)
                                            throws CollectionException,
                                                   java.lang.InterruptedException

Returns all tracks contained in given category.

Parameters:

context - search in context of this item. Must not be null.

Returns:

list of tracks, sorted in no particular order. Must not be null, may be empty. Not required to be thread-safe. Sorted in no particular order.

Throws:

CollectionException - thrown when the collection fails to return items.

java.lang.InterruptedException - when interrupted.

getCategoryList

java.util.List<CategoryItem> getCategoryList(CategoryEnum request,
                                             CategoryItem context,
                                             java.lang.String substring,
                                             boolean sortByYear)
                                             throws CollectionException,
                                                    java.lang.InterruptedException

Returns category list matching given criteria. Returns sorted list, either by name or by the year.

Parameters:

request - the category to search for. Must not be null.

context - search in context of this item. May be null - in this case all categories are returned.

substring - if not null then all category names must contain this substring.

sortByYear - if true then the result category list is sorted by year, then by CategoryItem.sortKey. If false then sorted only by CategoryItem.sortKey. Ignored when the request parameter is not an album.

Returns:

list of categories. Must not be null, may be empty. Not required to be thread-safe. Sorted depending on the value of the sortByYear parameter.

Throws:

CollectionException - thrown when the collection fails to return items.

java.lang.InterruptedException - when interrupted.

findTracks

java.util.List<TrackMetadataBean> findTracks(java.lang.String substring)
                                             throws CollectionException,
                                                    java.lang.InterruptedException

A simpler version of findTracks(Map). Search song which Song Title, Artist Name, Album Name or Genre Name contains given substring.

Parameters:

substring - the substring to search for.

Returns:

the list of tracks. Must not be null, may be empty. Sorted in no particular order. Not required to be thread-safe.

Throws:

CollectionException - thrown when the collection fails to return items.

java.lang.InterruptedException - when interrupted.

getStatistics

Statistics getStatistics()
                         throws CollectionException,
                                java.lang.InterruptedException

Returns statistics for this collection.

Returns:

the statistics object, must not be null.

Throws:

CollectionException - thrown when the collection fails to return items.

java.lang.InterruptedException - when interrupted.

serializeItem

java.lang.String serializeItem(CategoryItem item)

Returns ID returned by this collection in the CategoryItem.id as String. This item will only be used to perform searches - you should thus preserve minimum information from the category item. This functionality is only used by AmpacheServer. You do not need to store the CategoryItem.category - it will be overwritten.

Parameters:

item - the item to convert

Returns:

string representation of given item.

deserializeItem

CategoryItem deserializeItem(java.lang.String serializedItem)

Deserializes item serialized by serializeItem(CategoryItem). This item will be used to perform search only. This functionality is only used by AmpacheServer. You do not need to store the CategoryItem.category - it will be overwritten.

Parameters:

serializedItem - the item to deserialize

Returns:

the ID instance.

newTrackProvider

IDynamicPlaylistTrackProvider newTrackProvider(Random random)

Returns a new instance of the track provider. May return null if this collection does not provide this functionality. It is caller's responsibility to close the provider.

Parameters:

random - initially provide tracks using this random value.

Returns:

new provider instance, may be null.

findTracks

java.util.List<TrackMetadataBean> findTracks(java.util.Map<CategoryEnum,java.lang.String> criteria)
                                             throws CollectionException,
                                                    java.lang.InterruptedException

Search for tracks using given criteria search.

Parameters:

criteria - the criteria, must not be null. AND operator is used if multiple criteria are specified. String values are matched as substrings.

Returns:

tracks that comply given criteria, in no particular order. Not required to be thread-safe.

Throws:

CollectionException - thrown when the collection fails to return items.

java.lang.InterruptedException - when interrupted.

supportsLocationFix

boolean supportsLocationFix()

Serves for optimalization purposes only: checks if this collection can perform obsolete locations fixup or not.

Returns:

true if fixLocations(Collection) is supported, false if the collection cannot fix the locations, or the fix operation is not applicable to this collection.

fixLocations

java.util.Map<java.lang.String,java.lang.String> fixLocations(java.util.Collection<java.lang.String> locations)
                                                              throws CollectionException,
                                                                     java.lang.InterruptedException

Given locations became invalid and need fixing.

MediaPlayer detected an error while playing first location URL from given location list. All given locations might thus have become invalid. The collection is asked to fix these locations: it should re-connect to the server (if any) and/or perform any required steps. If any of these locations became completely invalid the method is free to omit them in the result map. If the collection is unable to fix given location then just pass input location.

Invoked asynchronously. This method will receive only locations provided earlier by track lookup methods such as findTracks(Map).

Parameters:

locations - the list of (possibly) invalid locations. Never null nor empty.

Returns:

a map of locations, maps original location to a fixed locations. Must not be null. Not required to be thread-safe.

Throws:

CollectionException - thrown when this collection is unable to fix the locations.

java.lang.InterruptedException - thrown when interrupted.