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 using a specific api endpoint.
      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 using a proxy.
      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

      @Deprecated public RadioBrowser(int timeout, String myUserAgent)
      Deprecated.
      This method is deprecated since it can use an obsolete endpoint. Using the endpoint discovery and passing the result to one of the other constructors is recommended.
      Creates a new API client using the default endpoint.
      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)
      Deprecated.
      This API endpoint has been removed.
      Get a list of all improvable stations. Will return a single batch.
      Parameters:
      limit - the limit of the page to retrieve.
      Returns:
      an empty list of improvable stations as a placeholder for the removed API endpoint.

    • listImprovableStations

      @Deprecated public Stream<Station> listImprovableStations()
      Deprecated.
      This API endpoint has been removed.
      Get a list of all broken stations as one continuous stream.
      Returns:
      an empty stream of improvable stations as a placeholder for the removed API endpoint.

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

    • getServerStats

      public Stats getServerStats()
      Get the server statistics.
      Returns:
      the statistics for the configured server endpoint.

    • listStationsWithAdvancedSearch

      public Stream<Station> listStationsWithAdvancedSearch(@NonNull @NonNull AdvancedSearch advancedSearch)
      Get a stream of stations matching a certain search criteria.
      Parameters:
      advancedSearch - the advanced search query object. A builder can be created by calling AdvancedSearch.builder(), and then when you are finished AdvancedSearch.AdvancedSearchBuilder.build().
      Returns:
      the full stream of matching stations.