de.sfuhrm.radiobrowser4j

Class RadioBrowser

java.lang.Object

de.sfuhrm.radiobrowser4j.RadioBrowser

public final class RadioBrowser
extends Object

API facade for the RadioBrowser. You usually create a new instance and then use the methods to invoke API calls.

Author:

Stephan Fuhrmann

Field Summary

Fields

Modifier and Type	Field and Description
protected static String	API_URL The base URL of the REST service.

Constructor Summary

Constructors

Constructor and Description
RadioBrowser(int timeout, String myUserAgent) Creates a new API client.

Method Summary

Modifier and Type	Method and Description
void	deleteStation(Station station) Deletes a station.
String	editStation(Station station) Edits an existing station on the server.
Optional<Station>	getStationById(String id) Get a station referenced by the ID.
Stream<Station>	listBrokenStations() Get a list of all broken stations as one continuous stream.
List<Station>	listBrokenStations(Paging paging) Get a list of all broken stations.
Map<String,Integer>	listCodecs() List the known codecs.
Map<String,Integer>	listCountries() List the known countries.
List<Station>	listDeletedStations() Get a list of the deleted stations.
Stream<Station>	listImprovableStations() Get a list of all broken stations as one continuous stream.
List<Station>	listImprovableStations(Paging paging) Get a list of all improvable stations.
Map<String,Integer>	listLanguages() List the known languages.
Stream<Station>	listLastChangedStations() Get a stream of last changed stations.
List<Station>	listLastChangedStations(Paging paging) Get a list of the last changed stations.
Stream<Station>	listLastClickStations() Get a stream of last clicked stations.
List<Station>	listLastClickStations(Paging paging) Get a list of the last clicked stations.
Stream<Station>	listStations(ListParameter... listParam) Get a list of all stations.
List<Station>	listStations(Paging paging, ListParameter... listParam) Get a list of all stations.
List<Station>	listStationsBy(Paging paging, SearchMode searchMode, String searchTerm, ListParameter... listParam) Get a list of stations matching a certain search criteria.
Stream<Station>	listStationsBy(SearchMode searchMode, String searchTerm, ListParameter... listParam) Get a stream of stations matching a certain search criteria.
Map<String,Integer>	listTags() List the known tags.
Stream<Station>	listTopClickStations() Get a stream of all top click stations.
List<Station>	listTopClickStations(Paging paging) Get a list of the top click stations.
Stream<Station>	listTopVoteStations() Get a stream of the top vote stations.
List<Station>	listTopVoteStations(Paging paging) Get a list of the top vote stations.
String	postNewStation(Station station) Posts a new station to the server.
URL	resolveStreamUrl(Station station) Resolves the streaming URL for the given station.
void	undeleteStation(Station station) Undeletes a station.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

API_URL

protected static final String API_URL

The base URL of the REST service.

See Also:

Constant Field Values

Constructor Detail

RadioBrowser

public RadioBrowser(int timeout,
                    String myUserAgent)

Creates a new API client.

Parameters:

timeout - the timeout for connect and read requests in milliseconds. Must be greater than zero.

myUserAgent - the user agent String for your user agent. Must be something to point to you.

Method Detail

listCountries

public Map<String,Integer> listCountries()

List the known countries.

Returns:

a list of countries (keys) and country usages (values).

See Also:

API

listCodecs

public Map<String,Integer> listCodecs()

List the known codecs.

Returns:

a list of codecs (keys) and codec usages (values).

See Also:

API

listLanguages

public Map<String,Integer> listLanguages()

List the known languages.

Returns:

a list of languages (keys) and language usages (values).

See Also:

API

listTags

public Map<String,Integer> listTags()

List the known tags.

Returns:

a list of tags (keys) and tag usages (values).

See Also:

API

listStations

public List<Station> listStations(Paging paging,
                                  ListParameter... listParam)

Get a list of all stations. Will return a single batch.

Parameters:

paging - the offset and limit of the page to retrieve.

listParam - the optional listing parameters.

Returns:

the partial list of the stations. Can be empty for exceeding the possible stations.

listStations

public Stream<Station> listStations(ListParameter... listParam)

Get a list of all stations. Will return all stations in a stream..

Parameters:

listParam - the optional listing parameters.

Returns:

the full stream of stations..

listBrokenStations

public List<Station> listBrokenStations(Paging paging)

Get a list of all broken stations. Will return a single batch.

Parameters:

paging - the offset and limit of the page to retrieve.

Returns:

the partial list of the broken stations. Can be empty for exceeding the possible stations.

listBrokenStations

public Stream<Station> listBrokenStations()

Get a list of all broken stations as one continuous stream.

Returns:

the continuous stream of all broken stations.

listImprovableStations

public List<Station> listImprovableStations(Paging paging)

Get a list of all improvable stations. Will return a single batch.

Parameters:

paging - the offset and limit of the page to retrieve.

Returns:

the partial list of the improvable stations. Can be empty for exceeding the possible stations.

listImprovableStations

public Stream<Station> listImprovableStations()

Get a list of all broken stations as one continuous stream.

Returns:

the continuous stream of all improvable stations.

listTopClickStations

public List<Station> listTopClickStations(Paging paging)

Get a list of the top click stations. Will return a single batch.

Parameters:

paging - the offset and limit of the page to retrieve.

Returns:

the partial list of the top click stations. Can be empty for exceeding the possible stations.

listTopClickStations

public Stream<Station> listTopClickStations()

Get a stream of all top click stations.

Returns:

the complete stream of all top click stations.

listTopVoteStations

public List<Station> listTopVoteStations(Paging paging)

Get a list of the top vote stations. Will return a single batch.

Parameters:

paging - the offset and limit of the page to retrieve.

Returns:

the partial list of the top vote stations. Can be empty for exceeding the possible stations.

listTopVoteStations

public Stream<Station> listTopVoteStations()

Get a stream of the top vote stations.

Returns:

the complete stream of the top vote stations.

listLastClickStations

public List<Station> listLastClickStations(Paging paging)

Get a list of the last clicked stations. Will return a single batch.

Parameters:

paging - the offset and limit of the page to retrieve.

Returns:

the partial list of the last clicked stations. Can be empty for exceeding the possible stations.

listLastClickStations

public Stream<Station> listLastClickStations()

Get a stream of last clicked stations.

Returns:

the complete stream of the last clicked stations.

listLastChangedStations

public List<Station> listLastChangedStations(Paging paging)

Get a list of the last changed stations. Will return a single batch.

Parameters:

paging - the offset and limit of the page to retrieve.

Returns:

the partial list of the last clicked stations. Can be empty for exceeding the possible stations.

listLastChangedStations

public Stream<Station> listLastChangedStations()

Get a stream of last changed stations.

Returns:

the complete stream of the last changed stations.

listDeletedStations

public List<Station> listDeletedStations()

Get a list of the deleted stations. Will return a single batch.

Returns:

the partial list of the deleted stations. Can be empty for exceeding the possible stations.

getStationById

public Optional<Station> getStationById(String id)

Get a station referenced by the ID.

Parameters:

id - the id of the station to retrieve.

Returns:

an optional containing either the station or nothing. Nothing is returned if the API didn't find the station by the given ID:

listStationsBy

public List<Station> listStationsBy(Paging paging,
                                    SearchMode searchMode,
                                    String searchTerm,
                                    ListParameter... listParam)

Get a list of stations matching a certain search criteria. Will return a single batch.

Parameters:

paging - the offset and limit of the page to retrieve.

searchMode - the field to match.

searchTerm - the term to search for.

listParam - the optional listing parameters.

Returns:

the partial list of the stations. Can be empty for exceeding the number of matching stations.

listStationsBy

public Stream<Station> listStationsBy(SearchMode searchMode,
                                      String searchTerm,
                                      ListParameter... listParam)

Get a stream of stations matching a certain search criteria.

Parameters:

searchMode - the field to match.

searchTerm - the term to search for.

listParam - the optional listing parameters.

Returns:

the full stream of matching stations.

resolveStreamUrl

public URL resolveStreamUrl(Station station)

Resolves the streaming URL for the given station.

Parameters:

station - the station to retrieve the stream URL for.

Returns:

the URL of the stream.

Throws:

RadioBrowserException - if the URL could not be retrieed

deleteStation

public void deleteStation(Station station)

Deletes a station. The station is only marked as being deleted.

Parameters:

station - the station to delete from the REST service.

See Also:

The API endpoint

undeleteStation

public void undeleteStation(Station station)

Undeletes a station. The station is only marked as being deleted.

Parameters:

station - the station to delete from the REST service.

See Also:

The API endpoint

postNewStation

public String postNewStation(Station station)

Posts a new station to the server. Note: This call only transmits certain fields. The fields are: name, url, homepage, favicon, country, state, language and tags.

Parameters:

station - the station to add to the REST service.

Returns:

the id of the new station.

Throws:

RadioBrowserException - if there was a problem creating the station.

See Also:

The API endpoint

editStation

public String editStation(Station station)

Edits an existing station on the server. Note: This call only transmits certain fields. The fields are: name, url, homepage, favicon, country, state, language and tags.

Parameters:

station - the station to edit with the REST service.

Returns:

the id of the station.

Throws:

RadioBrowserException - if there was a problem editing the station.

See Also:

The API endpoint