DeploymentPackage (OSGi Compendium Release 7)

```
public interface DeploymentPackage
```
The DeploymentPackage object represents a deployment package (already installed or being currently processed). A Deployment Package groups resources as a unit of management. A deployment package is something that can be installed, updated, and uninstalled as a unit. A deployment package is a reified concept, like a bundle, in an OSGi Service Platform. It is not known by the OSGi Framework, but it is managed by the Deployment Admin service. A deployment package is a stream of resources (including bundles) which, once processed, will result in new artifacts (effects on the system) being added to the OSGi platform. These new artifacts can include installed Bundles, new configuration objects added to the Configuration Admin service, new Wire objects added to the Wire Admin service, or changed system properties, etc. All the changes caused by the processing of a deployment package are persistently associated with the deployment package, so that they can be appropriately cleaned up when the deployment package is uninstalled. There is a strict no overlap rule imposed on deployment packages. Two deployment packages are not allowed to create or manipulate the same artifact. Obviously, this means that a bundle cannot be in two different deployment packages. Any violation of this no overlap rule is considered an error and the install or update of the offending deployment package must be aborted.
The Deployment Admin service should do as much as possible to ensure transactionality. It means that if a deployment package installation, update or removal (uninstall) fails all the side effects caused by the process should be disappeared and the system should be in the state in which it was before the process.
If a deployment package is being updated the old version is visible through the DeploymentPackage interface until the update process ends. After the package is updated the updated version is visible and the old one is not accessible any more.

Field Summary

Fields
Modifier and Type	Field and Description
`static java.lang.String`	`EVENT_DEPLOYMENTPACKAGE_CURRENTVERSION` The currently installed version of the Deployment Package.
`static java.lang.String`	`EVENT_DEPLOYMENTPACKAGE_NAME` The name of the Deployment Package.
`static java.lang.String`	`EVENT_DEPLOYMENTPACKAGE_NEXTVERSION` The version of DP after the successful completion of the install operation (used in INSTALL event only).
`static java.lang.String`	`EVENT_DEPLOYMENTPACKAGE_READABLENAME` The human readable name of the DP localized to the default locale.

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`boolean`	`equals(java.lang.Object other)` Indicates whether some other object is "equal to" this one.
`Bundle`	`getBundle(java.lang.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.
`BundleInfo[]`	`getBundleInfos()` Returns an array of `BundleInfo` objects representing the bundles specified in the manifest of this deployment package.
`java.lang.String`	`getDisplayName()` Returns the Deployment Package human readable name.
`java.lang.String`	`getHeader(java.lang.String header)` Returns the requested deployment package manifest header from the main section.
`java.net.URL`	`getIcon()` Returns a URL pointing to an image that represents the icon for this Deployment Package.
`java.lang.String`	`getName()` Returns the Deployment Package Symbolic Name of the package.
`java.lang.String`	`getResourceHeader(java.lang.String resource, java.lang.String header)` Returns the requested deployment package manifest header from the name section determined by the resource parameter.
`ServiceReference<ResourceProcessor>`	`getResourceProcessor(java.lang.String resource)` At the time of deployment, resource processor service instances are located to resources contained in a deployment package.
`java.lang.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.
`int`	`hashCode()` Returns a hash code value for the object.
`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 (`uninstall()`) due to exceptions.

- Field Detail
  - EVENT_DEPLOYMENTPACKAGE_NAME
```
static final java.lang.String EVENT_DEPLOYMENTPACKAGE_NAME
```
    The name of the Deployment Package. This name is the same name as that specified in the DeploymentPackage-SymbolicName Manifest header.
    
    Since:
    
    1.1
    
    See Also:
    
    Constant Field Values
  - EVENT_DEPLOYMENTPACKAGE_READABLENAME
```
static final java.lang.String EVENT_DEPLOYMENTPACKAGE_READABLENAME
```
    The human readable name of the DP localized to the default locale.
    
    Since:
    
    1.1
    
    See Also:
    
    Constant Field Values
  - EVENT_DEPLOYMENTPACKAGE_CURRENTVERSION
```
static final java.lang.String EVENT_DEPLOYMENTPACKAGE_CURRENTVERSION
```
    The currently installed version of the Deployment Package. The attribute is not present, if no version is installed:
    - in the INSTALL event, when an installDeploymentPackage was called and no earlier version is present
    - in the COMPLETE event after the _successfully_ completing an uninstallDeploymentPackage call
    The value for this event must be a Version object.
    Since:
    
    1.1
    
    See Also:
    
    Constant Field Values
  - EVENT_DEPLOYMENTPACKAGE_NEXTVERSION
```
static final java.lang.String EVENT_DEPLOYMENTPACKAGE_NEXTVERSION
```
    The version of DP after the successful completion of the install operation (used in INSTALL event only). The value for this event must be a Version object.
    
    Since:
    
    1.1
    
    See Also:
    
    Constant Field Values
- Method Detail
  - isStale
```
boolean isStale()
```
    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:
    Returns:
    
    true if the deployment package is stale. false otherwise
    
    See Also:
    
    uninstall(), uninstallForced()
  - getName
```
java.lang.String getName()
```
    Returns the Deployment Package Symbolic Name of the package.
    
    Returns:
    
    The name of the deployment package. It cannot be null.
  - getDisplayName
```
java.lang.String getDisplayName()
```
    Returns the Deployment Package human readable name. This method returns the localized human readable name as set with the DeploymentPackage-Name manifest header using the default locale. If no header is set, this method will return null.
    
    Returns:
    
    The human readable name of the deployment package or null if header is not set.
    
    Since:
    
    1.1
  - getVersion
```
Version getVersion()
```
    Returns the version of the deployment package.
    
    Returns:
    
    version of the deployment package. It cannot be null.
  - getBundleInfos
```
BundleInfo[] getBundleInfos()
```
    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.
    
    Returns:
    
    array of BundleInfo objects
    
    Throws:
    
    java.lang.SecurityException - if the caller doesn't have the appropriate DeploymentAdminPermission with "metadata" action
  - getIcon
```
java.net.URL getIcon()
```
    Returns a URL pointing to an image that represents the icon for this Deployment Package. The DeploymentPackage-Icon header can set an icon for the deployment package. This method returns an absolute URL that is defined by this header. The Deployment Admin service must provide this icon as a local resource. That is, the Deployment Admin must make a local copy of the specified icon. The returned URL's must point to a local resource.
    
    Returns:
    
    An absolute URL to a local (device resident) image resource or null if not found
    
    Since:
    
    1.1
  - getBundle
```
Bundle getBundle(java.lang.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. 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.
    
    Parameters:
    
    symbolicName - the symbolic name of the requested bundle
    
    Returns:
    
    The Bundle instance for a given bundle symbolic name.
    
    Throws:
    
    java.lang.SecurityException - if the caller doesn't have the appropriate DeploymentAdminPermission with "metadata" action
    
    java.lang.IllegalStateException - if the package is stale
  - getResources
```
java.lang.String[] getResources()
```
    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.
    Returns:
    
    The string array corresponding to resources. It cannot be null but its length can be zero.
    
    Throws:
    
    java.lang.SecurityException - if the caller doesn't have the appropriate DeploymentAdminPermission with "metadata" action
  - getResourceProcessor
```
ServiceReference<ResourceProcessor> getResourceProcessor(java.lang.String resource)
```
    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.
    
    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.
    
    Throws:
    
    java.lang.SecurityException - if the caller doesn't have the appropriate DeploymentAdminPermission with "metadata" action
    
    java.lang.IllegalStateException - if the package is stale
  - getHeader
```
java.lang.String getHeader(java.lang.String header)
```
    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).
    
    Parameters:
    
    header - the requested header
    
    Returns:
    
    the value of the header or null if the header does not exist
    
    Throws:
    
    java.lang.SecurityException - if the caller doesn't have the appropriate DeploymentAdminPermission with "metadata" action
  - getResourceHeader
```
java.lang.String getResourceHeader(java.lang.String resource,
                                   java.lang.String header)
```
    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).
    
    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
    
    Throws:
    
    java.lang.SecurityException - if the caller doesn't have the appropriate DeploymentAdminPermission with "metadata" action
  - uninstall
```
void uninstall()
        throws DeploymentException
```
    Uninstalls the deployment package. After uninstallation, the deployment package object becomes stale. This can be checked by using isStale(), which will return true when stale.
    
    Throws:
    
    DeploymentException - if the deployment package could not be successfully uninstalled. For detailed error code description see DeploymentException.
    
    java.lang.SecurityException - if the caller doesn't have the appropriate DeploymentAdminPermission("<filter>", "uninstall") permission.
    
    java.lang.IllegalStateException - if the package is stale
  - uninstallForced
```
boolean uninstallForced()
                 throws DeploymentException
```
    This method is called to completely uninstall a deployment package, which couldn't be uninstalled using traditional means (uninstall()) due to exceptions. After uninstallation, the deployment package object becomes stale. This can be checked by using 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 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.
    
    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.
    
    java.lang.SecurityException - if the caller doesn't have the appropriate DeploymentAdminPermission("<filter>", "uninstall_forced") permission.
    
    java.lang.IllegalStateException - if the package is stale
  - hashCode
```
int hashCode()
```
    Returns a hash code value for the object.
    
    Overrides:
    
    hashCode in class java.lang.Object
    
    Returns:
    
    a hash code value for this object
  - equals
```
boolean equals(java.lang.Object other)
```
    Indicates whether some other object is "equal to" this one. Two deployment packages are equal if they have the same deployment package symbolic name and version.
    
    Overrides:
    
    equals in class java.lang.Object
    
    Parameters:
    
    other - the reference object with which to compare.
    
    Returns:
    
    true if this object is the same as the other argument; false otherwise.

Interface DeploymentPackage

Field Summary

Method Summary

Field Detail

EVENT_DEPLOYMENTPACKAGE_NAME

EVENT_DEPLOYMENTPACKAGE_READABLENAME

EVENT_DEPLOYMENTPACKAGE_CURRENTVERSION

EVENT_DEPLOYMENTPACKAGE_NEXTVERSION

Method Detail

isStale

getName

getDisplayName

getVersion

getBundleInfos

getIcon

getBundle

getResources

getResourceProcessor

getHeader

getResourceHeader

uninstall

uninstallForced

hashCode

equals