Package 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	Description
protected static String	DEFAULT_API_URL	The base URL of the REST service.

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method	Description
Optional<Station>	getStationByUUID(@NonNull UUID uuid)	Get a station referenced by its UUID.
Stream<Station>	listBrokenStations()	Get a list of all broken stations as one continuous stream.
List<Station>	listBrokenStations(@NonNull Limit limit)	Get a list of all broken stations.
Map<String,Integer>	listCodecs()	List the known codecs.
Map<String,Integer>	listCountries()	List the known countries.
Stream<Station>	listImprovableStations()	Get a list of all broken stations as one continuous stream.
List<Station>	listImprovableStations(@NonNull Limit limit)	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(@NonNull Limit limit)	Get a list of the last changed stations.
Stream<Station>	listLastClickStations()	Get a stream of last clicked stations.
List<Station>	listLastClickStations(@NonNull Limit limit)	Get a list of the last clicked stations.
List<Station>	listStations(@NonNull Paging paging, ListParameter... listParam)	Get a list of all stations.
Stream<Station>	listStations(ListParameter... listParam)	Get a list of all stations.
List<Station>	listStationsBy(@NonNull Paging paging, @NonNull SearchMode searchMode, @NonNull String searchTerm, ListParameter... listParam)	Get a list of stations matching a certain search criteria.
Stream<Station>	listStationsBy(@NonNull SearchMode searchMode, @NonNull 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(@NonNull Limit limit)	Get a list of the top click stations.
Stream<Station>	listTopVoteStations()	Get a stream of the top vote stations.
List<Station>	listTopVoteStations(@NonNull Limit limit)	Get a list of the top vote stations.
UUID	postNewStation(@NonNull Station station)	Posts a new station to the server.
URL	resolveStreamUrl(@NonNull UUID stationUUID)	Resolves the streaming URL for the given station.
void	voteForStation(@NonNull UUID stationUUID)	Votes for a station.

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_API_URL

protected static final String DEFAULT_API_URL

The base URL of the REST service.

See Also:

Constant Field Values

Constructor Detail

RadioBrowser

public RadioBrowser(@NonNull
                    @NonNull String apiUrl,
                    int timeout,
                    @NonNull
                    @NonNull String myUserAgent)

Creates a new API client.

Parameters:

apiUrl - the base URL of the API.

timeout - the timeout in milliseconds for connecting and reading.

myUserAgent - the user agent string to use.

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(@NonNull
                                  @NonNull 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(@NonNull
                                        @NonNull Limit limit)

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

Parameters:

limit - the 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(@NonNull
                                            @NonNull Limit limit)

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

Parameters:

limit - the 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(@NonNull
                                          @NonNull Limit limit)

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

Parameters:

limit - the 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(@NonNull
                                         @NonNull Limit limit)

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

Parameters:

limit - the 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(@NonNull
                                           @NonNull Limit limit)

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

Parameters:

limit - the 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(@NonNull
                                             @NonNull Limit limit)

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

Parameters:

limit - the 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.

getStationByUUID

public Optional<Station> getStationByUUID(@NonNull
                                          @NonNull UUID uuid)

Get a station referenced by its UUID.

Parameters:

uuid - the UUID 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(@NonNull
                                    @NonNull Paging paging,
                                    @NonNull
                                    @NonNull SearchMode searchMode,
                                    @NonNull
                                    @NonNull 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(@NonNull
                                      @NonNull SearchMode searchMode,
                                      @NonNull
                                      @NonNull 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(@NonNull
                            @NonNull UUID stationUUID)

Resolves the streaming URL for the given station.

Parameters:

stationUUID - the station UUID to retrieve the stream URL for.

Returns:

the URL of the stream.

Throws:

RadioBrowserException - if the URL could not be retrieved

postNewStation

public UUID postNewStation(@NonNull
                           @NonNull 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 Station#getStationUUID() id} of the new station.

Throws:

RadioBrowserException - if there was a problem creating the station.

See Also:

The API endpoint

voteForStation

public void voteForStation(@NonNull
                           @NonNull UUID stationUUID)

Votes for a station.

Parameters:

stationUUID - The uuid of the station to vote for.

Throws:

RadioBrowserException - if there was a problem voting for the station.