|
What this is
This file is included in the DevDaily.com
"Java Source Code
Warehouse" project. The intent of this project is to help you "Learn
Java by Example" TM.
Other links
The source code
/*
* $Header: /cvsroot/eclipse/equinox-incubator/org.eclipse.equinox.deploymentadmin/src/org/osgi/service/deploymentadmin/DeploymentPackage.java,v 1.1 2007/07/04 18:07:15 skaegi Exp $
*
* Copyright (c) OSGi Alliance (2005, 2006). All Rights Reserved.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.osgi.service.deploymentadmin;
import org.osgi.framework.*;
/**
* The <code>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 packagess. Any violation of this no overlap rule is considered
* an error and the install or update of the offending deployment package must be aborted.<p>
*
* 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.<p>
*
* If a deployment package is being updated the old version is visible through the
* <code>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.
*/
public 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 {@link IllegalStateException}.
* Active methods are the following:<p>
*
* <ul>
* <li>{@link #getBundle(String)}
* <li>{@link #getResourceProcessor(String)}
* <li>{@link #uninstall()}
* <li>{@link #uninstallForced()}
* </ul>
*
* @return <code>true if the deployment package is stale. false
* otherwise
* @see #uninstall
* @see #uninstallForced
*/
boolean isStale();
/**
* Returns the Deployment Pacakage Symbolic Name of the package.
*
* @return The name of the deployment package. It cannot be null.
*/
String getName();
/**
* Returns the version of the deployment package.
* @return version of the deployment package. It cannot be null.
*/
Version getVersion();
/**
* Returns an array of {@link 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.
*
* @return array of <code>BundleInfo objects
* @throws SecurityException if the caller doesn't have the appropriate {@link DeploymentAdminPermission}
* with "metadata" action
*/
BundleInfo[] getBundleInfos();
/**
* Returns the bundle instance, which is part of this deployment package, that corresponds
* to the bundle's symbolic name passed in the <code>symbolicName parameter.
* This method will return null for request for bundles that are not part
* of this deployment package.<p>
*
* 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.
*
* @param symbolicName the symbolic name of the requested bundle
* @return The <code>Bundle instance for a given bundle symbolic name.
* @throws SecurityException if the caller doesn't have the appropriate {@link DeploymentAdminPermission}
* with "metadata" action
* @throws IllegalStateException if the package is stale
*/
Bundle getBundle(String symbolicName);
/**
* 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.<p>
*
* E.g. if the "Name" section of the resource (or individual-section as the
* <a href="http://java.sun.com/j2se/1.4.2/docs/guide/jar/jar.html#Manifest%20Specification">Manifest Specification
* calls it) in the manifest is the following
* <pre>
* Name: foo/readme.txt
* Resource-Processor: foo.rp
* </pre>
*
* then the corresponding array element is the "foo/readme.txt" string.<p>
*
* @return The string array corresponding to resources. It cannot be null but its
* length can be zero.
* @throws SecurityException if the caller doesn't have the appropriate {@link DeploymentAdminPermission}
* with "metadata" action
*/
String[] getResources();
/**
* At the time of deployment, resource processor service instances are located to
* resources contained in a deployment package.<p>
*
* 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.
*
* @param resource the name of the resource (it is the same as the value of the "Name"
* attribute in the deployment package's manifest)
* @return resource processor for the resource or <code>null.
* @throws SecurityException if the caller doesn't have the appropriate {@link DeploymentAdminPermission}
* with "metadata" action
* @throws IllegalStateException if the package is stale
*/
ServiceReference getResourceProcessor(String resource);
/**
* 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.<p>
*
* If the header is localized then the localized value is returned (see OSGi Service Platform,
* Mobile Specification Release 4 - Localization related chapters).
*
* @param header the requested header
* @return the value of the header or <code>null if the header does not exist
* @throws SecurityException if the caller doesn't have the appropriate {@link DeploymentAdminPermission}
* with "metadata" action
*/
String getHeader(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.<p>
*
* If the header is localized then the localized value is returned (see OSGi Service Platform,
* Mobile Specification Release 4 - Localization related chapters).
* @param resource the name of the resource (it is the same as the value of the "Name"
* attribute in the deployment package's manifest)
* @param header the requested header
* @return the value of the header or <code>null if the resource or the header doesn't exist
* @throws SecurityException if the caller doesn't have the appropriate {@link DeploymentAdminPermission}
* with "metadata" action
*/
String getResourceHeader(String resource, String header);
/**
* Uninstalls the deployment package. After uninstallation, the deployment package
* object becomes stale. This can be checked by using {@link #isStale()},
* which will return <code>true when stale.
*
* @throws DeploymentException if the deployment package could not be successfully uninstalled.
* For detailed error code description see {@link DeploymentException}.
* @throws SecurityException if the caller doesn't have the appropriate
* {@link DeploymentAdminPermission}("<filter>", "uninstall") permission.
* @throws IllegalStateException if the package is stale
*/
void uninstall() throws DeploymentException;
/**
* This method is called to completely uninstall a deployment package, which couldn't be uninstalled
* using traditional means ({@link #uninstall()}) due to exceptions. After uninstallation, the deployment
* package object becomes stale. This can be checked by using {@link #isStale()},
* which will return <code>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 {@link #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.
*
* @return true if the operation was successful
* @throws DeploymentException only {@link DeploymentException#CODE_TIMEOUT} and
* {@link DeploymentException#CODE_CANCELLED} can be thrown. For detailed error code description
* see {@link DeploymentException}.
* @throws SecurityException if the caller doesn't have the appropriate
* {@link DeploymentAdminPermission}("<filter>", "uninstall_forced") permission.
* @throws IllegalStateException if the package is stale
*/
boolean uninstallForced() throws DeploymentException;
/**
* Returns a hash code value for the object.
*
* @return a hash code value for this object
*/
int hashCode();
/**
* Indicates whether some other object is "equal to" this one. Two deployment packages
* are equal if they have the same deployment package symbolicname and version.
*
* @param other the reference object with which to compare.
* @return true if this object is the same as the obj argument; false otherwise.
*/
boolean equals(Object other);
}
|