Java tutorial
/** * */ package me.iste.subsonicdialer; import java.io.File; import java.io.IOException; import java.io.InputStream; import java.net.HttpURLConnection; import java.util.ArrayList; import java.util.List; import me.iste.subsonicdialer.exception.DownloadException; import me.iste.subsonicdialer.exception.SubsonicException; import me.iste.subsonicdialer.util.DownloadObserver; import me.iste.subsonicdialer.util.Downloader; import me.iste.subsonicdialer.util.Parameter; import me.iste.subsonicdialer.xml.Channel; import me.iste.subsonicdialer.xml.ChatMessage; import me.iste.subsonicdialer.xml.Child; import me.iste.subsonicdialer.xml.Directory; import me.iste.subsonicdialer.xml.Indexes; import me.iste.subsonicdialer.xml.JukeboxPlaylist; import me.iste.subsonicdialer.xml.JukeboxStatus; import me.iste.subsonicdialer.xml.License; import me.iste.subsonicdialer.xml.MusicFolder; import me.iste.subsonicdialer.xml.NowPlaying; import me.iste.subsonicdialer.xml.Playlist; import me.iste.subsonicdialer.xml.SearchResult; import me.iste.subsonicdialer.xml.Share; import me.iste.subsonicdialer.xml.User; import org.jdom2.Document; import org.jdom2.JDOMException; import org.jdom2.input.SAXBuilder; /** * @author Iste * @version 1.2 27 avr. 2012 * */ public class SubsonicDialer { private static final String PATH_PING = "ping"; private static final String PATH_LICENSE = "getLicense"; private static final String PATH_GET_MUSIC_FOLDERS = "getMusicFolders"; private static final String PATH_GET_NOW_PLAYING = "getNowPlaying"; private static final String PATH_GET_INDEXES = "getIndexes"; private static final String PATH_GET_MUSIC_DIR = "getMusicDirectory"; private static final String PATH_SEARCH = "search"; private static final String PATH_SEARCH2 = "search2"; private static final String PATH_GET_PLAYLISTS = "getPlaylists"; private static final String PATH_GET_PLAYLIST = "getPlaylist"; private static final String PATH_CREATE_PLAYLIST = "createPlaylist"; private static final String PATH_DELETE_PLAYLIST = "deletePlaylist"; private static final String PATH_DOWNLOAD = "download"; private static final String PATH_STREAM = "stream"; private static final String PATH_GET_COVER_ART = "getCoverArt"; private static final String PATH_SCROBBLE = "scrobble"; private static final String PATH_CHANGE_PASSWORD = "changePassword"; private static final String PATH_GET_USER = "getUser"; private static final String PATH_CREATE_USER = "createUser"; private static final String PATH_DELETE_USER = "deleteUser"; private static final String PATH_GET_CHAT_MESSAGES = "getChatMessages"; private static final String PATH_ADD_CHAT_MESSAGE = "addChatMessage"; private static final String PATH_GET_ALBUM_LIST = "getAlbumList"; private static final String PATH_GET_RANDOM_SONGS = "getRandomSongs"; private static final String PATH_GET_LYRICS = "getLyrics"; private static final String PATH_JUKEBOCCONTROL = "jukeboxControl"; private static final String PATH_GET_PODCASTS = "getPodcasts"; private static final String PATH_GET_SHARES = "getShares"; private static final String PATH_CREATE_SHARE = "createShare"; private static final String PATH_UPDATE_SHARE = "updateShare"; private static final String PATH_DELETE_SHARE = "deleteShare"; private static final String PATH_SET_RATING = "setRating"; private SubsonicConnection connection; private String serverVersion; private Downloader downloader; /** * @param connection * @throws SubsonicException * @throws IOException * @throws JDOMException */ public SubsonicDialer(final SubsonicConnection connection) throws JDOMException, IOException, SubsonicException { this.connection = connection; this.downloader = new Downloader(); } /** * Used to test connectivity with the server. * * @return ping in ms. * @throws SubsonicException * @throws IOException * @throws JDOMException * @Since 1.0.0 */ public long ping() throws JDOMException, IOException, SubsonicException { final long start = System.currentTimeMillis(); send(PATH_PING); final long end = System.currentTimeMillis(); return end - start; } /** * Get details about the software license. Please note that access to the REST API requires that the server has a valid license (after a 30-day trial period). To get a license key you can give a * donation to the Subsonic project. * * @return The license. * @throws SubsonicException * @throws IOException * @throws JDOMException * @Since 1.0.0 */ public License getLicense() throws JDOMException, IOException, SubsonicException { final Document document = send(PATH_LICENSE); return Factory.createLicense(document); } /** * Returns all configured top-level music folders. * * @return The folders names. * @throws SubsonicException * @throws IOException * @throws JDOMException * @Since 1.0.0 */ public MusicFolder[] getMusicFolders() throws JDOMException, IOException, SubsonicException { final Document document = send(PATH_GET_MUSIC_FOLDERS); return Factory.createMusicFolders(document); } /** * Returns what is currently being played by all users. * * @return The folders names. * @throws SubsonicException * @throws IOException * @throws JDOMException * @Since 1.0.0 */ public NowPlaying[] getNowPlaying() throws JDOMException, IOException, SubsonicException { final Document document = send(PATH_GET_NOW_PLAYING); return Factory.createNowPlaying(document); } /** * Returns an indexed structure of all artists. * * @param musicFolder If specified, only return artists in the music folder. See getMusicFolders. * @param ifModifiedSince If specified, only return a result if the artist collection has changed since the given time. * * @return an indexed structure of all artists. * @throws SubsonicException * @throws IOException * @throws JDOMException * @Since 1.0.0 */ public Indexes getIndexes(final String musicFolder, final String ifModifiedSince) throws JDOMException, IOException, SubsonicException { final List<Parameter> parameters = new ArrayList<Parameter>(); if (musicFolder != null) { parameters.add(new Parameter("musicFolderId", musicFolder)); } if (ifModifiedSince != null) { parameters.add(new Parameter("ifModifiedSince", ifModifiedSince)); } final Document document = send(PATH_GET_INDEXES, parameters); return Factory.createIndexes(document); } /** * Returns a listing of all files in a music directory. Typically used to get list of albums for an artist, or list of songs for an album. * @param musicFolder The parent {@link MusicFolder}. Required. * * @return a listing of all files in a music directory. * @throws SubsonicException * @throws IOException * @throws JDOMException * @Since 1.0.0 */ public Directory getMusicDirectory(final String musicFolder) throws JDOMException, IOException, SubsonicException { final List<Parameter> parameters = new ArrayList<Parameter>(); if (musicFolder != null) { parameters.add(new Parameter("id", musicFolder)); } final Document document = send(PATH_GET_MUSIC_DIR, parameters); return Factory.createMusicDirectory(document); } /** * Returns a listing of files matching the given search criteria. Supports paging through the result. * @param artist Artist to search for. * @param album Album to searh for. * @param title Song title to search for. * @param any Searches all fields. * @param count Maximum number of results to return. Default 20. * @param offset Search result offset. Used for paging. Default 0. * @param newerThan Only return matches that are newer than this. Given as milliseconds since 1970. * * @return a listing of files matching the given search criteria. * @throws SubsonicException * @throws IOException * @throws JDOMException * @Since 1.0.0 * @deprecated since 1.4.0, use search2 instead. */ public Child[] search(final String artist, final String album, final String title, final String any, final String count, final String offset, final String newerThan) throws JDOMException, IOException, SubsonicException { final List<Parameter> parameters = new ArrayList<Parameter>(); if (artist != null) { parameters.add(new Parameter("artist", artist)); } if (album != null) { parameters.add(new Parameter("album", album)); } if (title != null) { parameters.add(new Parameter("title", title)); } if (any != null) { parameters.add(new Parameter("any", any)); } if (count != null) { parameters.add(new Parameter("count", count)); } if (offset != null) { parameters.add(new Parameter("offset", offset)); } if (newerThan != null) { parameters.add(new Parameter("newerThan", newerThan)); } final Document document = send(PATH_SEARCH, parameters); return Factory.createSearch(document); } /** * Returns albums, artists and songs matching the given search criteria. Supports paging through the result. * @param query Search query. Required. * @param artistCount Maximum number of artists to return. Default 20. * @param artistOffset Search result offset for artists. Used for paging. Default 0. * @param albumCount Maximum number of albums to return. Default 20. * @param albumOffset Search result offset for albums. Used for paging. Default 0. * @param songCount Maximum number of songs to return. Default 20. * @param songOffset Search result offset for songs. Used for paging. Default 0. * * @return albums, artists and songs matching the given search criteria. * @throws SubsonicException * @throws IOException * @throws JDOMException * @Since 1.4.0 */ public SearchResult search2(final String query, final String artistCount, final String artistOffset, final String albumCount, final String albumOffset, final String songCount, final String songOffset) throws JDOMException, IOException, SubsonicException { final List<Parameter> parameters = new ArrayList<Parameter>(); if (query != null) { parameters.add(new Parameter("query", query)); } if (artistCount != null) { parameters.add(new Parameter("artistCount", artistCount)); } if (artistOffset != null) { parameters.add(new Parameter("artistOffset", artistOffset)); } if (albumCount != null) { parameters.add(new Parameter("albumCount", albumCount)); } if (albumOffset != null) { parameters.add(new Parameter("albumOffset", albumOffset)); } if (songCount != null) { parameters.add(new Parameter("songCount", songCount)); } if (songOffset != null) { parameters.add(new Parameter("songOffset", songOffset)); } final Document document = send(PATH_SEARCH2, parameters); return Factory.createSearch2(document); } /** * Returns all saved playlists. * @return Array of {@link Playlist}. * @throws SubsonicException * @throws IOException * @throws JDOMException * @Since 1.0.0 */ public Playlist[] getPlaylists() throws JDOMException, IOException, SubsonicException { final Document document = send(PATH_GET_PLAYLISTS); return Factory.createPlaylists(document); } /** * Returns a listing of files in a saved playlist. * @param id ID of the playlist to return, as obtained by getPlaylists. Required. * @return Array of {@link Child}. * @throws SubsonicException * @throws IOException * @throws JDOMException * @Since 1.0.0 */ public Playlist getPlaylist(final String id) throws JDOMException, IOException, SubsonicException { final List<Parameter> parameters = new ArrayList<Parameter>(); if (id != null) { parameters.add(new Parameter("id", id)); } final Document document = send(PATH_GET_PLAYLIST, parameters); return Factory.createPlaylist(document); } /** * Creates or updates a saved playlist. * Note: The user must be authorized to create playlists (see Settings > Users > User is allowed to create and delete playlists). * @param playlistId The playlist ID. Required for updating. * @param name The human-readable name of the playlist. Required for creating. * @param songIds {@link List} of ID of the song in the playlist. Required. * * @throws SubsonicException * @throws IOException * @throws JDOMException * @Since 1.2.0 */ public void createPlaylist(final String playlistId, final String name, final List<String> songIds) throws JDOMException, IOException, SubsonicException { final List<Parameter> parameters = new ArrayList<Parameter>(); if (playlistId != null) { parameters.add(new Parameter("playlistId", playlistId)); } if (name != null) { parameters.add(new Parameter("name", name)); } if (songIds != null) { for (String id : songIds) { parameters.add(new Parameter("songId", id)); } } send(PATH_CREATE_PLAYLIST, parameters); } /** * Deletes a saved playlist. * @param id ID of the playlist to delete, as obtained by getPlaylists. Required. * * @throws SubsonicException * @throws IOException * @throws JDOMException * @Since 1.2.0 */ public void deletePlaylist(final String id) throws JDOMException, IOException, SubsonicException { final List<Parameter> parameters = new ArrayList<Parameter>(); if (id != null) { parameters.add(new Parameter("id", id)); } send(PATH_DELETE_PLAYLIST, parameters); } /** * Downloads a given media file. * @param id A string which uniquely identifies the file to download. Obtained by calls to getMusicDirectory. Required. * @param file The {@link File} where download. * @param observer A {@link DownloadObserver}. * * @throws SubsonicException * @throws IOException * @throws JDOMException * @throws DownloadException * @Since 1.0.0 */ public void download(final String id, final File file, final DownloadObserver observer) throws JDOMException, IOException, SubsonicException, DownloadException { final List<Parameter> parameters = new ArrayList<Parameter>(); if (id != null) { parameters.add(new Parameter("id", id)); } download(PATH_DOWNLOAD, parameters, file, observer); } /** * Streams a given media file. * @param id A string which uniquely identifies the file to stream. Obtained by calls to getMusicDirectory. Required. * @param maxBitRate (Since 1.2.0) If specified, the server will attempt to limit the bitrate to this value, in kilobits per second. If set to zero, no limit is imposed. * @param format (Since 1.6.0) Specifies the preferred target format (e.g., "mp3" or "flv") in case there are multiple applicable transcodings. * @param timeOffset Only applicable to video streaming. If specified, start streaming at the given offset (in seconds) into the video. Typically used to implement video skipping. * @param size (Since 1.6.0) Only applicable to video streaming. Requested video size specified as WxH, for instance "640x480". * @param file The {@link File} where download. * @param observer A {@link DownloadObserver}. * * @throws SubsonicException * @throws IOException * @throws JDOMException * @throws DownloadException * @Since 1.0.0 */ public void stream(final String id, final String maxBitRate, final String format, final String timeOffset, final String size, final File file, final DownloadObserver observer) throws JDOMException, IOException, SubsonicException, DownloadException { final List<Parameter> parameters = new ArrayList<Parameter>(); if (id != null) { parameters.add(new Parameter("id", id)); } if (maxBitRate != null) { parameters.add(new Parameter("maxBitRate", maxBitRate)); } if (format != null) { parameters.add(new Parameter("format", format)); } if (timeOffset != null) { parameters.add(new Parameter("timeOffset", timeOffset)); } if (size != null) { parameters.add(new Parameter("size", size)); } download(PATH_STREAM, parameters, file, observer); } /** * Returns a cover art image. * @param id A string which uniquely identifies the cover art file to download. Obtained by calls to getMusicDirectory. Required. * @param size If specified, scale image to this size. * @param file The {@link File} where download. * @param observer A {@link DownloadObserver}. * * @throws SubsonicException * @throws IOException * @throws JDOMException * @throws DownloadException * @Since 1.0.0 */ public void getCoverArt(final String id, final String size, final File file, final DownloadObserver observer) throws JDOMException, IOException, SubsonicException, DownloadException { final List<Parameter> parameters = new ArrayList<Parameter>(); if (id != null) { parameters.add(new Parameter("id", id)); } if (size != null) { parameters.add(new Parameter("size", size)); } download(PATH_GET_COVER_ART, parameters, file, observer); } /** * Returns a cover art image. * @param id A string which uniquely identifies the file to scrobble. Required. * @param submission Whether this is a "submission" or a "now playing" notification. Default "True". * * @throws SubsonicException * @throws IOException * @throws JDOMException * @Since 1.5.0 */ public void scrobble(final String id, final String submission) throws JDOMException, IOException, SubsonicException { final List<Parameter> parameters = new ArrayList<Parameter>(); if (id != null) { parameters.add(new Parameter("id", id)); } if (submission != null) { parameters.add(new Parameter("submission", submission)); } send(PATH_SCROBBLE, parameters); } /** * Changes the password of an existing Subsonic user, using the following parameters. You can only change your own password unless you have admin privileges. * @param username The name of the user which should change its password. Required. * @param password The new password of the new user, either in clear text of hex-encoded (see above). Required. * * @throws SubsonicException * @throws IOException * @throws JDOMException * @Since 1.1.0 */ public void changePassword(final String username, final String password) throws JDOMException, IOException, SubsonicException { final List<Parameter> parameters = new ArrayList<Parameter>(); if (username != null) { parameters.add(new Parameter("username", username)); } if (password != null) { parameters.add(new Parameter("password", password)); } send(PATH_CHANGE_PASSWORD, parameters); } /** * Get details about a given user, including which authorization roles it has. Can be used to enable/disable certain features in the client, such as jukebox control. * @param username The name of the user to retrieve. You can only retrieve your own user unless you have admin privileges. Required. * @return An {@link User} object. * * @throws SubsonicException * @throws IOException * @throws JDOMException * @Since 1.3.0 */ public User getUser(final String username) throws JDOMException, IOException, SubsonicException { final List<Parameter> parameters = new ArrayList<Parameter>(); if (username != null) { parameters.add(new Parameter("username", username)); } final Document document = send(PATH_GET_USER, parameters); return Factory.createUser(document); } /** * Creates a new Subsonic user * @param username The name of the new user. Required. * @param password The password of the new user, either in clear text of hex-encoded (see above). Required. * @param ldapAuthenticated Whether the user is authenicated in LDAP. Default "false". * @param adminRole Whether the user is administrator. Default "false". * @param settingsRole Whether the user is allowed to change settings and password. Default "true". * @param streamRole Whether the user is allowed to play files. Default "true". * @param jukeboxRole Whether the user is allowed to play files in jukebox mode. Default "false". * @param downloadRole Whether the user is allowed to download files. Default "false". * @param uploadRole Whether the user is allowed to upload files. Default "false". * @param playlistRole Whether the user is allowed to create and delete playlists. Default "false". * @param coverArtRole Whether the user is allowed to change cover art and tags. Default "false". * @param commentRole Whether the user is allowed to create and edit comments and ratings. Default "false". * @param podcastRole Whether the user is allowed to administrate Podcasts. Default "false". * @param shareRole (Since 1.8.0) Whether the user is allowed to share files with anyone. Default "false". * * @throws SubsonicException * @throws IOException * @throws JDOMException * @Since 1.1.0 */ public void createUser(final String username, final String password, final String ldapAuthenticated, final String adminRole, final String settingsRole, final String streamRole, final String jukeboxRole, final String downloadRole, final String uploadRole, final String playlistRole, final String coverArtRole, final String commentRole, final String podcastRole, final String shareRole) throws JDOMException, IOException, SubsonicException { final List<Parameter> parameters = new ArrayList<Parameter>(); if (username != null) { parameters.add(new Parameter("username", username)); } if (password != null) { parameters.add(new Parameter("password", username)); } if (ldapAuthenticated != null) { parameters.add(new Parameter("ldapAuthenticated", ldapAuthenticated)); } if (adminRole != null) { parameters.add(new Parameter("adminRole", adminRole)); } if (settingsRole != null) { parameters.add(new Parameter("settingsRole", settingsRole)); } if (streamRole != null) { parameters.add(new Parameter("streamRole", streamRole)); } if (jukeboxRole != null) { parameters.add(new Parameter("jukeboxRole", jukeboxRole)); } if (downloadRole != null) { parameters.add(new Parameter("downloadRole", downloadRole)); } if (uploadRole != null) { parameters.add(new Parameter("uploadRole", uploadRole)); } if (playlistRole != null) { parameters.add(new Parameter("playlistRole", playlistRole)); } if (coverArtRole != null) { parameters.add(new Parameter("coverArtRole", coverArtRole)); } if (commentRole != null) { parameters.add(new Parameter("commentRole", commentRole)); } if (podcastRole != null) { parameters.add(new Parameter("podcastRole", podcastRole)); } if (shareRole != null) { parameters.add(new Parameter("shareRole", shareRole)); } send(PATH_CREATE_USER, parameters); } /** * Deletes an existing Subsonic user * @param username The name of the user to delete. Required. * * @throws SubsonicException * @throws IOException * @throws JDOMException * @Since 1.3.0 */ public void deleteUser(final String username) throws JDOMException, IOException, SubsonicException { final List<Parameter> parameters = new ArrayList<Parameter>(); if (username != null) { parameters.add(new Parameter("username", username)); } send(PATH_DELETE_USER, parameters); } /** * Returns the current visible (non-expired) chat messages. * @param since Only return messages newer than this time (in millis since Jan 1 1970). * @return Array of {@link ChatMessage}. * * @throws SubsonicException * @throws IOException * @throws JDOMException * @Since 1.2.0 */ public ChatMessage[] getChatMessages(final String since) throws JDOMException, IOException, SubsonicException { final List<Parameter> parameters = new ArrayList<Parameter>(); if (since != null) { parameters.add(new Parameter("since", since)); } final Document document = send(PATH_GET_CHAT_MESSAGES, parameters); return Factory.createChatMessages(document); } /** * Adds a message to the chat log. * @param message The chat message. Required. * * @throws SubsonicException * @throws IOException * @throws JDOMException * @Since 1.2.0 */ public void addChatMessage(final String message) throws JDOMException, IOException, SubsonicException { final List<Parameter> parameters = new ArrayList<Parameter>(); if (message != null) { parameters.add(new Parameter("message", message)); } send(PATH_ADD_CHAT_MESSAGE, parameters); } /** * Returns a list of random, newest, highest rated etc. albums. Similar to the album lists on the home page of the Subsonic web interface. * @param type The list type. Must be one of the following: random, newest, highest, frequent, recent. Required. * @param size The number of albums to return. Max 500. Default 10. * @param offset The list offset. Useful if you for example want to page through the list of newest albums. Max 5000. Default 0. * @return Array of {@link Child}. * * @throws SubsonicException * @throws IOException * @throws JDOMException * @Since 1.2.0 */ public Child[] getAlbumList(final String type, final String size, final String offset) throws JDOMException, IOException, SubsonicException { final List<Parameter> parameters = new ArrayList<Parameter>(); if (type != null) { parameters.add(new Parameter("type", type)); } if (size != null) { parameters.add(new Parameter("size", size)); } if (offset != null) { parameters.add(new Parameter("offset", offset)); } final Document document = send(PATH_GET_ALBUM_LIST, parameters); return Factory.createAlbumList(document); } /** * Returns random songs matching the given criteria. * @param size The maximum number of songs to return. Max 500. Default 10. * @param genre Only returns songs belonging to this genre. * @param fromYear Only return songs published after or in this year. * @param toYear Only return songs published before or in this year. * @param musicFolderId Only return songs in the music folder with the given ID. See getMusicFolders. * @return Array of {@link Child}. * * @throws SubsonicException * @throws IOException * @throws JDOMException * @Since 1.2.0 */ public Child[] getRandomSongs(final String size, final String genre, final String fromYear, final String toYear, final String musicFolderId) throws JDOMException, IOException, SubsonicException { final List<Parameter> parameters = new ArrayList<Parameter>(); if (size != null) { parameters.add(new Parameter("size", size)); } if (genre != null) { parameters.add(new Parameter("genre", genre)); } if (fromYear != null) { parameters.add(new Parameter("fromYear", fromYear)); } if (toYear != null) { parameters.add(new Parameter("toYear", toYear)); } if (musicFolderId != null) { parameters.add(new Parameter("musicFolderId", musicFolderId)); } final Document document = send(PATH_GET_RANDOM_SONGS, parameters); return Factory.createRandomSongs(document); } /** * Searches for and returns lyrics for a given song. * @param artist The artist name. * @param title The song title. * @return The lyrics. * * @throws SubsonicException * @throws IOException * @throws JDOMException * @Since 1.2.0 */ public String getLyrics(final String artist, final String title) throws JDOMException, IOException, SubsonicException { final List<Parameter> parameters = new ArrayList<Parameter>(); if (artist != null) { parameters.add(new Parameter("artist", artist)); } if (title != null) { parameters.add(new Parameter("title", title)); } final Document document = send(PATH_GET_LYRICS, parameters); return Factory.createLyrics(document); } /** * Searches for and returns lyrics for a given song. * @param action The operation to perform. Must be one of: get, status (since 1.7.0), set (since 1.7.0), start, stop, skip, add, clear, remove, shuffle, setGain. Required. * @param index Used by skip and remove. Zero-based index of the song to skip to or remove. * @param offset (Since 1.7.0) Used by skip. Start playing this many seconds into the track. * @param id Used by add and set. ID of song to add to the jukebox playlist. (set is similar to a clear followed by a add, but will not change the currently playing track.) * @param gain Used by setGain to control the playback volume. A float value between 0.0 and 1.0. * @return A {@link JukeboxStatus} object or a {@link JukeboxPlaylist} if action = get. * * @throws SubsonicException * @throws IOException * @throws JDOMException * @Since 1.2.0 */ public JukeboxStatus jukeboxControl(final String action, final String index, final String offset, final List<String> id, final String gain) throws JDOMException, IOException, SubsonicException { final List<Parameter> parameters = new ArrayList<Parameter>(); if (action != null) { parameters.add(new Parameter("action", action)); } if (index != null) { parameters.add(new Parameter("index", index)); } if (offset != null) { parameters.add(new Parameter("offset", offset)); } if (id != null) { for (String value : id) { parameters.add(new Parameter("id", value)); } } if (gain != null) { parameters.add(new Parameter("gain", gain)); } final Document document = send(PATH_JUKEBOCCONTROL, parameters); return Factory.createjukeboxControl(document); } /** * Returns all podcast channels the server subscribes to and their episodes. * @return Array of {@link Channel}. * * @throws SubsonicException * @throws IOException * @throws JDOMException * @Since 1.6.0 */ public Channel[] getPodcasts() throws JDOMException, IOException, SubsonicException { final Document document = send(PATH_GET_PODCASTS); return Factory.createPodcasts(document); } /** * Returns information about shared media this user is allowed to manage. * @return Array of {@link Channel}. * * @throws SubsonicException * @throws IOException * @throws JDOMException * @Since 1.6.0 */ public Share[] getShares() throws JDOMException, IOException, SubsonicException { final Document document = send(PATH_GET_SHARES); return Factory.createShares(document); } /** * Creates a public URL that can be used by anyone to stream music or video from the Subsonic server. The URL is short and suitable for posting on Facebook, Twitter etc. Note: The user must be authorized to share (see Settings > Users > User is allowed to share files with anyone). * @param id ID of a song, album or video to share. Required. * @param description A user-defined description that will be displayed to people visiting the shared media. * @param expires The time at which the share expires. Given as milliseconds since 1970. * @return The {@link Channel}. * * @throws SubsonicException * @throws IOException * @throws JDOMException * @Since 1.6.0 */ public Share createShare(final List<String> id, final String description, final String expires) throws JDOMException, IOException, SubsonicException { final List<Parameter> parameters = new ArrayList<Parameter>(); if (id != null) { for (String value : id) { parameters.add(new Parameter("id", value)); } } if (description != null) { parameters.add(new Parameter("description", description)); } if (expires != null) { parameters.add(new Parameter("expires", expires)); } final Document document = send(PATH_CREATE_SHARE, parameters); return Factory.createNewShares(document); } /** * Updates the description and/or expiration date for an existing share. * @param id ID of the share to update. Required. * @param description A user-defined description that will be displayed to people visiting the shared media. * @param expires The time at which the share expires. Given as milliseconds since 1970. * * @throws SubsonicException * @throws IOException * @throws JDOMException * @Since 1.6.0 */ public void updateShare(final String id, final String description, final String expires) throws JDOMException, IOException, SubsonicException { final List<Parameter> parameters = new ArrayList<Parameter>(); if (id != null) { parameters.add(new Parameter("id", id)); } if (description != null) { parameters.add(new Parameter("description", description)); } if (expires != null) { parameters.add(new Parameter("expires", expires)); } send(PATH_UPDATE_SHARE, parameters); } /** * Deletes an existing share. * @param id ID of the share to delete. Required. * * @throws SubsonicException * @throws IOException * @throws JDOMException * @Since 1.6.0 */ public void deleteShare(final String id) throws JDOMException, IOException, SubsonicException { final List<Parameter> parameters = new ArrayList<Parameter>(); if (id != null) { parameters.add(new Parameter("id", id)); } send(PATH_DELETE_SHARE, parameters); } /** * Sets the rating for a music file. * @param id A string which uniquely identifies the file (song) or folder (album/artist) to rate. Required. * @param rating The rating between 1 and 5 (inclusive), or 0 to remove the rating. Required. * * @throws SubsonicException * @throws IOException * @throws JDOMException * @Since 1.6.0 */ public void setRating(final String id, final String rating) throws JDOMException, IOException, SubsonicException { final List<Parameter> parameters = new ArrayList<Parameter>(); if (id != null) { parameters.add(new Parameter("id", id)); } if (rating != null) { parameters.add(new Parameter("rating", rating)); } send(PATH_SET_RATING, parameters); } /** * @param methode the methode. * @param parameters a {@link List} of {@link Parameter}. * @return The {@link Document}. * @throws JDOMException * @throws IOException * @throws SubsonicException */ public Document send(final String methode, final List<Parameter> parameters) throws JDOMException, IOException, SubsonicException { final HttpURLConnection httpConnection = this.connection.post(methode, parameters); final InputStream inputStream = httpConnection.getInputStream(); final SAXBuilder saxBuilder = new SAXBuilder(); final Document document = saxBuilder.build(inputStream); inputStream.close(); httpConnection.disconnect(); Factory.checkError(document); this.serverVersion = Factory.getVersion(document); return document; } /** * @param methode * @return The {@link Document}. * @throws JDOMException * @throws IOException * @throws SubsonicException */ public Document send(final String methode) throws JDOMException, IOException, SubsonicException { return send(methode, null); } /** * @param methode * @param parameters * @param file * @param observer * @throws IOException * @throws SubsonicException * @throws JDOMException * @throws DownloadException */ public void download(final String methode, final List<Parameter> parameters, final File file, final DownloadObserver observer) throws JDOMException, IOException, SubsonicException, DownloadException { this.downloader.download(this.connection.post(methode, parameters), file, observer); } /** * @param methode * @param parameters * @param file * @throws IOException * @throws SubsonicException * @throws JDOMException * @throws DownloadException */ public void download(final String methode, final List<Parameter> parameters, final File file) throws JDOMException, IOException, SubsonicException, DownloadException { download(methode, parameters, file, null); } /** * @return the serverVersion */ public String getServerVersion() { return this.serverVersion; } /** * @return the {@link SubsonicConnection} */ public SubsonicConnection getConnection() { return this.connection; } /** * @param connection the connection to set */ public void setConnection(final SubsonicConnection connection) { this.connection = connection; } /** * @return the downloader */ public Downloader getDownloader() { return this.downloader; } /** * @param downloader the downloader to set */ public void setDownloader(final Downloader downloader) { this.downloader = downloader; } }