public class

Playlist

extends Model
java.lang.Object
   ↳ java.util.Observable
     ↳ fm.audiobox.core.models.Model
       ↳ fm.audiobox.core.models.Playlist

Class Overview

Playlists are the main containers for Media Files and are represented in the system by an unique token.
Internally a Cloud Drive is treated as a Playlist.
There are different types of playlists and each one can represent a particular media storage service, here's a rundown:

LocalPlaylist
Contains AudioBox Desktop media files. AudioBox Desktop is an application that is able to stream media files directly from the User's pc, without uploading an entire collection first.
During normal desktop usage and syncing this playlist will be filled with metadata of files found on the user's filesystem in the folder he specified. This playlist is not treated differently, except that media files actions are limited, such as destroy, since it is automatically managed.
CloudPlaylist
Contains AudioBox Cloud media files. AudioBox Cloud is the official AudioBox Cloud Media Storage offering and it's available space is unlimited.
This playlist can be accessed only when a valid subscription is in place, so in order to perform actions against it make sure that the permissions: cloud is true in the /api/v1/user.json call.
DropboxPlaylist, SkydrivePlaylist, BoxPlaylist, GdrivePlaylist, YouTubePlaylist, SoundcloudPlaylist, MegaPlaylist
Contains media files synced from the relative remote storage. Accessible when a valid subscription exists, whereas applicable, and a proper service authentication is stored in database. The link between an AudioBox account and the remote service is called an AudioMash.
CustomPlaylist
User-created playlist that contains media files assigned by the user.
SmartPlaylist
User-created playlist that contains media files that corresponds to rules defined by the user. Updates automatically on demand.
OfflinePlaylist
System-created playlist that contains media files the user would like to store on client.

Each playlist supports a set of attributes:

token:
identifier used to perform actions on a playlist, usually part of the URL.
embeddable:
boolean identifying if this playlist can be embedded on an external website. For future use.
visible:
boolean identifying if this playlist should be hidden from the user interface.
syncable:
boolean identifying if this playlist supports syncing with remote content, usually valid for external storage services.
system_name:
a code friendly name identifying playlist's type.
position
integer identifying the order of which playlists should be shown, this is a user's preference. The most important playlists has this attribute unchangeable.

Summary

Public Constructors
Playlist()
Instantiates a new Playlist.
Playlist(String name)
Instantiates a new Playlist.
Public Methods
Playlist addMediaFiles(AudioBoxClient audioBoxClient, List<String> tokens)
Add Media Files to a CustomPlaylist.
Playlist create(AudioBoxClient audioBoxClient)
Creates a new CustomPlaylist or SmartPlaylist depending on the input parameters.
boolean destroy(AudioBoxClient audioBoxClient)
Permanently destroy a playlist.
final boolean equals(Object other)
Albums getAlbums(AudioBoxClient audioBoxClient)
Gets media files grouped by albums.
Artists getArtists(AudioBoxClient audioBoxClient)
Gets media files grouped by albums.
String getDescription()
Gets this playlist brief description.
List<? extends MediaFile> getFingerprints(AudioBoxClient audioBoxClient)
Returns known file fingerprints for this playlist.
List<? extends MediaFile> getFingerprints(AudioBoxClient audioBoxClient, JsonObjectParser parser)
Returns known file fingerprints for this playlist.
Genres getGenres(AudioBoxClient audioBoxClient)
Gets media files grouped by albums.
List<MediaFile> getMediaFiles(AudioBoxClient audioBoxClient, long since)
Same as getMediaFiles(fm.audiobox.core.AudioBoxClient, long, String) but all media file fields are returned.
List<MediaFile> getMediaFiles(AudioBoxClient audioBoxClient, long since, String set)

Returns media files linked to the specified playlist token along with primary information.

List<MediaFile> getMediaFiles(AudioBoxClient audioBoxClient, long since, String set, JsonObjectParser parser)

Returns media files linked to the specified playlist token along with primary information.

List<MediaFile> getMediaFiles(AudioBoxClient audioBoxClient, JsonObjectParser parser)

Returns media files linked to the specified playlist token along with primary information.

List<MediaFile> getMediaFiles(AudioBoxClient audioBoxClient)
Same as getMediaFiles(fm.audiobox.core.AudioBoxClient, long, String) but all media file fields are returned and *no* time filter is applied.
long getMediaFilesCount()
Gets media files count on this playlist.
String getName()
Gets the playlist name.
static String getPath()
Gets the generic remote resource path (token interpolation needed, see interpolate(String, String) ).
long getPosition()
Gets the position of the playlist (client application should respect this field while sorting playlists).
String getSystemName()
Gets system name.
String getToken()
Gets playlist unique token.
String getType()
Gets the playlist type.
String getUpdatedAt()
Gets the last time (in form of an UTC String) this playlist have been changed.
final int hashCode()
boolean isCustom()
Checks if the playlist is a custom one.
boolean isDrive()
Checks if the playlist represents a cloud drive.
boolean isEmbeddable()
Use this method to check if the playlist is embeddable or not.
boolean isLastAccessed()
Use this method to check if the playlist is the last one accessed.
boolean isOffline()
Checks if the playlist is the offline items playlist.
boolean isSmart()
Checks if the playlist is a smart one.
boolean isSyncable()
Checks if this playlist supports syncing with remote content, usually valid for external storage services.
boolean isVisible()
Use this method to check if the playlist is visible or not.
Playlist removeMediaFiles(AudioBoxClient audioBoxClient, List<String> tokens)
Remove Media Files from a CustomPlaylist.
Playlist setDescription(String description)
Sets a brief description of the playlist.
Playlist setEmbeddable(boolean embeddable)
Changes embeddable value, if you want to persist the change remember to call update(fm.audiobox.core.AudioBoxClient) method.
void setLastAccessed(boolean lastAccessed)
Sets as last accessed.
void setMediaFilesCount(long mediaFilesCount)
Sets media files count.
Playlist setName(String name)
Changes playlist name, if you want to persist the change remember to call update(fm.audiobox.core.AudioBoxClient) method.
Playlist setPosition(long position)
Changes position value, if you want to persist the change remember to call update(fm.audiobox.core.AudioBoxClient) method.
void setSyncable(boolean syncable)
Sets syncable property.
void setSystemName(String systemName)
Sets system name.
void setToken(String token)
Sets token.
void setType(String type)
Sets type.
void setUpdatedAt(String updatedAt)
Sets updated at.
Playlist setVisible(boolean visible)
Changes visible value, if you want to persist the change remember to call update(fm.audiobox.core.AudioBoxClient) method.
boolean sync(AudioBoxClient audioBoxClient)
Begin content sync with the remote platform.
boolean toggleVisibility(AudioBoxClient audioBoxClient)

Toggle visibility mode for this playlist.

Playlist update(AudioBoxClient audioBoxClient)
Handle the update of a custom or smart playlist.
[Expand]
Inherited Methods
From class fm.audiobox.core.models.Model
From class java.util.Observable
From class java.lang.Object

Public Constructors

public Playlist ()

Instantiates a new Playlist.

Default empty constructor.

public Playlist (String name)

Instantiates a new Playlist.

Parameters
name the name of the playlist

Public Methods

public Playlist addMediaFiles (AudioBoxClient audioBoxClient, List<String> tokens)

Add Media Files to a CustomPlaylist.

Shallow action that requires a list of media files tokens to be added to this custom playlist. Media files can be added manually only to custom playlists.

Parameters
audioBoxClient the AudioBoxClient to use for the request
tokens the list of the tokens string to add to this playlist
Returns
  • the playlist instance in order to chain other operations on it if needed.
Throws
IllegalStateException if the playlist is not persisted yet.
ResourceNotFoundException if the playlist not found or not of type CustomPlaylist.
AudioBoxException if any of the remote error exception is detected.
IOException if any connection problem occurs.
See Also

public Playlist create (AudioBoxClient audioBoxClient)

Creates a new CustomPlaylist or SmartPlaylist depending on the input parameters.

The user can create a CustomPlaylist by setting the playlist name.

The user can create a SmartPlaylist by setting the playlist name AND playlist search_params.

NOTE: Currently the search_params hash construction is complex enough and therefore it's restricted to the Cloud Web Player, we'll open up the possibility for developers to create them as well.

Parameters
audioBoxClient the client
Returns
  • a new instance of the saved Playlist if success or null if any error occurs
Throws
AudioBoxException if any of the remote error exception is detected.
IOException if any connection problem occurs.
See Also

public boolean destroy (AudioBoxClient audioBoxClient)

Permanently destroy a playlist.

Only Custom and Smart playlists can be destroyed.

Parameters
audioBoxClient the client to use for the request
Returns
  • true if operation succeeds
Throws
AudioBoxException if any of the remote error exception is detected.
IOException if any connection problem occurs.
See Also

public final boolean equals (Object other)

public Albums getAlbums (AudioBoxClient audioBoxClient)

Gets media files grouped by albums.

Also includes the same media file entities in other collection views, sorted by the media files' position attribute.

Throws ForbiddenException if the user is not enabled to view this playlist due to bad subscription state or missing AudioMash link.

Throws ResourceNotFoundException if the playlist does not exists.

Parameters
audioBoxClient the AudioBoxClient to use for the request
Returns
Throws
AudioBoxException if any of the remote error exception is detected.
IOException if any connection problem occurs.
See Also

public Artists getArtists (AudioBoxClient audioBoxClient)

Gets media files grouped by albums.

Also includes the same media file entities in other collection views, sorted by the media files' position attribute.

Throws ForbiddenException if the user is not enabled to view this playlist due to bad subscription state or missing AudioMash link.

Throws ResourceNotFoundException if the playlist does not exists.

Parameters
audioBoxClient the AudioBoxClient to use for the request
Returns
Throws
AudioBoxException if any of the remote error exception is detected.
IOException if any connection problem occurs.
See Also

public String getDescription ()

Gets this playlist brief description.

public List<? extends MediaFile> getFingerprints (AudioBoxClient audioBoxClient)

Returns known file fingerprints for this playlist. Available only for local and cloud playlist tokens.

Will return all MD5 fingerprints of the media files on this playlist. Useful to know what has already been uploaded.

Parameters
audioBoxClient the AudioBoxClient to use for the request
Returns
Throws
AudioBoxException if any of the remote error exception is detected.
IOException if any connection problem occurs.
See Also

public List<? extends MediaFile> getFingerprints (AudioBoxClient audioBoxClient, JsonObjectParser parser)

Returns known file fingerprints for this playlist. Available only for local and cloud playlist tokens.

Will return all MD5 fingerprints of the media files on this playlist. Useful to know what has already been uploaded.

Parameters
audioBoxClient the AudioBoxClient to use for the request
parser the parser to use to parse the response
Returns
Throws
AudioBoxException if any of the remote error exception is detected.
IOException if any connection problem occurs.
See Also

public Genres getGenres (AudioBoxClient audioBoxClient)

Gets media files grouped by albums.

Also includes the same media file entities in other collection views, sorted by the media files' position attribute.

Throws ForbiddenException if the user is not enabled to view this playlist due to bad subscription state or missing AudioMash link.

Throws ResourceNotFoundException if the playlist does not exists.

Parameters
audioBoxClient the AudioBoxClient to use for the request
Returns
Throws
AudioBoxException if any of the remote error exception is detected.
IOException if any connection problem occurs.
See Also

public List<MediaFile> getMediaFiles (AudioBoxClient audioBoxClient, long since)

Same as getMediaFiles(fm.audiobox.core.AudioBoxClient, long, String) but all media file fields are returned.
Time filter is applied.

Parameters
audioBoxClient the client to use for the request
since unix timestamp that filters the collection and returns records modified since the specified date.
Returns
Throws
AudioBoxException if any of the remote error exception is detected.
IOException if any connection problem occurs.
See Also

public List<MediaFile> getMediaFiles (AudioBoxClient audioBoxClient, long since, String set)

Returns media files linked to the specified playlist token along with primary information.

This does not return all the attributes for a MediaFile, instead it returns an optimized JSON for fast view-level rendering and parsing purposes. Full details about a particular MediaFile can be obtained by calling the dedicated show endpoint.

Supports a comma separated 'set' parameter which indicates which attributes to render, like 'type,token' so a developer can just ask the needed attributes.

Supports a datetime 'since' parameter that filters the collection and returns records modified since the specified date.

Remote and third party Cloud Storage services' content can be accessed through this endpoint, however an error will be returned if the user has no valid authentication information stored towards the service in question or has an invalid subscription. For example if the user tries to access the Dropbox playlist but he has not the related account linked a ForbiddenException will be thrown, along with the subscription status. Valid subscription statuses are active and trialing.

Parameters
audioBoxClient the client to use for the request
since unix timestamp that filters the collection and returns records modified since the specified date.
set comma separated 'set' parameter which indicates which attributes to render, like 'type,token', null will return all available fields.
Returns
Throws
AudioBoxException if any of the remote error exception is detected.
IOException if any connection problem occurs.
See Also

public List<MediaFile> getMediaFiles (AudioBoxClient audioBoxClient, long since, String set, JsonObjectParser parser)

Returns media files linked to the specified playlist token along with primary information.

This does not return all the attributes for a MediaFile, instead it returns an optimized JSON for fast view-level rendering and parsing purposes. Full details about a particular MediaFile can be obtained by calling the dedicated show endpoint.

Supports a comma separated 'set' parameter which indicates which attributes to render, like 'type,token' so a developer can just ask the needed attributes.

Supports a datetime 'since' parameter that filters the collection and returns records modified since the specified date.

Remote and third party Cloud Storage services' content can be accessed through this endpoint, however an error will be returned if the user has no valid authentication information stored towards the service in question or has an invalid subscription. For example if the user tries to access the Dropbox playlist but he has not the related account linked a ForbiddenException will be thrown, along with the subscription status. Valid subscription statuses are active and trialing.

Parameters
audioBoxClient the client to use for the request
since unix timestamp that filters the collection and returns records modified since the specified date.
set comma separated 'set' parameter which indicates which attributes to render, like 'type,token', null will return all available fields.
parser the parser to use to parse the response
Returns
Throws
AudioBoxException if any of the remote error exception is detected.
IOException if any connection problem occurs.
See Also

public List<MediaFile> getMediaFiles (AudioBoxClient audioBoxClient, JsonObjectParser parser)

Returns media files linked to the specified playlist token along with primary information.

This does not return all the attributes for a MediaFile, instead it returns an optimized JSON for fast view-level rendering and parsing purposes. Full details about a particular MediaFile can be obtained by calling the dedicated show endpoint.

Supports a comma separated 'set' parameter which indicates which attributes to render, like 'type,token' so a developer can just ask the needed attributes.

Supports a datetime 'since' parameter that filters the collection and returns records modified since the specified date.

Remote and third party Cloud Storage services' content can be accessed through this endpoint, however an error will be returned if the user has no valid authentication information stored towards the service in question or has an invalid subscription. For example if the user tries to access the Dropbox playlist but he has not the related account linked a ForbiddenException will be thrown, along with the subscription status. Valid subscription statuses are active and trialing.

Parameters
audioBoxClient the client to use for the request
parser the parser to use to parse the response
Returns
Throws
AudioBoxException if any of the remote error exception is detected.
IOException if any connection problem occurs.
See Also

public List<MediaFile> getMediaFiles (AudioBoxClient audioBoxClient)

Same as getMediaFiles(fm.audiobox.core.AudioBoxClient, long, String) but all media file fields are returned and *no* time filter is applied.

Parameters
audioBoxClient the client to use for the request
Returns
Throws
AudioBoxException if any of the remote error exception is detected.
IOException if any connection problem occurs.
See Also

public long getMediaFilesCount ()

Gets media files count on this playlist.

Returns
  • the media files count

public String getName ()

Gets the playlist name.

Returns
  • the playlist name

public static String getPath ()

Gets the generic remote resource path (token interpolation needed, see interpolate(String, String) ).

Returns
  • the path String

public long getPosition ()

Gets the position of the playlist (client application should respect this field while sorting playlists).

Returns
  • the position of the playlist

public String getSystemName ()

Gets system name.

Returns
  • the system name

public String getToken ()

Gets playlist unique token.

Returns
  • the token String

public String getType ()

Gets the playlist type.

Returns
  • the type

public String getUpdatedAt ()

Gets the last time (in form of an UTC String) this playlist have been changed.
NOTE: Since client timezone may differ significantly you are strongly invited to always trust and use this datetime in case you are building a sync tool.

Returns
  • the UTC String of the last update on this playlist

public final int hashCode ()

public boolean isCustom ()

Checks if the playlist is a custom one.

Returns
  • true if the playlist is a custom playlist.

public boolean isDrive ()

Checks if the playlist represents a cloud drive.

Returns
  • true if the playlist is a cloud drive.

public boolean isEmbeddable ()

Use this method to check if the playlist is embeddable or not.

Returns
  • true if the playlist is embeddable

public boolean isLastAccessed ()

Use this method to check if the playlist is the last one accessed. (i.e. getPlaylist(String) was called at last}

Returns
  • true if this was the last accessed playlist

public boolean isOffline ()

Checks if the playlist is the offline items playlist.

Returns
  • true if the playlist is the offline playlist.

public boolean isSmart ()

Checks if the playlist is a smart one.

Returns
  • true if the playlist is a smart playlist.

public boolean isSyncable ()

Checks if this playlist supports syncing with remote content, usually valid for external storage services.

Returns
  • true if this is a syncable playlist, false otherwise

public boolean isVisible ()

Use this method to check if the playlist is visible or not.

Returns
  • true if the playlist is embeddable

public Playlist removeMediaFiles (AudioBoxClient audioBoxClient, List<String> tokens)

Remove Media Files from a CustomPlaylist.

Shallow action that requires a list of media files tokens to be removed from this playlist. Only custom playlist tokens are allowed, being the only ones for which content can be modified.
AudioBox will not remove media files not present in the destination playlist.

Parameters
audioBoxClient the AudioBoxClient to use for the request
tokens the list of the tokens string to add to this playlist
Returns
  • the playlist instance in order to chain other operations on it if needed.
Throws
IllegalStateException if the playlist is not persisted yet.
ResourceNotFoundException if the playlist not found or not of type CustomPlaylist.
AudioBoxException if any of the remote error exception is detected.
IOException if any connection problem occurs.
See Also

public Playlist setDescription (String description)

Sets a brief description of the playlist.

Parameters
description a brief String to describe this playlist
Returns
  • the playlist instance in order to chain other methods.

public Playlist setEmbeddable (boolean embeddable)

Changes embeddable value, if you want to persist the change remember to call update(fm.audiobox.core.AudioBoxClient) method.

Parameters
embeddable true to mark it as embeddable, false to disable the feature.
Returns
  • the playlist instance in order to chain other methods.

public void setLastAccessed (boolean lastAccessed)

Sets as last accessed. Note: this is a readonly field (when saving this value will be discarded) and the meaning of this method is to populate this object field (i.e. load from persisted playlist).

Parameters
lastAccessed true if the playlist was the last accessed.

public void setMediaFilesCount (long mediaFilesCount)

Sets media files count. Note: this is a readonly field (when saving this value will be discarded) and the meaning of this method is to populate this object field (i.e. load from persisted playlist).

Parameters
mediaFilesCount the media files count

public Playlist setName (String name)

Changes playlist name, if you want to persist the change remember to call update(fm.audiobox.core.AudioBoxClient) method.

Parameters
name the name
Returns
  • the playlist instance in order to chain other methods.

public Playlist setPosition (long position)

Changes position value, if you want to persist the change remember to call update(fm.audiobox.core.AudioBoxClient) method.

Parameters
position the position to set
Returns
  • the playlist instance in order to chain other methods.

public void setSyncable (boolean syncable)

Sets syncable property. Note: this is a readonly field (when saving this value will be discarded) and the meaning of this method is to populate this object field (i.e. load from persisted playlist).

Parameters
syncable the syncable

public void setSystemName (String systemName)

Sets system name. Note: this is a readonly field (when saving this value will be discarded) and the meaning of this method is to populate this object field (i.e. load from persisted playlist).

Parameters
systemName the system name

public void setToken (String token)

Sets token. Note: this is a readonly field (when saving this value will be discarded) and the meaning of this method is to populate this object field (i.e. load from persisted playlist).

Parameters
token the token

public void setType (String type)

Sets type. Note: this is a readonly field (when saving this value will be discarded) and the meaning of this method is to populate this object field (i.e. load from persisted playlist).

Parameters
type the type

public void setUpdatedAt (String updatedAt)

Sets updated at. Note: this is a readonly field (when saving this value will be discarded) and the meaning of this method is to populate this object field (i.e. load from persisted playlist).

Parameters
updatedAt last time updated

public Playlist setVisible (boolean visible)

Changes visible value, if you want to persist the change remember to call update(fm.audiobox.core.AudioBoxClient) method.

Parameters
visible true to mark it as visible, false to disable the feature.
Returns
  • the playlist instance in order to chain other methods.

public boolean sync (AudioBoxClient audioBoxClient)

Begin content sync with the remote platform. Supported only by syncable playlists.

Calling this method will initiate a job that will synchronize data with the remote storage, such as Dropbox, SkyDrive and others.

Playlists supporting official storage such as AudioBox Cloud or AudioBox Desktop does not require syncing.

Parameters
audioBoxClient the client to use for the request
Returns
  • true if operation succeeds.
Throws
SyncException if any problem occurs.
AudioBoxException if any of the remote error exception is detected.
IOException if any connection problem occurs.
See Also

public boolean toggleVisibility (AudioBoxClient audioBoxClient)

Toggle visibility mode for this playlist.

By toggling the visibility attribute clients should avoid to render the playlist marked with visible: false or grey them out.

Non visible playlists retains their functionality, they just should be hidden in views.

Parameters
audioBoxClient the client to use for the request
Returns
  • true if operation succeeds.
Throws
AudioBoxException if any of the remote error exception is detected.
IOException if any connection problem occurs.
See Also

public Playlist update (AudioBoxClient audioBoxClient)

Handle the update of a custom or smart playlist.

As a rule of thumb you can have one uniquely named playlist for each type.

SmartPlaylist's search_params can be set only on creation and thus cannot be changed, in this action.

SmartPlaylist cannot be tweaked in their search_params due to the complexity of their construct. Since SmartPlaylist are compiled on demand, just destroy the old and create a new one.

Parameters
audioBoxClient the client
Returns
  • the playlist
Throws
IllegalStateException if the playlist is not persisted yet.
ForbiddenException if no valid subscription found
ResourceNotFoundException if playlist is not found or immutable
ValidationException if playlist data is not valid (ex: name already taken)
AudioBoxException if any of the remote error exception is detected.
IOException if any connection problem occurs.
See Also