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 Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method 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.