org.apache.felix.deploymentadmin
Class AbstractDeploymentPackage

java.lang.Object
  extended by org.apache.felix.deploymentadmin.AbstractDeploymentPackage
All Implemented Interfaces:
DeploymentPackage

public abstract class AbstractDeploymentPackage
extends Object
implements DeploymentPackage

Base class for various types of deployment packages. Indifferent in regard to how the deployment package data is obtained, this should be handled by extending classes.


Field Summary
protected static AbstractDeploymentPackage emptyPackage
           
 
Fields inherited from interface org.osgi.service.deploymentadmin.DeploymentPackage
EVENT_DEPLOYMENTPACKAGE_CURRENTVERSION, EVENT_DEPLOYMENTPACKAGE_NAME, EVENT_DEPLOYMENTPACKAGE_NEXTVERSION, EVENT_DEPLOYMENTPACKAGE_READABLENAME
 
Constructor Summary
AbstractDeploymentPackage(Manifest manifest, BundleContext bundleContext)
          Creates an instance of this class.
 
Method Summary
protected  AbstractInfo getAbstractInfoByPath(String path)
          Determines the info about either a bundle or processed resource based on it's path/resource-id.
 Bundle getBundle(String symbolicName)
          Returns the bundle instance, which is part of this deployment package, that corresponds to the bundle's symbolic name passed in the symbolicName parameter.
 BundleInfoImpl getBundleInfoByName(String symbolicName)
          Determines the info about a bundle resource based on the bundle symbolic name.
 BundleInfoImpl getBundleInfoByPath(String path)
          Determines the info about a bundle based on it's path/resource-id.
 BundleInfoImpl[] getBundleInfoImpls()
          Returns the bundles of this deployment package as an array of BundleInfoImpl objects.
 BundleInfo[] getBundleInfos()
          Returns an array of BundleInfo objects representing the bundles specified in the manifest of this deployment package.
abstract  InputStream getBundleStream(String symbolicName)
          Determines the data stream of a bundle resource based on the bundle symbolic name
abstract  InputStream getCurrentEntryStream()
          Determines the data stream to the current entry of this deployment package, use this together with the getNextEntry method.
 String getHeader(String header)
          Returns the requested deployment package manifest header from the main section.
 String getName()
          Returns the Deployment Package Symbolic Name of the package.
abstract  AbstractInfo getNextEntry()
          Determines the next resource entry in this deployment package based on the order in which the resources appeared when the package was originally received.
abstract  BundleInfoImpl[] getOrderedBundleInfos()
          Determines the bundles of this deployment package in the order in which they were originally received.
abstract  ResourceInfoImpl[] getOrderedResourceInfos()
          Determines the resources of this deployment package in the order in which they were originally received.
 String getResourceHeader(String resource, String header)
          Returns the requested deployment package manifest header from the name section determined by the resource parameter.
 ResourceInfoImpl getResourceInfoByPath(String path)
          Determines the info about a processed resource based on it's path/resource-id.
 ResourceInfoImpl[] getResourceInfos()
          Returns the processed resources of this deployment package as an array of ResourceInfoImpl objects.
 ServiceReference getResourceProcessor(String resource)
          At the time of deployment, resource processor service instances are located to resources contained in a deployment package.
 String[] getResources()
          Returns an array of strings representing the resources (including bundles) that are specified in the manifest of this deployment package.
 Version getVersion()
          Returns the version of the deployment package.
 VersionRange getVersionRange()
          If this deployment package is a fix package this method determines the version range this deployment package can be applied to.
 boolean isFixPackage()
          Determines whether this deployment package is a fix package.
 boolean isStale()
          Gives back the state of the deployment package whether it is stale or not).
 void uninstall()
          Uninstalls the deployment package.
 boolean uninstallForced()
          This method is called to completely uninstall a deployment package, which couldn't be uninstalled using traditional means (DeploymentPackage.uninstall()) due to exceptions.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface org.osgi.service.deploymentadmin.DeploymentPackage
equals, getDisplayName, getIcon, hashCode
 

Field Detail

emptyPackage

protected static final AbstractDeploymentPackage emptyPackage
Constructor Detail

AbstractDeploymentPackage

public AbstractDeploymentPackage(Manifest manifest,
                                 BundleContext bundleContext)
                          throws DeploymentException
Creates an instance of this class.

Parameters:
manifest - The manifest of the deployment package.
bundleContext - The bundle context.
Throws:
DeploymentException - Thrown if the specified manifest does not describe a valid deployment package.
Method Detail

getBundle

public Bundle getBundle(String symbolicName)
Description copied from interface: DeploymentPackage
Returns the bundle instance, which is part of this deployment package, that corresponds to the bundle's symbolic name passed in the symbolicName parameter. This method will return null for request for bundles that are not part of this deployment package.

As this instance is transient (i.e. a bundle can be removed at any time because of the dynamic nature of the OSGi platform), this method may also return null if the bundle is part of this deployment package, but is not currently defined to the framework.

Specified by:
getBundle in interface DeploymentPackage
Parameters:
symbolicName - the symbolic name of the requested bundle
Returns:
The Bundle instance for a given bundle symbolic name.

getBundleInfos

public BundleInfo[] getBundleInfos()
Description copied from interface: DeploymentPackage
Returns an array of BundleInfo objects representing the bundles specified in the manifest of this deployment package. Its size is equal to the number of the bundles in the deployment package.

Specified by:
getBundleInfos in interface DeploymentPackage
Returns:
array of BundleInfo objects

getBundleInfoImpls

public BundleInfoImpl[] getBundleInfoImpls()
Returns the bundles of this deployment package as an array of BundleInfoImpl objects.

Returns:
Array containing BundleInfoImpl objects for each bundle this deployment package.

getResourceInfos

public ResourceInfoImpl[] getResourceInfos()
Returns the processed resources of this deployment package as an array of ResourceInfoImpl objects.

Returns:
Array containing ResourceInfoImpl objects for each processed resource of this deployment package.

isFixPackage

public boolean isFixPackage()
Determines whether this deployment package is a fix package.

Returns:
True if this deployment package is a fix package, false otherwise.

getHeader

public String getHeader(String header)
Description copied from interface: DeploymentPackage
Returns the requested deployment package manifest header from the main section. Header names are case insensitive. If the header doesn't exist it returns null.

If the header is localized then the localized value is returned (see OSGi Service Platform, Mobile Specification Release 4 - Localization related chapters).

Specified by:
getHeader in interface DeploymentPackage
Parameters:
header - the requested header
Returns:
the value of the header or null if the header does not exist

getName

public String getName()
Description copied from interface: DeploymentPackage
Returns the Deployment Package Symbolic Name of the package.

Specified by:
getName in interface DeploymentPackage
Returns:
The name of the deployment package. It cannot be null.

getResourceHeader

public String getResourceHeader(String resource,
                                String header)
Description copied from interface: DeploymentPackage
Returns the requested deployment package manifest header from the name section determined by the resource parameter. Header names are case insensitive. If the resource or the header doesn't exist it returns null.

If the header is localized then the localized value is returned (see OSGi Service Platform, Mobile Specification Release 4 - Localization related chapters).

Specified by:
getResourceHeader in interface DeploymentPackage
Parameters:
resource - the name of the resource (it is the same as the value of the "Name" attribute in the deployment package's manifest)
header - the requested header
Returns:
the value of the header or null if the resource or the header doesn't exist

getResourceProcessor

public ServiceReference getResourceProcessor(String resource)
Description copied from interface: DeploymentPackage
At the time of deployment, resource processor service instances are located to resources contained in a deployment package.

This call returns a service reference to the corresponding service instance. If the resource is not part of the deployment package or this call is made during deployment, prior to the locating of the service to process a given resource, null will be returned. Services can be updated after a deployment package has been deployed. In this event, this call will return a reference to the updated service, not to the instance that was used at deployment time.

Specified by:
getResourceProcessor in interface DeploymentPackage
Parameters:
resource - the name of the resource (it is the same as the value of the "Name" attribute in the deployment package's manifest)
Returns:
resource processor for the resource or null.

getResources

public String[] getResources()
Description copied from interface: DeploymentPackage
Returns an array of strings representing the resources (including bundles) that are specified in the manifest of this deployment package. A string element of the array is the same as the value of the "Name" attribute in the manifest. The array contains the bundles as well.

E.g. if the "Name" section of the resource (or individual-section as the Manifest Specification calls it) in the manifest is the following

     Name: foo/readme.txt
     Resource-Processor: foo.rp
 
then the corresponding array element is the "foo/readme.txt" string.

Specified by:
getResources in interface DeploymentPackage
Returns:
The string array corresponding to resources. It cannot be null but its length can be zero.

getVersion

public Version getVersion()
Description copied from interface: DeploymentPackage
Returns the version of the deployment package.

Specified by:
getVersion in interface DeploymentPackage
Returns:
version of the deployment package. It cannot be null.

getVersionRange

public VersionRange getVersionRange()
If this deployment package is a fix package this method determines the version range this deployment package can be applied to.

Returns:
VersionRange the fix package can be applied to or null if it is not a fix package.

isStale

public boolean isStale()
Description copied from interface: DeploymentPackage
Gives back the state of the deployment package whether it is stale or not). After uninstall of a deployment package it becomes stale. Any active method calls to a stale deployment package raise IllegalStateException. Active methods are the following:

Specified by:
isStale in interface DeploymentPackage
Returns:
true if the deployment package is stale. false otherwise
See Also:
DeploymentPackage.uninstall(), DeploymentPackage.uninstallForced()

uninstall

public void uninstall()
               throws DeploymentException
Description copied from interface: DeploymentPackage
Uninstalls the deployment package. After uninstallation, the deployment package object becomes stale. This can be checked by using DeploymentPackage.isStale(), which will return true when stale.

Specified by:
uninstall in interface DeploymentPackage
Throws:
DeploymentException - if the deployment package could not be successfully uninstalled. For detailed error code description see DeploymentException.

uninstallForced

public boolean uninstallForced()
                        throws DeploymentException
Description copied from interface: DeploymentPackage
This method is called to completely uninstall a deployment package, which couldn't be uninstalled using traditional means (DeploymentPackage.uninstall()) due to exceptions. After uninstallation, the deployment package object becomes stale. This can be checked by using DeploymentPackage.isStale(), which will return true when stale.

The method forces removal of the Deployment Package from the repository maintained by the Deployment Admin service. This method follows the same steps as DeploymentPackage.uninstall(). However, any errors or the absence of Resource Processor services are ignored, they must not cause a roll back. These errors should be logged.

Specified by:
uninstallForced in interface DeploymentPackage
Returns:
true if the operation was successful
Throws:
DeploymentException - only DeploymentException.CODE_TIMEOUT and DeploymentException.CODE_CANCELLED can be thrown. For detailed error code description see DeploymentException.

getOrderedBundleInfos

public abstract BundleInfoImpl[] getOrderedBundleInfos()
Determines the bundles of this deployment package in the order in which they were originally received.

Returns:
Array containing BundleInfoImpl objects of the bundles in this deployment package, ordered in the way they appeared when the deployment package was first received.

getOrderedResourceInfos

public abstract ResourceInfoImpl[] getOrderedResourceInfos()
Determines the resources of this deployment package in the order in which they were originally received.

Returns:
Array containing ResourceInfoImpl objects of all processed resources in this deployment package, ordered in the way they appeared when the deployment package was first received

getResourceInfoByPath

public ResourceInfoImpl getResourceInfoByPath(String path)
Determines the info about a processed resource based on it's path/resource-id.

Parameters:
path - String containing a (processed) resource path
Returns:
ResourceInfoImpl for the resource identified by the specified path or null if the path is unknown or does not describe a processed resource

getAbstractInfoByPath

protected AbstractInfo getAbstractInfoByPath(String path)
Determines the info about either a bundle or processed resource based on it's path/resource-id.

Parameters:
path - String containing a resource path (either bundle or processed resource)
Returns:
AbstractInfoImpl for the resource identified by the specified path or null if the path is unknown

getBundleInfoByPath

public BundleInfoImpl getBundleInfoByPath(String path)
Determines the info about a bundle based on it's path/resource-id.

Parameters:
path - String containing a bundle path
Returns:
BundleInfoImpl for the bundle resource identified by the specified path or null if the path is unknown or does not describe a bundle resource

getBundleInfoByName

public BundleInfoImpl getBundleInfoByName(String symbolicName)
Determines the info about a bundle resource based on the bundle symbolic name.

Parameters:
symbolicName - String containing a bundle symbolic name
Returns:
BundleInfoImpl for the bundle identified by the specified symbolic name or null if the symbolic name is unknown

getBundleStream

public abstract InputStream getBundleStream(String symbolicName)
                                     throws IOException
Determines the data stream of a bundle resource based on the bundle symbolic name

Parameters:
symbolicName - Bundle symbolic name
Returns:
Stream to the bundle identified by the specified symbolic name or null if no such bundle exists in this deployment package.
Throws:
IOException - If the bundle can not be properly offered as an inputstream

getNextEntry

public abstract AbstractInfo getNextEntry()
                                   throws IOException
Determines the next resource entry in this deployment package based on the order in which the resources appeared when the package was originally received.

Returns:
AbstractInfo describing the next resource entry (as determined by the order in which the deployment package was received originally) or null if there is no next entry
Throws:
IOException - if the next entry can not be properly determined

getCurrentEntryStream

public abstract InputStream getCurrentEntryStream()
Determines the data stream to the current entry of this deployment package, use this together with the getNextEntry method.

Returns:
Stream to the current resource in the deployment package (as determined by the order in which the deployment package was received originally) or null if there is no entry


Copyright © 2011 Apache Software Foundation. All Rights Reserved.