Package org.osgi.service.rest.client

Interface RestClient

@ProviderType public interface RestClient
A Java client API for a REST service endpoint.

Provides a Java client API for accessing and managing a remote OSGi framework through the REST API. Implementations of this interface will usually take the URL to the remote REST Management Service instance as an argument in their constructor. Further arguments might be needed, for example, if the cloud provider requires URL signing.

  • Method Details

    • getFrameworkStartLevel

      FrameworkStartLevelDTO getFrameworkStartLevel() throws Exception
      Retrieves the current framework start level.
      Returns:
      Returns the current framework start level in the form of a FrameworkStartLevelDTO.
      Throws:
      Exception - An exception representing a failure in the underlying REST call.

    • setFrameworkStartLevel

      void setFrameworkStartLevel(FrameworkStartLevelDTO startLevel) throws Exception
      Sets the current framework start level.
      Parameters:
      startLevel - set the framework start level to this target.
      Throws:
      Exception - An exception representing a failure in the underlying REST call.

    • getBundlePaths

      Collection<String> getBundlePaths() throws Exception
      Get the bundles currently installed on the managed framework.
      Returns:
      Returns a collection of the bundle URIs in the form of Strings. The URIs are relative to the REST API root URL and can be used to retrieve bundle representations.
      Throws:
      Exception - An exception representing a failure in the underlying REST call.

    • getBundles

      Collection<BundleDTO> getBundles() throws Exception
      Get the bundle representations for all bundles currently installed in the managed framework.
      Returns:
      Returns a collection of BundleDTO objects.
      Throws:
      Exception - An exception representing a failure in the underlying REST call.

    • getBundle

      BundleDTO getBundle(long id) throws Exception
      Retrieve the bundle representation for a given bundle Id.
      Parameters:
      id - Addresses the bundle by its identifier.
      Returns:
      A BundleDTO for the requested bundle.
      Throws:
      Exception - An exception representing a failure in the underlying REST call.

    • getBundle

      BundleDTO getBundle(String bundlePath) throws Exception
      Retrieve the bundle representation for a given bundle path.
      Parameters:
      bundlePath - Addresses the bundle by its URI path.
      Returns:
      A BundleDTO for the requested bundle.
      Throws:
      Exception - An exception representing a failure in the underlying REST call.

    • getBundleState

      int getBundleState(long id) throws Exception
      Get the state for a given bundle Id.
      Parameters:
      id - Addresses the bundle by its identifier.
      Returns:
      Returns the current bundle state as defined in (@link org.osgi.framework.Bundle}.
      Throws:
      Exception - An exception representing a failure in the underlying REST call.

    • getBundleState

      int getBundleState(String bundlePath) throws Exception
      Get the state for a given bundle path.
      Parameters:
      bundlePath - Addresses the bundle by its URI path.
      Returns:
      Returns the current bundle state as defined in (@link org.osgi.framework.Bundle}.
      Throws:
      Exception - An exception representing a failure in the underlying REST call.

    • startBundle

      void startBundle(long id) throws Exception
      Start a bundle given by its bundle Id.
      Parameters:
      id - Addresses the bundle by its identifier.
      Throws:
      Exception - An exception representing a failure in the underlying REST call.

    • startBundle

      void startBundle(String bundlePath) throws Exception
      Start a bundle given by its URI path.
      Parameters:
      bundlePath - Addresses the bundle by its URI path.
      Throws:
      Exception - An exception representing a failure in the underlying REST call.

    • startBundle

      void startBundle(long id, int options) throws Exception
      Start a bundle given by its bundle Id.
      Parameters:
      id - Addresses the bundle by its identifier.
      options - Passes additional options as defined in Bundle.start(int)
      Throws:
      Exception - An exception representing a failure in the underlying REST call.

    • startBundle

      void startBundle(String bundlePath, int options) throws Exception
      Start a bundle given by its URI path.
      Parameters:
      bundlePath - Addresses the bundle by its URI path.
      options - Passes additional options as defined in Bundle.start(int)
      Throws:
      Exception - An exception representing a failure in the underlying REST call.

    • stopBundle

      void stopBundle(long id) throws Exception
      Stop a bundle given by its bundle Id.
      Parameters:
      id - Addresses the bundle by its identifier.
      Throws:
      Exception - An exception representing a failure in the underlying REST call.

    • stopBundle

      void stopBundle(String bundlePath) throws Exception
      Stop a bundle given by its URI path.
      Parameters:
      bundlePath - Addresses the bundle by its URI path.
      Throws:
      Exception - An exception representing a failure in the underlying REST call.

    • stopBundle

      void stopBundle(long id, int options) throws Exception
      Stop a bundle given by its bundle Id.
      Parameters:
      id - Addresses the bundle by its identifier.
      options - Passes additional options as defined in Bundle.stop(int)
      Throws:
      Exception - An exception representing a failure in the underlying REST call.

    • stopBundle

      void stopBundle(String bundlePath, int options) throws Exception
      Stop a bundle given by its URI path.
      Parameters:
      bundlePath - Addresses the bundle by its URI path.
      options - Passes additional options as defined in Bundle.stop(int)
      Throws:
      Exception - An exception representing a failure in the underlying REST call.

    • getBundleHeaders

      Map<String,String> getBundleHeaders(long id) throws Exception
      Get the header for a bundle given by its bundle Id.
      Parameters:
      id - Addresses the bundle by its identifier.
      Returns:
      Returns the map of headers entries.
      Throws:
      Exception - An exception representing a failure in the underlying REST call.

    • getBundleHeaders

      Map<String,String> getBundleHeaders(String bundlePath) throws Exception
      Get the header for a bundle given by its URI path.
      Parameters:
      bundlePath - Addresses the bundle by its URI path.
      Returns:
      Returns the map of headers entries.
      Throws:
      Exception - An exception representing a failure in the underlying REST call.

    • getBundleStartLevel

      BundleStartLevelDTO getBundleStartLevel(long id) throws Exception
      Get the start level for a bundle given by its bundle Id.
      Parameters:
      id - Addresses the bundle by its identifier.
      Returns:
      Returns a BundleStartLevelDTO describing the current start level of the bundle.
      Throws:
      Exception - An exception representing a failure in the underlying REST call.

    • getBundleStartLevel

      BundleStartLevelDTO getBundleStartLevel(String bundlePath) throws Exception
      Get the start level for a bundle given by its URI path.
      Parameters:
      bundlePath - Addresses the bundle by its URI path.
      Returns:
      Returns a BundleStartLevelDTO describing the current start level of the bundle.
      Throws:
      Exception - An exception representing a failure in the underlying REST call.

    • setBundleStartLevel

      void setBundleStartLevel(long id, int startLevel) throws Exception
      Set the start level for a bundle given by its bundle Id.
      Parameters:
      id - Addresses the bundle by its identifier.
      startLevel - The target start level.
      Throws:
      Exception - An exception representing a failure in the underlying REST call.

    • setBundleStartLevel

      void setBundleStartLevel(String bundlePath, int startLevel) throws Exception
      Parameters:
      bundlePath - Addresses the bundle by its URI path.
      startLevel - The target start level.
      Throws:
      Exception - An exception representing a failure in the underlying REST call.

    • installBundle

      BundleDTO installBundle(String location) throws Exception
      Install a new bundle given by an externally reachable location string, typically describing a URL.
      Parameters:
      location - Passes the location string to retrieve the bundle content from.
      Returns:
      Returns the BundleDTO of the newly installed bundle.
      Throws:
      Exception - An exception representing a failure in the underlying REST call.

    • installBundle

      BundleDTO installBundle(String location, InputStream in) throws Exception
      Install a new bundle given by an InputStream to a bundle content.
      Parameters:
      location - Passes the location string to be used to install the new bundle.
      in - Passes the input stream to a bundle.
      Returns:
      Returns the BundleDTO of the newly installed bundle.
      Throws:
      Exception - An exception representing a failure in the underlying REST call.

    • uninstallBundle

      BundleDTO uninstallBundle(long id) throws Exception
      Uninstall a bundle given by its bundle Id.
      Parameters:
      id - Addresses the bundle by its identifier.
      Returns:
      Returns the BundleDTO of the uninstalled bundle.
      Throws:
      Exception - An exception representing a failure in the underlying REST call.

    • uninstallBundle

      BundleDTO uninstallBundle(String bundlePath) throws Exception
      Uninstall a bundle given by its URI path.
      Parameters:
      bundlePath - Addresses the bundle by its URI path.
      Returns:
      Returns the BundleDTO of the uninstalled bundle.
      Throws:
      Exception - An exception representing a failure in the underlying REST call.

    • updateBundle

      BundleDTO updateBundle(long id) throws Exception
      Updates a bundle given by its bundle Id using the bundle-internal update location.
      Parameters:
      id - Addresses the bundle by its identifier.
      Returns:
      Returns the BundleDTO of the updated bundle.
      Throws:
      Exception - An exception representing a failure in the underlying REST call.

    • updateBundle

      BundleDTO updateBundle(long id, String url) throws Exception
      Updates a bundle given by its URI path using the content at the specified URL.
      Parameters:
      id - Addresses the bundle by its identifier.
      url - The URL whose content is to be used to update the bundle.
      Returns:
      Returns the BundleDTO of the updated bundle.
      Throws:
      Exception - An exception representing a failure in the underlying REST call.

    • updateBundle

      BundleDTO updateBundle(long id, InputStream in) throws Exception
      Updates a bundle given by its bundle Id and passing the new bundle content in the form of an InputStream.
      Parameters:
      id - Addresses the bundle by its identifier.
      in - Passes an input stream to the new bundle content.
      Returns:
      Returns the BundleDTO of the updated bundle.
      Throws:
      Exception - An exception representing a failure in the underlying REST call.

    • getServicePaths

      Collection<String> getServicePaths() throws Exception
      Gets a collection of URI paths to all installed services.
      Returns:
      Returns a collection of URI paths to the installed services.
      Throws:
      Exception - An exception representing a failure in the underlying REST call.

    • getServicePaths

      Collection<String> getServicePaths(String filter) throws Exception
      Gets a collection of URI paths to all installed services.
      Parameters:
      filter - Passes a filter to restrict the result set.
      Returns:
      Returns a collection of URI paths to the installed services.
      Throws:
      Exception - An exception representing a failure in the underlying REST call.

    • getServiceReferences

      Collection<ServiceReferenceDTO> getServiceReferences() throws Exception
      Get the service representations for all services.
      Returns:
      Returns the service representations in the form of ServiceReferenceDTO objects.
      Throws:
      Exception - An exception representing a failure in the underlying REST call.

    • getServiceReferences

      Collection<ServiceReferenceDTO> getServiceReferences(String filter) throws Exception
      Get the service representations for all services.
      Parameters:
      filter - Passes a filter to restrict the result set.
      Returns:
      Returns the service representations in the form of ServiceReferenceDTO objects.
      Throws:
      Exception - An exception representing a failure in the underlying REST call.

    • getServiceReference

      ServiceReferenceDTO getServiceReference(long id) throws Exception
      Get the service representation for a service given by its service Id.
      Parameters:
      id - Addresses the service by its identifier.
      Returns:
      The service representation as ServiceReferenceDTO.
      Throws:
      Exception - An exception representing a failure in the underlying REST call.

    • getServiceReference

      ServiceReferenceDTO getServiceReference(String servicePath) throws Exception
      Get the service representation for a service given by its URI path.
      Parameters:
      servicePath - Addresses the service by its URI path.
      Returns:
      The service representation as ServiceReferenceDTO.
      Throws:
      Exception - An exception representing a failure in the underlying REST call.