sk.baka.ambient.collection
Interface ICollection

All Known Implementing Classes:

CollectionImpl, CollectionImpl, 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(String serializedItem) Deserializes item serialized by serializeItem(CategoryItem).
List<TrackMetadataBean>	findTracks(Map<CategoryEnum,String> criteria) Search for tracks using given criteria search.
Map<String,String>	fixLocations(Collection<String> locations) Given locations became invalid and need fixing.
List<CategoryItem>	getCategoryList(CategoryEnum request, CategoryItem context, String substring, boolean sortByYear) Returns category list matching given criteria.
String	getName() Returns short descriptive name of this collection backend.
Statistics	getStatistics() Returns statistics for this collection.
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.
List<TrackMetadataBean>	searchTracks(String substring) Search song which Song Title, Artist Name, Album Name or Genre Name contains given substring.
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

String getName()

Returns short descriptive name of this collection backend.

Returns:

the name.

getTracks

List<TrackMetadataBean> getTracks(CategoryItem context)
                                  throws CollectionException,
                                         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.

Throws:

CollectionException - thrown when the collection fails to return items.

InterruptedException - when interrupted.

getCategoryList

List<CategoryItem> getCategoryList(CategoryEnum request,
                                   CategoryItem context,
                                   String substring,
                                   boolean sortByYear)
                                   throws CollectionException,
                                          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 name. If false then sorted only by name. Ignored when the request parameter is not an album.

Returns:

list of categories. Must not be null, may be empty.

Throws:

CollectionException - thrown when the collection fails to return items.

InterruptedException - when interrupted.

searchTracks

List<TrackMetadataBean> searchTracks(String substring)
                                     throws CollectionException,
                                            InterruptedException

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.

Throws:

CollectionException - thrown when the collection fails to return items.

InterruptedException - when interrupted.

getStatistics

Statistics getStatistics()
                         throws CollectionException,
                                InterruptedException

Returns statistics for this collection.

Returns:

the statistics object, must not be null.

Throws:

CollectionException - thrown when the collection fails to return items.

InterruptedException - when interrupted.

serializeItem

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(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

List<TrackMetadataBean> findTracks(Map<CategoryEnum,String> criteria)
                                   throws CollectionException,
                                          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.

Throws:

CollectionException - thrown when the collection fails to return items.

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

Map<String,String> fixLocations(Collection<String> locations)
                                throws CollectionException,
                                       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.

Throws:

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

InterruptedException - thrown when interrupted.