RestClient
Date: 2016-06-25

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 Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `org.osgi.framework.dto.BundleDTO` | `getBundle(long id)` Retrieve the bundle representation for a given bundle Id.
    `org.osgi.framework.dto.BundleDTO` | `getBundle(java.lang.String bundlePath)` Retrieve the bundle representation for a given bundle path.
    `java.util.Map<java.lang.String,java.lang.String>` | `getBundleHeaders(long id)` Get the header for a bundle given by its bundle Id.
    `java.util.Map<java.lang.String,java.lang.String>` | `getBundleHeaders(java.lang.String bundlePath)` Get the header for a bundle given by its URI path.
    `java.util.Collection<java.lang.String>` | `getBundlePaths()` Get the bundles currently installed on the managed framework.
    `java.util.Collection<org.osgi.framework.dto.BundleDTO>` | `getBundles()` Get the bundle representations for all bundles currently installed in the managed framework.
    `org.osgi.framework.startlevel.dto.BundleStartLevelDTO` | `getBundleStartLevel(long id)` Get the start level for a bundle given by its bundle Id.
    `org.osgi.framework.startlevel.dto.BundleStartLevelDTO` | `getBundleStartLevel(java.lang.String bundlePath)` Get the start level for a bundle given by its URI path.
    `int` | `getBundleState(long id)` Get the state for a given bundle Id.
    `int` | `getBundleState(java.lang.String bundlePath)` Get the state for a given bundle path.
    `org.osgi.framework.startlevel.dto.FrameworkStartLevelDTO` | `getFrameworkStartLevel()` Retrieves the current framework start level.
    `java.util.Collection<java.lang.String>` | `getServicePaths()` Gets a collection of URI paths to all installed services.
    `java.util.Collection<java.lang.String>` | `getServicePaths(java.lang.String filter)` Gets a collection of URI paths to all installed services.
    `org.osgi.framework.dto.ServiceReferenceDTO` | `getServiceReference(long id)` Get the service representation for a service given by its service Id.
    `org.osgi.framework.dto.ServiceReferenceDTO` | `getServiceReference(java.lang.String servicePath)` Get the service representation for a service given by its URI path.
    `java.util.Collection<org.osgi.framework.dto.ServiceReferenceDTO>` | `getServiceReferences()` Get the service representations for all services.
    `java.util.Collection<org.osgi.framework.dto.ServiceReferenceDTO>` | `getServiceReferences(java.lang.String filter)` Get the service representations for all services.
    `org.osgi.framework.dto.BundleDTO` | `installBundle(java.lang.String location)` Install a new bundle given by an externally reachable location string, typically describing a URL.
    `org.osgi.framework.dto.BundleDTO` | `installBundle(java.lang.String location, java.io.InputStream in)` Install a new bundle given by an `InputStream` to a bundle content.
    `void` | `setBundleStartLevel(long id, int startLevel)` Set the start level for a bundle given by its bundle Id.
    `void` | `setBundleStartLevel(java.lang.String bundlePath, int startLevel)`
    `void` | `setFrameworkStartLevel(org.osgi.framework.startlevel.dto.FrameworkStartLevelDTO startLevel)` Sets the current framework start level.
    `void` | `startBundle(long id)` Start a bundle given by its bundle Id.
    `void` | `startBundle(long id, int options)` Start a bundle given by its bundle Id.
    `void` | `startBundle(java.lang.String bundlePath)` Start a bundle given by its URI path.
    `void` | `startBundle(java.lang.String bundlePath, int options)` Start a bundle given by its URI path.
    `void` | `stopBundle(long id)` Stop a bundle given by its bundle Id.
    `void` | `stopBundle(long id, int options)` Stop a bundle given by its bundle Id.
    `void` | `stopBundle(java.lang.String bundlePath)` Stop a bundle given by its URI path.
    `void` | `stopBundle(java.lang.String bundlePath, int options)` Stop a bundle given by its URI path.
    `org.osgi.framework.dto.BundleDTO` | `uninstallBundle(long id)` Uninstall a bundle given by its bundle Id.
    `org.osgi.framework.dto.BundleDTO` | `uninstallBundle(java.lang.String bundlePath)` Uninstall a bundle given by its URI path.
    `org.osgi.framework.dto.BundleDTO` | `updateBundle(long id)` Updates a bundle given by its bundle Id using the bundle-internal update location.
    `org.osgi.framework.dto.BundleDTO` | `updateBundle(long id, java.io.InputStream in)` Updates a bundle given by its bundle Id and passing the new bundle content in the form of an `InputStream`.
    `org.osgi.framework.dto.BundleDTO` | `updateBundle(long id, java.lang.String url)` Updates a bundle given by its URI path using the content at the specified URL.

- - ### Method Detail

    - #### getFrameworkStartLevel

          org.osgi.framework.startlevel.dto.FrameworkStartLevelDTO getFrameworkStartLevel()
                                                                                          throws java.lang.Exception

      Retrieves the current framework start level.
      Returns:
        Returns the current framework start level in the form of a `FrameworkStartLevelDTO`.
      Throws:
        `java.lang.Exception` - An exception representing a failure in the underlying REST call.

    - #### setFrameworkStartLevel

          void setFrameworkStartLevel(org.osgi.framework.startlevel.dto.FrameworkStartLevelDTO startLevel)
                                      throws java.lang.Exception

      Sets the current framework start level.
      Parameters:
        `startLevel` - set the framework start level to this target.
      Throws:
        `java.lang.Exception` - An exception representing a failure in the underlying REST call.

    - #### getBundlePaths

          java.util.Collection<java.lang.String> getBundlePaths()
                                                                throws java.lang.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:
        `java.lang.Exception` - An exception representing a failure in the underlying REST call.

    - #### getBundles

          java.util.Collection<org.osgi.framework.dto.BundleDTO> getBundles()
                                                                            throws java.lang.Exception

      Get the bundle representations for all bundles currently installed in the managed framework.
      Returns:
        Returns a collection of BundleDTO objects.
      Throws:
        `java.lang.Exception` - An exception representing a failure in the underlying REST call.

    - #### getBundle

          org.osgi.framework.dto.BundleDTO getBundle(long id)
                                                     throws java.lang.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:
        `java.lang.Exception` - An exception representing a failure in the underlying REST call.

    - #### getBundle

          org.osgi.framework.dto.BundleDTO getBundle(java.lang.String bundlePath)
                                                     throws java.lang.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:
        `java.lang.Exception` - An exception representing a failure in the underlying REST call.

    - #### getBundleState

          int getBundleState(long id)
                             throws java.lang.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:
        `java.lang.Exception` - An exception representing a failure in the underlying REST call.

    - #### getBundleState

          int getBundleState(java.lang.String bundlePath)
                             throws java.lang.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:
        `java.lang.Exception` - An exception representing a failure in the underlying REST call.

    - #### startBundle

          void startBundle(long id)
                           throws java.lang.Exception

      Start a bundle given by its bundle Id.
      Parameters:
        `id` - Addresses the bundle by its identifier.
      Throws:
        `java.lang.Exception` - An exception representing a failure in the underlying REST call.

    - #### startBundle

          void startBundle(java.lang.String bundlePath)
                           throws java.lang.Exception

      Start a bundle given by its URI path.
      Parameters:
        `bundlePath` - Addresses the bundle by its URI path.
      Throws:
        `java.lang.Exception` - An exception representing a failure in the underlying REST call.

    - #### startBundle

          void startBundle(long id,
                         int options)
                           throws java.lang.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:
        `java.lang.Exception` - An exception representing a failure in the underlying REST call.

    - #### startBundle

          void startBundle(java.lang.String bundlePath,
                         int options)
                           throws java.lang.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:
        `java.lang.Exception` - An exception representing a failure in the underlying REST call.

    - #### stopBundle

          void stopBundle(long id)
                          throws java.lang.Exception

      Stop a bundle given by its bundle Id.
      Parameters:
        `id` - Addresses the bundle by its identifier.
      Throws:
        `java.lang.Exception` - An exception representing a failure in the underlying REST call.

    - #### stopBundle

          void stopBundle(java.lang.String bundlePath)
                          throws java.lang.Exception

      Stop a bundle given by its URI path.
      Parameters:
        `bundlePath` - Addresses the bundle by its URI path.
      Throws:
        `java.lang.Exception` - An exception representing a failure in the underlying REST call.

    - #### stopBundle

          void stopBundle(long id,
                        int options)
                          throws java.lang.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:
        `java.lang.Exception` - An exception representing a failure in the underlying REST call.

    - #### stopBundle

          void stopBundle(java.lang.String bundlePath,
                        int options)
                          throws java.lang.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:
        `java.lang.Exception` - An exception representing a failure in the underlying REST call.

    - #### getBundleHeaders

          java.util.Map<java.lang.String,java.lang.String> getBundleHeaders(long id)
                                                                            throws java.lang.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:
        `java.lang.Exception` - An exception representing a failure in the underlying REST call.

    - #### getBundleHeaders

          java.util.Map<java.lang.String,java.lang.String> getBundleHeaders(java.lang.String bundlePath)
                                                                            throws java.lang.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:
        `java.lang.Exception` - An exception representing a failure in the underlying REST call.

    - #### getBundleStartLevel

          org.osgi.framework.startlevel.dto.BundleStartLevelDTO getBundleStartLevel(long id)
                                                                                    throws java.lang.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:
        `java.lang.Exception` - An exception representing a failure in the underlying REST call.

    - #### getBundleStartLevel

          org.osgi.framework.startlevel.dto.BundleStartLevelDTO getBundleStartLevel(java.lang.String bundlePath)
                                                                                    throws java.lang.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:
        `java.lang.Exception` - An exception representing a failure in the underlying REST call.

    - #### setBundleStartLevel

          void setBundleStartLevel(long id,
                                 int startLevel)
                                   throws java.lang.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:
        `java.lang.Exception` - An exception representing a failure in the underlying REST call.

    - #### setBundleStartLevel

          void setBundleStartLevel(java.lang.String bundlePath,
                                 int startLevel)
                                   throws java.lang.Exception

      Parameters:
        `bundlePath` - Addresses the bundle by its URI path.
        `startLevel` - The target start level.
      Throws:
        `java.lang.Exception` - An exception representing a failure in the underlying REST call.

    - #### installBundle

          org.osgi.framework.dto.BundleDTO installBundle(java.lang.String location)
                                                         throws java.lang.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:
        `java.lang.Exception` - An exception representing a failure in the underlying REST call.

    - #### installBundle

          org.osgi.framework.dto.BundleDTO installBundle(java.lang.String location,
                                                       java.io.InputStream in)
                                                         throws java.lang.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:
        `java.lang.Exception` - An exception representing a failure in the underlying REST call.

    - #### uninstallBundle

          org.osgi.framework.dto.BundleDTO uninstallBundle(long id)
                                                           throws java.lang.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:
        `java.lang.Exception` - An exception representing a failure in the underlying REST call.

    - #### uninstallBundle

          org.osgi.framework.dto.BundleDTO uninstallBundle(java.lang.String bundlePath)
                                                           throws java.lang.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:
        `java.lang.Exception` - An exception representing a failure in the underlying REST call.

    - #### updateBundle

          org.osgi.framework.dto.BundleDTO updateBundle(long id)
                                                        throws java.lang.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:
        `java.lang.Exception` - An exception representing a failure in the underlying REST call.

    - #### updateBundle

          org.osgi.framework.dto.BundleDTO updateBundle(long id,
                                                      java.lang.String url)
                                                        throws java.lang.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:
        `java.lang.Exception` - An exception representing a failure in the underlying REST call.

    - #### updateBundle

          org.osgi.framework.dto.BundleDTO updateBundle(long id,
                                                      java.io.InputStream in)
                                                        throws java.lang.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:
        `java.lang.Exception` - An exception representing a failure in the underlying REST call.

    - #### getServicePaths

          java.util.Collection<java.lang.String> getServicePaths()
                                                                 throws java.lang.Exception

      Gets a collection of URI paths to all installed services.
      Returns:
        Returns a collection of URI paths to the installed services.
      Throws:
        `java.lang.Exception` - An exception representing a failure in the underlying REST call.

    - #### getServicePaths

          java.util.Collection<java.lang.String> getServicePaths(java.lang.String filter)
                                                                 throws java.lang.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:
        `java.lang.Exception` - An exception representing a failure in the underlying REST call.

    - #### getServiceReferences

          java.util.Collection<org.osgi.framework.dto.ServiceReferenceDTO> getServiceReferences()
                                                                                                throws java.lang.Exception

      Get the service representations for all services.
      Returns:
        Returns the service representations in the form of `ServiceReferenceDTO` objects.
      Throws:
        `java.lang.Exception` - An exception representing a failure in the underlying REST call.

    - #### getServiceReferences

          java.util.Collection<org.osgi.framework.dto.ServiceReferenceDTO> getServiceReferences(java.lang.String filter)
                                                                                                throws java.lang.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:
        `java.lang.Exception` - An exception representing a failure in the underlying REST call.

    - #### getServiceReference

          org.osgi.framework.dto.ServiceReferenceDTO getServiceReference(long id)
                                                                         throws java.lang.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:
        `java.lang.Exception` - An exception representing a failure in the underlying REST call.

    - #### getServiceReference

          org.osgi.framework.dto.ServiceReferenceDTO getServiceReference(java.lang.String servicePath)
                                                                         throws java.lang.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:
        `java.lang.Exception` - An exception representing a failure in the underlying REST call.