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

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

Method Detail

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.