Package de.sfuhrm.radiobrowser4j

Class 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

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