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 Details

  • Constructor Details

    • 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. Can be determined by EndpointDiscovery.discover() or set to DEFAULT_API_URL.
      timeout - the timeout in milliseconds for connecting and reading.
      myUserAgent - the user agent string to use. Please use a user agent string that somehow points to your github project, home page, or what ever.

    • RadioBrowser

      public RadioBrowser(@NonNull @NonNull String apiUrl, int timeout, @NonNull @NonNull String myUserAgent, String proxyUri, String proxyUser, String proxyPassword)
      Creates a new API client.
      Parameters:
      apiUrl - the base URL of the API. Can be determined by EndpointDiscovery.discover() or set to DEFAULT_API_URL.
      timeout - the timeout in milliseconds for connecting and reading.
      myUserAgent - the user agent string to use. Please use a user agent string that somehow points to your github project, home page, or what ever.
      proxyUri - optional URI of the proxy server, or null if no proxy is required.
      proxyUser - optional username to authenticate with if using a proxy.
      proxyPassword - optional password to authenticate with if using a proxy

    • 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. Please use a user agent string that somehow points to your github project, home page, or what ever.

  • Method Details

    • listCountries

      public Map<String,Integer> listCountries()
      List the known countries.
      Returns:
      a list of countries (keys) and country usages (values).
      See Also:

    • listCodecs

      public Map<String,Integer> listCodecs()
      List the known codecs.
      Returns:
      a list of codecs (keys) and codec usages (values).
      See Also:

    • listLanguages

      public Map<String,Integer> listLanguages()
      List the known languages.
      Returns:
      a list of languages (keys) and language usages (values).
      See Also:

    • listTags

      public Map<String,Integer> listTags()
      List the known tags.
      Returns:
      a list of tags (keys) and tag usages (values).
      See Also:

    • 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 id of the new station.
      Throws:
      RadioBrowserException - if there was a problem creating the station.
      See Also:

    • 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.