You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@felix.apache.org by ch...@apache.org on 2008/08/02 11:56:04 UTC
svn commit: r681945 [7/9] - in /felix/trunk/org.osgi.compendium: ./ doc/
src/main/java/info/ src/main/java/info/dmtree/
src/main/java/info/dmtree/notification/
src/main/java/info/dmtree/notification/spi/
src/main/java/info/dmtree/registry/ src/main/jav...
Added: felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/application/ScheduledApplication.java
URL: http://svn.apache.org/viewvc/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/application/ScheduledApplication.java?rev=681945&view=auto
==============================================================================
--- felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/application/ScheduledApplication.java (added)
+++ felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/application/ScheduledApplication.java Sat Aug 2 02:56:01 2008
@@ -0,0 +1,176 @@
+/*
+ * $Header: /cvshome/build/org.osgi.service.application/src/org/osgi/service/application/ScheduledApplication.java,v 1.20 2006/07/06 14:59:29 sboshev Exp $
+ *
+ * Copyright (c) OSGi Alliance (2004, 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.application;
+
+import java.util.Map;
+
+/**
+ * It is allowed to schedule an application based on a specific event.
+ * ScheduledApplication service keeps the schedule information. When the
+ * specified event is fired a new instance must be launched. Note that launching
+ * operation may fail because e.g. the application is locked.
+ * <p>
+ * Each <code>ScheduledApplication</code> instance has an identifier which is
+ * unique within the scope of the application being scheduled.
+ * <p>
+ * <code>ScheduledApplication</code> instances are registered as services.
+ * The {@link #APPLICATION_PID} service property contains the PID of the
+ * application being scheduled, the {@link #SCHEDULE_ID} service property
+ * contains the schedule identifier.
+ */
+public interface ScheduledApplication {
+
+ /**
+ * The property key for the identifier of the application being scheduled.
+ */
+ public static final String APPLICATION_PID = ApplicationDescriptor.APPLICATION_PID;
+
+ /**
+ * The property key for the schedule identifier. The identifier is unique
+ * within the scope of the application being scheduled.
+ */
+ public static final String SCHEDULE_ID = "schedule.id";
+
+ /**
+ * The key for the startup argument used to pass the event object that
+ * triggered the schedule to launch the application instance.
+ * The event is passed in a {@link java.security.GuardedObject}
+ * protected by the corresponding
+ * {@link org.osgi.service.event.TopicPermission}.
+ */
+ public static final String TRIGGERING_EVENT = "org.osgi.triggeringevent";
+
+ /**
+ * The topic name for the virtual timer topic. Time based schedules
+ * should be created using this topic.
+ */
+ public static final String TIMER_TOPIC = "org/osgi/application/timer";
+
+ /**
+ * The name of the <i>year</i> attribute of a virtual timer event. The value is
+ * defined by {@link java.util.Calendar#YEAR}.
+ */
+ public static final String YEAR = "year";
+
+ /**
+ * The name of the <i>month</i> attribute of a virtual timer event. The value is
+ * defined by {@link java.util.Calendar#MONTH}.
+ */
+ public static final String MONTH = "month";
+
+ /**
+ * The name of the <i>day of month</i> attribute of a virtual timer event. The value is
+ * defined by {@link java.util.Calendar#DAY_OF_MONTH}.
+ */
+ public static final String DAY_OF_MONTH = "day_of_month";
+
+ /**
+ * The name of the <i>day of week</i> attribute of a virtual timer event. The value is
+ * defined by {@link java.util.Calendar#DAY_OF_WEEK}.
+ */
+ public static final String DAY_OF_WEEK = "day_of_week";
+
+ /**
+ * The name of the <i>hour of day</i> attribute of a virtual timer event. The value is
+ * defined by {@link java.util.Calendar#HOUR_OF_DAY}.
+ */
+ public static final String HOUR_OF_DAY = "hour_of_day";
+
+ /**
+ * The name of the <i>minute</i> attribute of a virtual timer event. The value is
+ * defined by {@link java.util.Calendar#MINUTE}.
+ */
+ public static final String MINUTE = "minute";
+
+
+ /**
+ * Returns the identifier of this schedule. The identifier is unique within
+ * the scope of the application that the schedule is related to.
+ * @return the identifier of this schedule
+ *
+ */
+ public String getScheduleId();
+
+ /**
+ * Queries the topic of the triggering event. The topic may contain a
+ * trailing asterisk as wildcard.
+ *
+ * @return the topic of the triggering event
+ *
+ * @throws IllegalStateException
+ * if the scheduled application service is unregistered
+ */
+ public String getTopic();
+
+ /**
+ * Queries the event filter for the triggering event.
+ *
+ * @return the event filter for triggering event
+ *
+ * @throws IllegalStateException
+ * if the scheduled application service is unregistered
+ */
+ public String getEventFilter();
+
+ /**
+ * Queries if the schedule is recurring.
+ *
+ * @return true if the schedule is recurring, otherwise returns false
+ *
+ * @throws IllegalStateException
+ * if the scheduled application service is unregistered
+ */
+ public boolean isRecurring();
+
+ /**
+ * Retrieves the ApplicationDescriptor which represents the application and
+ * necessary for launching.
+ *
+ * @return the application descriptor that
+ * represents the scheduled application
+ *
+ * @throws IllegalStateException
+ * if the scheduled application service is unregistered
+ */
+ public ApplicationDescriptor getApplicationDescriptor();
+
+ /**
+ * Queries the startup arguments specified when the application was
+ * scheduled. The method returns a copy of the arguments, it is not possible
+ * to modify the arguments after scheduling.
+ *
+ * @return the startup arguments of the scheduled application. It may be
+ * null if null argument was specified.
+ *
+ * @throws IllegalStateException
+ * if the scheduled application service is unregistered
+ */
+ public Map getArguments();
+
+ /**
+ * Cancels this schedule of the application.
+ *
+ * @throws SecurityException
+ * if the caller doesn't have "schedule"
+ * ApplicationAdminPermission for the scheduled application.
+ * @throws IllegalStateException
+ * if the scheduled application service is unregistered
+ */
+ public void remove();
+}
Modified: felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/cm/ConfigurationAdmin.java
URL: http://svn.apache.org/viewvc/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/cm/ConfigurationAdmin.java?rev=681945&r1=681944&r2=681945&view=diff
==============================================================================
--- felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/cm/ConfigurationAdmin.java (original)
+++ felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/cm/ConfigurationAdmin.java Sat Aug 2 02:56:01 2008
@@ -1,5 +1,5 @@
/*
- * $Header: /cvshome/build/org.osgi.service.cm/src/org/osgi/service/cm/ConfigurationAdmin.java,v 1.16 2006/07/11 00:54:03 hargrave Exp $
+ * $Header: /cvshome/build/org.osgi.service.cm/src/org/osgi/service/cm/ConfigurationAdmin.java,v 1.17 2006/09/26 13:33:09 hargrave Exp $
*
* Copyright (c) OSGi Alliance (2001, 2006). All Rights Reserved.
*
@@ -100,7 +100,7 @@
* <code>ConfigurationAdmin</code> must use a
* {@link org.osgi.framework.ServiceFactory} to support this concept.
*
- * @version $Revision: 1.16 $
+ * @version $Revision: 1.17 $
*/
public interface ConfigurationAdmin {
/**
@@ -230,7 +230,7 @@
* <code>ConfigurationPermission[*,CONFIGURE]</code>.
*
* <p>
- * The syntax of the filter string is as defined in the <code>Filter</code>
+ * The syntax of the filter string is as defined in the {@link org.osgi.framework.Filter}
* class. The filter can test any configuration parameters including the
* following system properties:
* <ul>
@@ -244,10 +244,10 @@
* The filter can also be <code>null</code>, meaning that all
* <code>Configuration</code> objects should be returned.
*
- * @param filter a <code>Filter</code> object, or <code>null</code> to
+ * @param filter A filter string, or <code>null</code> to
* retrieve all <code>Configuration</code> objects.
- * @return all matching <code>Configuration</code> objects, or
- * <code>null</code> if there aren't any
+ * @return All matching <code>Configuration</code> objects, or
+ * <code>null</code> if there aren't any.
* @throws IOException if access to persistent storage fails
* @throws InvalidSyntaxException if the filter string is invalid
*/
Added: felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/BundleInfo.java
URL: http://svn.apache.org/viewvc/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/BundleInfo.java?rev=681945&view=auto
==============================================================================
--- felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/BundleInfo.java (added)
+++ felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/BundleInfo.java Sat Aug 2 02:56:01 2008
@@ -0,0 +1,43 @@
+/*
+ * $Header: /cvshome/build/org.osgi.service.deploymentadmin/src/org/osgi/service/deploymentadmin/BundleInfo.java,v 1.3 2006/06/16 16:31:39 hargrave 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.Version;
+
+/**
+ * Represents a bundle in the array given back by the {@link DeploymentPackage#getBundleInfos()}
+ * method.
+ */
+public interface BundleInfo {
+
+ /**
+ * Returns the Bundle Symbolic Name of the represented bundle.
+ *
+ * @return the Bundle Symbolic Name
+ */
+ String getSymbolicName();
+
+ /**
+ * Returns the version of the represented bundle.
+ *
+ * @return the version of the represented bundle
+ */
+ Version getVersion();
+
+}
Added: felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/DeploymentAdmin.java
URL: http://svn.apache.org/viewvc/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/DeploymentAdmin.java?rev=681945&view=auto
==============================================================================
--- felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/DeploymentAdmin.java (added)
+++ felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/DeploymentAdmin.java Sat Aug 2 02:56:01 2008
@@ -0,0 +1,139 @@
+/*
+ * $Header: /cvshome/build/org.osgi.service.deploymentadmin/src/org/osgi/service/deploymentadmin/DeploymentAdmin.java,v 1.28 2007/02/07 18:53:07 hargrave Exp $
+ *
+ * Copyright (c) OSGi Alliance (2005, 2007). 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 java.io.InputStream;
+
+import org.osgi.framework.Bundle;
+
+/**
+ * This is the interface of the Deployment Admin service.<p>
+ *
+ * The OSGi Service Platform provides mechanisms to manage the life cycle of
+ * bundles, configuration objects, permission objects, etc. but the overall consistency
+ * of the runtime configuration is the responsibility of the management
+ * agent. In other words, the management agent decides to install, update,
+ * or uninstall bundles, create or delete configuration or permission objects, as
+ * well as manage other resource types, etc.<p>
+ *
+ * The Deployment Admin service standardizes the access to some of the responsibilities
+ * of the management agent. The service provides functionality to manage Deployment Packages
+ * (see {@link DeploymentPackage}). 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.<p>
+ *
+ * The Deployment Admin functionality is exposed as a standard OSGi service with no
+ * mandatory service parameters.
+ */
+public interface DeploymentAdmin {
+
+ /**
+ * Installs a Deployment Package from an input stream. If a version of that Deployment Package
+ * is already installed and the versions are different, the installed version is updated
+ * with this new version even if it is older (downgrade). If the two versions are the same, then this
+ * method simply returns with the old (target) Deployment Package without any action.
+ *
+ * @param in the input stream the Deployment Package can be read from. It mustn't be <code>null</code>.
+ * @return A DeploymentPackage object representing the newly installed/updated Deployment Package.
+ * It is never <code>null</code>.
+ * @throws IllegalArgumentException if the got InputStream parameter is <code>null</code>
+ * @throws DeploymentException if the installation was not successful. For detailed error code description
+ * see {@link DeploymentException}.
+ * @throws SecurityException if the caller doesn't have the appropriate
+ * {@link DeploymentAdminPermission}("<filter>", "install") permission.
+ * @see DeploymentAdminPermission
+ * @see DeploymentPackage
+ * @see DeploymentPackage
+ */
+ DeploymentPackage installDeploymentPackage(InputStream in) throws DeploymentException;
+
+ /**
+ * Lists the Deployment Packages currently installed on the platform.<p>
+ *
+ * {@link DeploymentAdminPermission}("<filter>", "list") is
+ * needed for this operation to the effect that only those packages are listed in
+ * the array to which the caller has appropriate DeploymentAdminPermission. It has
+ * the consequence that the method never throws SecurityException only doesn't
+ * put certain Deployment Packages into the array.<p>
+ *
+ * During an installation of an existing package (update) or during an uninstallation,
+ * the target must remain in this list until the installation (uninstallation) process
+ * is completed, after which the source (or <code>null</code> in case of uninstall)
+ * replaces the target.
+ *
+ * @return the array of <code>DeploymentPackage</code> objects representing all the
+ * installed Deployment Packages. The return value cannot be <code>null</code>.
+ * In case of missing permissions it may give back an empty array.
+ * @see DeploymentPackage
+ * @see DeploymentAdminPermission
+ */
+ DeploymentPackage[] listDeploymentPackages();
+
+ /**
+ * Gets the currenlty installed {@link DeploymentPackage} instance which has the given
+ * symbolic name.<p>
+ *
+ * During an installation of an existing package (update) or during an uninstallation,
+ * the target Deployment Package must remain the return value until the installation
+ * (uninstallation) process is completed, after which the source (or <code>null</code>
+ * in case of uninstall) is the return value.
+ *
+ * @param symbName the symbolic name of the Deployment Package to be retrieved. It mustn't be
+ * <code>null</code>.
+ * @return The <code>DeploymentPackage</code> for the given symbolic name.
+ * If there is no Deployment Package with that symbolic name currently installed,
+ * <code>null</code> is returned.
+ * @throws IllegalArgumentException if the given <code>symbName</code> is <code>null</code>
+ * @throws SecurityException if the caller doesn't have the appropriate
+ * {@link DeploymentAdminPermission}("<filter>", "list") permission.
+ * @see DeploymentPackage
+ * @see DeploymentAdminPermission
+ */
+ DeploymentPackage getDeploymentPackage(String symbName);
+
+ /**
+ * Gives back the installed {@link DeploymentPackage} that owns the bundle. Deployment Packages own their
+ * bundles by their Bundle Symbolic Name. It means that if a bundle belongs to an installed
+ * Deployment Packages (and at most to one) the Deployment Admin assigns the bundle to its owner
+ * Deployment Package by the Symbolic Name of the bundle.<p>
+ *
+ * @param bundle the bundle whose owner is queried
+ * @return the Deployment Package Object that owns the bundle or <code>null</code> if the bundle doesn't
+ * belong to any Deployment Packages (standalone bundles)
+ * @throws IllegalArgumentException if the given <code>bundle</code> is <code>null</code>
+ * @throws SecurityException if the caller doesn't have the appropriate
+ * {@link DeploymentAdminPermission}("<filter>", "list") permission.
+ * @see DeploymentPackage
+ * @see DeploymentAdminPermission
+ */
+ DeploymentPackage getDeploymentPackage(Bundle bundle);
+
+ /**
+ * This method cancels the currently active deployment session. This method addresses the need
+ * to cancel the processing of excessively long running, or resource consuming install, update
+ * or uninstall operations.<p>
+ *
+ * @return true if there was an active session and it was successfully cancelled.
+ * @throws SecurityException if the caller doesn't have the appropriate
+ * {@link DeploymentAdminPermission}("<filter>", "cancel") permission.
+ * @see DeploymentAdminPermission
+ */
+ boolean cancel();
+
+}
Added: felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/DeploymentAdminPermission.java
URL: http://svn.apache.org/viewvc/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/DeploymentAdminPermission.java?rev=681945&view=auto
==============================================================================
--- felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/DeploymentAdminPermission.java (added)
+++ felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/DeploymentAdminPermission.java Sat Aug 2 02:56:01 2008
@@ -0,0 +1,331 @@
+/*
+ * $Header: /cvshome/build/org.osgi.service.deploymentadmin/src/org/osgi/service/deploymentadmin/DeploymentAdminPermission.java,v 1.40 2006/07/12 21:22:10 hargrave 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 java.io.InputStream;
+import java.lang.reflect.Constructor;
+import java.lang.reflect.InvocationTargetException;
+import java.security.*;
+
+import org.osgi.framework.Bundle;
+
+/**
+ * DeploymentAdminPermission controls access to the Deployment Admin service.<p>
+ *
+ * The permission uses a filter string formatted similarly to the {@link org.osgi.framework.Filter}.
+ * The filter determines the target of the permission. The <code>DeploymentAdminPermission</code> uses the
+ * <code>name</code> and the <code>signer</code> filter attributes only. The value of the <code>signer</code>
+ * attribute is matched against the signer chain (represented with its semicolon separated Distinguished Name chain)
+ * of the Deployment Package, and the value of the <code>name</code> attribute is matched against the value of the
+ * "DeploymentPackage-Name" manifest header of the Deployment Package. Example:
+ *
+ * <ul>
+ * <li>(signer=cn = Bugs Bunny, o = ACME, c = US)</li>
+ * <li>(name=org.osgi.ExampleApp)</li>
+ * </ul>
+ *
+ * Wildcards also can be used:<p>
+ *
+ * <pre>
+ * (signer=cn=*,o=ACME,c=*)
+ * </pre>
+ * "cn" and "c" may have an arbitrary value
+ *
+ * <pre>
+ * (signer=*, o=ACME, c=US)
+ * </pre>
+ * Only the value of "o" and "c" are significant
+ *
+ * <pre>
+ * (signer=* ; ou=S & V, o=Tweety Inc., c=US)
+ * </pre>
+ * The first element of the certificate chain is
+ * not important, only the second (the
+ * Distingushed Name of the root certificate)
+ *
+ * <pre>
+ * (signer=- ; *, o=Tweety Inc., c=US)
+ * </pre>
+ * The same as the previous but '-' represents
+ * zero or more certificates, whereas the asterisk
+ * only represents a single certificate
+ *
+ * <pre>
+ * (name=*)
+ * </pre>
+ * The name of the Deployment Package doesn't matter
+ *
+ * <pre>
+ * (name=org.osgi.*)
+ * </pre>
+ * The name has to begin with "org.osgi."
+ *
+ * <p>The following actions are allowed:<p>
+ *
+ * <b>list</b>
+ * <p>
+ * A holder of this permission can access the inventory information of the deployment
+ * packages selected by the <filter> string. The filter selects the deployment packages
+ * on which the holder of the permission can acquire detailed inventory information.
+ * See {@link DeploymentAdmin#getDeploymentPackage(Bundle)},
+ * {@link DeploymentAdmin#getDeploymentPackage(String)} and
+ * {@link DeploymentAdmin#listDeploymentPackages}.<p>
+ *
+ * <b>install</b><p>
+ *
+ * A holder of this permission can install/update deployment packages if the deployment
+ * package satisfies the <filter> string. See {@link DeploymentAdmin#installDeploymentPackage}.<p>
+ *
+ * <b>uninstall</b><p>
+ *
+ * A holder of this permission can uninstall deployment packages if the deployment
+ * package satisfies the <filter> string. See {@link DeploymentPackage#uninstall}.<p>
+ *
+ * <b>uninstall_forced</b><p>
+ *
+ * A holder of this permission can forcefully uninstall deployment packages if the deployment
+ * package satisfies the <filter> string. See {@link DeploymentPackage#uninstallForced}.<p>
+ *
+ * <b>cancel</b><p>
+ *
+ * A holder of this permission can cancel an active deployment action. This action being
+ * cancelled could correspond to the install, update or uninstall of a deployment package
+ * that satisfies the <filter> string. See {@link DeploymentAdmin#cancel}<p>
+ *
+ * <b>metadata</b><p>
+ *
+ * A holder of this permission is able to retrieve metadata information about a Deployment
+ * Package (e.g. is able to ask its manifest hedares).
+ * See {@link org.osgi.service.deploymentadmin.DeploymentPackage#getBundle(String)},
+ * {@link org.osgi.service.deploymentadmin.DeploymentPackage#getBundleInfos()},
+ * {@link org.osgi.service.deploymentadmin.DeploymentPackage#getHeader(String)},
+ * {@link org.osgi.service.deploymentadmin.DeploymentPackage#getResourceHeader(String, String)},
+ * {@link org.osgi.service.deploymentadmin.DeploymentPackage#getResourceProcessor(String)},
+ * {@link org.osgi.service.deploymentadmin.DeploymentPackage#getResources()}<p>
+ *
+ * The actions string is converted to lowercase before processing.
+ */
+public final class DeploymentAdminPermission extends Permission {
+
+ /**
+ *
+ */
+ private static final long serialVersionUID = 1L;
+
+ /**
+ * Constant String to the "install" action.<p>
+ *
+ * @see DeploymentAdmin#installDeploymentPackage(InputStream)
+ */
+ public static final String INSTALL = "install";
+
+ /**
+ * Constant String to the "list" action.<p>
+ *
+ * @see DeploymentAdmin#listDeploymentPackages()
+ * @see DeploymentAdmin#getDeploymentPackage(String)
+ * @see DeploymentAdmin#getDeploymentPackage(Bundle)
+ */
+ public static final String LIST = "list";
+
+ /**
+ * Constant String to the "uninstall" action.<p>
+ *
+ * @see DeploymentPackage#uninstall()
+ */
+ public static final String UNINSTALL = "uninstall";
+
+ /**
+ * Constant String to the "uninstall_forced" action.<p>
+ *
+ * @see DeploymentPackage#uninstallForced()
+ */
+ public static final String UNINSTALL_FORCED = "uninstall_forced";
+
+ /**
+ * Constant String to the "cancel" action.<p>
+ *
+ * @see DeploymentAdmin#cancel
+ */
+ public static final String CANCEL = "cancel";
+
+ /**
+ * Constant String to the "metadata" action.<p>
+ *
+ * @see org.osgi.service.deploymentadmin.DeploymentPackage#getBundle(String)
+ * @see org.osgi.service.deploymentadmin.DeploymentPackage#getBundleInfos()
+ * @see org.osgi.service.deploymentadmin.DeploymentPackage#getHeader(String)
+ * @see org.osgi.service.deploymentadmin.DeploymentPackage#getResourceHeader(String, String)
+ * @see org.osgi.service.deploymentadmin.DeploymentPackage#getResourceProcessor(String)
+ * @see org.osgi.service.deploymentadmin.DeploymentPackage#getResources()
+ */
+ public static final String METADATA = "metadata";
+
+ private static final String delegateProperty = "org.osgi.vendor.deploymentadmin";
+ private static final Constructor constructor;
+ private final Permission delegate;
+ static {
+ constructor = (Constructor) AccessController.doPrivileged(new PrivilegedAction() {
+ public Object run() {
+ String pckg = System.getProperty(delegateProperty);
+ if (null == pckg)
+ throw new RuntimeException("Property '" + delegateProperty + "' is not set");
+ try {
+ Class c = Class.forName(pckg + ".DeploymentAdminPermission");
+ return c.getConstructor(new Class[] {String.class, String.class});
+ }
+ catch (Exception e) {
+ throw new RuntimeException(e.getMessage());
+ }
+ }});
+ }
+
+ /**
+ * Creates a new <code>DeploymentAdminPermission</code> object for the given <code>name</code> and
+ * <code>action</code>.<p>
+ * The <code>name</code> parameter identifies the target depolyment package the permission
+ * relates to. The <code>actions</code> parameter contains the comma separated list of allowed actions.
+ *
+ * @param name filter string, must not be null.
+ * @param actions action string, must not be null. "*" means all the possible actions.
+ * @throws IllegalArgumentException if the filter is invalid, the list of actions
+ * contains unknown operations or one of the parameters is null
+ */
+ public DeploymentAdminPermission(String name, String actions) {
+ super(name);
+ try {
+ try {
+ delegate = (Permission) constructor.newInstance(new Object[] {name, actions});
+ }
+ catch (InvocationTargetException e) {
+ throw e.getTargetException();
+ }
+ }
+ catch (Error e) {
+ throw e;
+ }
+ catch (RuntimeException e) {
+ throw e;
+ }
+ catch (Throwable e) {
+ throw new RuntimeException(e.toString());
+ }
+ }
+
+ /**
+ * Checks two DeploymentAdminPermission objects for equality.
+ * Two permission objects are equal if: <p>
+ *
+ * <ul>
+ * <li>their target filters are semantically equal and</li>
+ * <li>their actions are the same</li>
+ * </ul>
+ *
+ * @param obj The reference object with which to compare.
+ * @return true if the two objects are equal.
+ * @see java.lang.Object#equals(java.lang.Object)
+ */
+ public boolean equals(Object obj) {
+ if (obj == this)
+ return true;
+ if (!(obj instanceof DeploymentAdminPermission))
+ return false;
+ DeploymentAdminPermission dap = (DeploymentAdminPermission) obj;
+ return delegate.equals(dap.delegate);
+ }
+
+ /**
+ * Returns hash code for this permission object.
+ *
+ * @return Hash code for this permission object.
+ * @see java.lang.Object#hashCode()
+ */
+ public int hashCode() {
+ return delegate.hashCode();
+ }
+
+ /**
+ * Returns the String representation of the action list.<p>
+ * The method always gives back the actions in the following (alphabetical) order:
+ * <code>cancel, install, list, metadata, uninstall, uninstall_forced</code>
+ *
+ * @return Action list of this permission instance. This is a comma-separated
+ * list that reflects the action parameter of the constructor.
+ * @see java.security.Permission#getActions()
+ */
+ public String getActions() {
+ return delegate.getActions();
+ }
+
+ /**
+ * Checks if this DeploymentAdminPermission would imply the parameter permission.<p>
+ * Precondition of the implication is that the action set of this permission is the superset
+ * of the action set of the other permission. Further rules of implication are determined
+ * by the {@link org.osgi.framework.Filter} rules and the "OSGi Service Platform, Core
+ * Specification Release 4, Chapter Certificate Matching".<p>
+ *
+ * The allowed attributes are: <code>name</code> (the symbolic name of the deployment
+ * package) and <code>signer</code> (the signer of the deployment package). In both cases
+ * wildcards can be used.<p>
+ *
+ * Examples:
+ *
+ * <pre>
+ * 1. DeploymentAdminPermission("(name=org.osgi.ExampleApp)", "list")
+ * 2. DeploymentAdminPermission("(name=org.osgi.ExampleApp)", "list, install")
+ * 3. DeploymentAdminPermission("(name=org.osgi.*)", "list")
+ * 4. DeploymentAdminPermission("(signer=*, o=ACME, c=US)", "list")
+ * 5. DeploymentAdminPermission("(signer=cn = Bugs Bunny, o = ACME, c = US)", "list")
+ * </pre><p>
+ *
+ * <pre>
+ * 1. implies 1.
+ * 2. implies 1.
+ * 1. doesn't implies 2.
+ * 3. implies 1.
+ * 4. implies 5.
+ * </pre>
+ *
+ * @param permission Permission to check.
+ * @return true if this DeploymentAdminPermission object implies the
+ * specified permission.
+ * @see java.security.Permission#implies(java.security.Permission)
+ * @see org.osgi.framework.Filter
+ */
+ public boolean implies(Permission permission) {
+ if (!(permission instanceof DeploymentAdminPermission))
+ return false;
+
+ DeploymentAdminPermission dap = (DeploymentAdminPermission) permission;
+
+ return delegate.implies(dap.delegate);
+ }
+
+ /**
+ * Returns a new PermissionCollection object for storing DeploymentAdminPermission
+ * objects.
+ *
+ * @return The new PermissionCollection.
+ * @see java.security.Permission#newPermissionCollection()
+ */
+ public PermissionCollection newPermissionCollection() {
+ return delegate.newPermissionCollection();
+ }
+
+}
Added: felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/DeploymentException.java
URL: http://svn.apache.org/viewvc/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/DeploymentException.java?rev=681945&view=auto
==============================================================================
--- felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/DeploymentException.java (added)
+++ felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/DeploymentException.java Sat Aug 2 02:56:01 2008
@@ -0,0 +1,266 @@
+/*
+ * $Header: /cvshome/build/org.osgi.service.deploymentadmin/src/org/osgi/service/deploymentadmin/DeploymentException.java,v 1.20 2006/07/12 21:22:10 hargrave 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 java.io.InputStream;
+
+/**
+ * Checked exception received when something fails during any deployment
+ * processes. A <code>DeploymentException</code> always contains an error code
+ * (one of the constants specified in this class), and may optionally contain
+ * the textual description of the error condition and a nested cause exception.
+ */
+public class DeploymentException extends Exception {
+
+ /**
+ *
+ */
+ private static final long serialVersionUID = 916011169146851101L;
+
+ /**
+ * {@link DeploymentAdmin#installDeploymentPackage(InputStream)},
+ * {@link DeploymentPackage#uninstall()} and {@link DeploymentPackage#uninstallForced()}
+ * methods can throw {@link DeploymentException} with this error code if the
+ * {@link DeploymentAdmin#cancel()} method is called from another thread.
+ */
+ public static final int CODE_CANCELLED = 401;
+
+ /**
+ * {@link DeploymentAdmin#installDeploymentPackage(InputStream)}
+ * methods can throw {@link DeploymentException} with this error code if
+ * the got InputStream is not a jar.
+ */
+ public static final int CODE_NOT_A_JAR = 404;
+
+ /**
+ * Order of files in the deployment package is bad. The right order is the
+ * following:<p>
+ *
+ * <ol>
+ * <li>META-INF/MANIFEST.MF</li>
+ * <li>META-INF/*.SF, META-INF/*.DSA, META-INF/*.RS</li>
+ * <li>Localization files</li>
+ * <li>Bundles</li>
+ * <li>Resources</li>
+ * </ol>
+ *
+ * {@link DeploymentAdmin#installDeploymentPackage(InputStream)}
+ * throws exception with this error code.
+ */
+ public static final int CODE_ORDER_ERROR = 450;
+
+ /**
+ * Missing mandatory manifest header.<p>
+ *
+ * {@link DeploymentAdmin#installDeploymentPackage(InputStream)} can throw
+ * exception with this error code.
+ */
+ public static final int CODE_MISSING_HEADER = 451;
+
+ /**
+ * Syntax error in any manifest header.<p>
+ *
+ * {@link DeploymentAdmin#installDeploymentPackage(InputStream)}
+ * throws exception with this error code.
+ */
+ public static final int CODE_BAD_HEADER = 452;
+
+ /**
+ * Fix pack version range doesn't fit to the version of the target
+ * deployment package or the target deployment package of the fix pack
+ * doesn't exist.<p>
+ *
+ * {@link DeploymentAdmin#installDeploymentPackage(InputStream)}
+ * throws exception with this error code.
+ */
+ public static final int CODE_MISSING_FIXPACK_TARGET = 453;
+
+ /**
+ * A bundle in the deployment package is marked as DeploymentPackage-Missing
+ * but there is no such bundle in the target deployment package.<p>
+ *
+ * {@link DeploymentAdmin#installDeploymentPackage(InputStream)}
+ * throws exception with this error code.
+ */
+ public static final int CODE_MISSING_BUNDLE = 454;
+
+ /**
+ * A resource in the source deployment package is marked as
+ * DeploymentPackage-Missing but there is no such resource in the target
+ * deployment package.<p>
+ *
+ * {@link DeploymentAdmin#installDeploymentPackage(InputStream)}
+ * throws exception with this error code.
+ */
+ public static final int CODE_MISSING_RESOURCE = 455;
+
+ /**
+ * Bad deployment package signing.<p>
+ *
+ * {@link DeploymentAdmin#installDeploymentPackage(InputStream)}
+ * throws exception with this error code.
+ */
+ public static final int CODE_SIGNING_ERROR = 456;
+
+ /**
+ * Bundle symbolic name is not the same as defined by the deployment package
+ * manifest.<p>
+ *
+ * {@link DeploymentAdmin#installDeploymentPackage(InputStream)}
+ * throws exception with this error code.
+ */
+ public static final int CODE_BUNDLE_NAME_ERROR = 457;
+
+ /**
+ * Matched resource processor service is a customizer from another
+ * deployment package.<p>
+ *
+ * {@link DeploymentAdmin#installDeploymentPackage(InputStream)}
+ * throws exception with this error code.
+ */
+ public static final int CODE_FOREIGN_CUSTOMIZER = 458;
+
+ /**
+ * Bundle with the same symbolic name alerady exists.<p>
+ *
+ * {@link DeploymentAdmin#installDeploymentPackage(InputStream)}
+ * throws exception with this error code.
+ */
+ public static final int CODE_BUNDLE_SHARING_VIOLATION = 460;
+
+ /**
+ * An artifact of any resource already exists.<p>
+ *
+ * This exception is thrown when the called resource processor throws a
+ * <code>ResourceProcessorException</code> with the
+ * {@link org.osgi.service.deploymentadmin.spi.ResourceProcessorException#CODE_RESOURCE_SHARING_VIOLATION}
+ * error code.<p>
+ *
+ * {@link DeploymentAdmin#installDeploymentPackage(InputStream)}
+ * throws exception with this error code.
+ */
+ public static final int CODE_RESOURCE_SHARING_VIOLATION = 461;
+
+ /**
+ * Exception with this error code is thrown when one of the Resource Processors
+ * involved in the deployment session threw a <code>ResourceProcessorException</code> with the
+ * {@link org.osgi.service.deploymentadmin.spi.ResourceProcessorException#CODE_PREPARE} error
+ * code.<p>
+ *
+ * {@link DeploymentAdmin#installDeploymentPackage(InputStream)} and
+ * {@link DeploymentPackage#uninstall()} methods throw exception with this error code.
+ */
+ public static final int CODE_COMMIT_ERROR = 462;
+
+ /**
+ * Other error condition.<p>
+ *
+ * All Deployment Admin methods which throw <code>DeploymentException</code>
+ * can throw an exception with this error code if the error condition cannot be
+ * categorized.
+ */
+ public static final int CODE_OTHER_ERROR = 463;
+
+ /**
+ * The Resource Processor service with the given PID (see
+ * <code>Resource-Processor</code> manifest header) is not found.<p>
+ *
+ * {@link DeploymentAdmin#installDeploymentPackage(InputStream)},
+ * {@link DeploymentPackage#uninstall()} and
+ * {@link DeploymentPackage#uninstallForced()}
+ * throws exception with this error code.
+ */
+ public static final int CODE_PROCESSOR_NOT_FOUND = 464;
+
+ /**
+ * When a client requests a new session with an install or uninstall
+ * operation, it must block that call until the earlier session is
+ * completed. The Deployment Admin service must throw a Deployment Exception
+ * with this error code when the session can not be created after an appropriate
+ * time out period.<p>
+ *
+ * {@link DeploymentAdmin#installDeploymentPackage(InputStream)},
+ * {@link DeploymentPackage#uninstall()} and
+ * {@link DeploymentPackage#uninstallForced()}
+ * throws exception with this error code.
+ */
+ public static final int CODE_TIMEOUT = 465;
+
+ private final int code;
+ private final String message;
+ private final Throwable cause;
+
+ /**
+ * Create an instance of the exception.
+ *
+ * @param code The error code of the failure. Code should be one of the
+ * predefined integer values (<code>CODE_X</code>).
+ * @param message Message associated with the exception
+ * @param cause the originating exception
+ */
+ public DeploymentException(int code, String message, Throwable cause) {
+ this.code = code;
+ this.message = message;
+ this.cause = cause;
+ }
+
+ /**
+ * Create an instance of the exception. Cause exception is implicitly set to
+ * null.
+ *
+ * @param code The error code of the failure. Code should be one of the
+ * predefined integer values (<code>CODE_X</code>).
+ * @param message Message associated with the exception
+ */
+ public DeploymentException(int code, String message) {
+ this(code, message, null);
+ }
+
+ /**
+ * Create an instance of the exception. Cause exception and message are
+ * implicitly set to null.
+ *
+ * @param code The error code of the failure. Code should be one of the
+ * predefined integer values (<code>CODE_X</code>).
+ */
+ public DeploymentException(int code) {
+ this(code, null, null);
+ }
+
+ /**
+ * @return Returns the cause.
+ */
+ public Throwable getCause() {
+ return cause;
+ }
+
+ /**
+ * @return Returns the code.
+ */
+ public int getCode() {
+ return code;
+ }
+
+ /**
+ * @return Returns the message.
+ */
+ public String getMessage() {
+ return message;
+ }
+}
Added: felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/DeploymentPackage.java
URL: http://svn.apache.org/viewvc/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/DeploymentPackage.java?rev=681945&view=auto
==============================================================================
--- felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/DeploymentPackage.java (added)
+++ felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/DeploymentPackage.java Sat Aug 2 02:56:01 2008
@@ -0,0 +1,240 @@
+/*
+ * $Header: /cvshome/build/org.osgi.service.deploymentadmin/src/org/osgi/service/deploymentadmin/DeploymentPackage.java,v 1.26 2006/07/12 21:22:10 hargrave 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</code> 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</code> 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>
+ * <li>{@link #getResourceProcessor(String)}</li>
+ * <li>{@link #uninstall()}</li>
+ * <li>{@link #uninstallForced()}</li>
+ * </ul>
+ *
+ * @return <code>true</code> if the deployment package is stale. <code>false</code>
+ * 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</code> 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</code> 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</code> 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</a>
+ * 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</cpde>.
+ * @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</code> 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</code> 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</code> when stale.<p>
+ *
+ * @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</code> when stale.<p>
+ *
+ * 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);
+
+}
Added: felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/spi/DeploymentCustomizerPermission.java
URL: http://svn.apache.org/viewvc/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/spi/DeploymentCustomizerPermission.java?rev=681945&view=auto
==============================================================================
--- felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/spi/DeploymentCustomizerPermission.java (added)
+++ felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/spi/DeploymentCustomizerPermission.java Sat Aug 2 02:56:01 2008
@@ -0,0 +1,200 @@
+/*
+ * $Header: /cvshome/build/org.osgi.service.deploymentadmin/src/org/osgi/service/deploymentadmin/spi/DeploymentCustomizerPermission.java,v 1.6 2006/06/21 15:16:13 hargrave 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.spi;
+
+import java.lang.reflect.Constructor;
+import java.lang.reflect.InvocationTargetException;
+import java.security.*;
+
+import org.osgi.service.deploymentadmin.DeploymentAdminPermission;
+
+/**
+ * The <code>DeploymentCustomizerPermission</code> permission gives the right to
+ * Resource Processors to access a bundle's (residing in a Deployment Package) private area.
+ * The bundle and the Resource Processor (customizer) have to be in the same Deployment Package.<p>
+ *
+ * The Resource Processor that has this permission is allowed to access the bundle's
+ * private area by calling the {@link DeploymentSession#getDataFile} method during the session
+ * (see {@link DeploymentSession}). After the session ends the FilePermissions are withdrawn.
+ * The Resource Processor will have <code>FilePermission</code> with "read", "write" and "delete"
+ * actions for the returned {@link java.io.File} that represents the the base directory of the
+ * persistent storage area and for its subdirectories.<p>
+ *
+ * The actions string is converted to lowercase before processing.
+ */
+public class DeploymentCustomizerPermission extends Permission {
+
+ /**
+ *
+ */
+ private static final long serialVersionUID = 1L;
+
+ /**
+ * Constant String to the "privatearea" action.
+ */
+ public static final String PRIVATEAREA = "privatearea";
+
+ private static final String delegateProperty = "org.osgi.vendor.deploymentadmin";
+ private static final Constructor constructor;
+ private final Permission delegate;
+ static {
+ constructor = (Constructor) AccessController.doPrivileged(new PrivilegedAction() {
+ public Object run() {
+ String pckg = System.getProperty(delegateProperty);
+ if (null == pckg)
+ throw new RuntimeException("Property '" + delegateProperty + "' is not set");
+ try {
+ Class c = Class.forName(pckg + ".DeploymentCustomizerPermission");
+ return c.getConstructor(new Class[] {String.class, String.class});
+ }
+ catch (Exception e) {
+ throw new RuntimeException(e.getMessage());
+ }
+ }});
+ }
+
+ /**
+ * Creates a new <code>DeploymentCustomizerPermission</code> object for the given
+ * <code>name</code> and <code>action</code>.<p>
+ *
+ * The name parameter is a filter string. This filter has the same syntax as an OSGi filter
+ * but only the "name" attribute is allowed. The value of the attribute
+ * is a Bundle Symbolic Name that represents a bundle. The only allowed action is the
+ * "privatearea" action. E.g.
+ *
+ * <pre>
+ * Permission perm = new DeploymentCustomizerPermission("(name=com.acme.bundle)", "privatearea");
+ * </pre>
+ *
+ * The Resource Processor that has this permission is allowed to access the bundle's
+ * private area by calling the {@link DeploymentSession#getDataFile} method. The
+ * Resource Processor will have <code>FilePermission</code> with "read", "write" and "delete"
+ * actions for the returned {@link java.io.File} and its subdirectories during the deployment
+ * session.
+ *
+ * @param name Bundle Symbolic Name of the target bundle, must not be <code>null</code>.
+ * @param actions action string (only the "privatearea" or "*" action is valid; "*" means all
+ * the possible actions), must not be <code>null</code>.
+ * @throws IllegalArgumentException if the filter is invalid, the list of actions
+ * contains unknown operations or one of the parameters is <code>null</code>
+ */
+ public DeploymentCustomizerPermission(String name, String actions) {
+ super(name);
+ try {
+ try {
+ delegate = (Permission) constructor.newInstance(new Object[] {name, actions});
+ }
+ catch (InvocationTargetException e) {
+ throw e.getTargetException();
+ }
+ }
+ catch (Error e) {
+ throw e;
+ }
+ catch (RuntimeException e) {
+ throw e;
+ }
+ catch (Throwable e) {
+ throw new RuntimeException(e.toString());
+ }
+ }
+
+ /**
+ * Checks two DeploymentCustomizerPermission objects for equality.
+ * Two permission objects are equal if: <p>
+ *
+ * <ul>
+ * <li>their target filters are equal (semantically and not character by
+ * character) and</li>
+ * <li>their actions are the same</li>
+ * </ul>
+ *
+ * @param obj the reference object with which to compare.
+ * @return true if the two objects are equal.
+ * @see java.lang.Object#equals(java.lang.Object)
+ */
+ public boolean equals(Object obj) {
+ if (obj == this)
+ return true;
+ if (!(obj instanceof DeploymentCustomizerPermission))
+ return false;
+ DeploymentCustomizerPermission dcp = (DeploymentCustomizerPermission) obj;
+ return delegate.equals(dcp.delegate);
+ }
+
+ /**
+ * Returns hash code for this permission object.
+ *
+ * @return Hash code for this permission object.
+ * @see java.lang.Object#hashCode()
+ */
+ public int hashCode() {
+ return delegate.hashCode();
+ }
+
+ /**
+ * Returns the String representation of the action list.
+ *
+ * @return Action list of this permission instance. It is always "privatearea".
+ * @see java.security.Permission#getActions()
+ */
+ public String getActions() {
+ return delegate.getActions();
+ }
+
+ /**
+ * Checks if this DeploymentCustomizerPermission would imply the parameter permission.
+ * This permission implies another DeploymentCustomizerPermission permission if:
+ *
+ * <ul>
+ * <li>both of them has the "privatearea" action (other actions are not allowed) and</li>
+ * <li>their filters (only name attribute is allowed in the filters) match similarly to
+ * {@link DeploymentAdminPermission}.</li>
+ * </ul>
+ *
+ * The value of the name attribute means Bundle Symbolic Name and not Deployment Package
+ * Symbolic Name here!<p>
+ *
+ * @param permission Permission to check.
+ * @return true if this DeploymentCustomizerPermission object implies the
+ * specified permission.
+ * @see java.security.Permission#implies(java.security.Permission)
+ */
+ public boolean implies(Permission permission) {
+ if (!(permission instanceof DeploymentCustomizerPermission))
+ return false;
+
+ DeploymentCustomizerPermission dcp = (DeploymentCustomizerPermission) permission;
+
+ return delegate.implies(dcp.delegate);
+ }
+
+ /**
+ * Returns a new PermissionCollection object for storing DeploymentCustomizerPermission
+ * objects.
+ *
+ * @return The new PermissionCollection.
+ * @see java.security.Permission#newPermissionCollection()
+ */
+ public PermissionCollection newPermissionCollection() {
+ return delegate.newPermissionCollection();
+ }
+
+}
Added: felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/spi/DeploymentSession.java
URL: http://svn.apache.org/viewvc/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/spi/DeploymentSession.java?rev=681945&view=auto
==============================================================================
--- felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/spi/DeploymentSession.java (added)
+++ felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/spi/DeploymentSession.java Sat Aug 2 02:56:01 2008
@@ -0,0 +1,96 @@
+/*
+ * $Header: /cvshome/build/org.osgi.service.deploymentadmin/src/org/osgi/service/deploymentadmin/spi/DeploymentSession.java,v 1.6 2006/06/16 16:31:39 hargrave 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.spi;
+
+import org.osgi.service.deploymentadmin.DeploymentPackage;
+
+/**
+ * The session interface represents a currently running deployment session
+ * (install/update/uninstall).<p>
+ *
+ * When a deployment package is installed the target package, when uninstalled the
+ * source package is an empty deployment package. The empty deployment package is a virtual
+ * entity it doesn't appear for the outside world. It is only visible on the
+ * DeploymentSession interface used by Resource Processors. Although the empty package
+ * is only visible for Resource Processors it has the following characteristics:<p>
+ *
+ * <ul>
+ * <li>has version 0.0.0</li>
+ * <li>its name is an empty string</li>
+ * <li>it is stale</li>
+ * <li>it has no bundles
+ * (see {@link DeploymentPackage#getBundle(String)})</li>
+ * <li>it has no resources
+ * (see {@link DeploymentPackage#getResources()})</li>
+ * <li>it has no headers except <br/>
+ * <code>DeploymentPackage-SymbolicName</code> and <br/>
+ * <code>DeploymentPackage-Version</code> <br/>
+ * (see {@link DeploymentPackage#getHeader(String)})</li>
+ * <li>it has no resource headers (see
+ * {@link DeploymentPackage#getResourceHeader(String, String)})</li>
+ * <li>{@link DeploymentPackage#uninstall()} throws
+ * {@link java.lang.IllegalStateException}</li>
+ * <li>{@link DeploymentPackage#uninstallForced()} throws
+ * {@link java.lang.IllegalStateException}</li>
+ * </ul>
+ *
+ */
+public interface DeploymentSession {
+
+ /**
+ * If the deployment action is an update or an uninstall, this call returns
+ * the <code>DeploymentPackage</code> instance for the installed deployment package. If the
+ * deployment action is an install, this call returns the empty deploymet package (see
+ * {@link DeploymentPackage}).
+ *
+ * @return the target deployment package
+ * @see DeploymentPackage
+ */
+ DeploymentPackage getTargetDeploymentPackage();
+
+ /**
+ * If the deployment action is an install or an update, this call returns
+ * the <code>DeploymentPackage</code> instance that corresponds to the deployment package
+ * being streamed in for this session. If the deployment action is an uninstall, this call
+ * returns the empty deploymet package (see {@link DeploymentPackage}).
+ *
+ * @return the source deployment package
+ * @see DeploymentPackage
+ */
+ DeploymentPackage getSourceDeploymentPackage();
+
+ /**
+ * Returns the private data area of the specified bundle. The bundle must be part of
+ * either the source or the target deployment packages. The permission set the caller
+ * resource processor needs to manipulate the private area of the bundle is set by the
+ * Deployment Admin on the fly when this method is called. The permissions remain available
+ * during the deployment action only.<p>
+ *
+ * The bundle and the caller Resource Processor have to be in the same Deployment Package.
+ *
+ * @param bundle the bundle the private area belongs to
+ * @return file representing the private area of the bundle. It cannot be null.
+ * @throws SecurityException if the caller doesn't have the appropriate
+ * {@link DeploymentCustomizerPermission}("<filter>", "privatearea") permission.
+ * @see DeploymentPackage
+ * @see DeploymentCustomizerPermission
+ */
+ java.io.File getDataFile(org.osgi.framework.Bundle bundle);
+
+}
+
Added: felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/spi/ResourceProcessor.java
URL: http://svn.apache.org/viewvc/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/spi/ResourceProcessor.java?rev=681945&view=auto
==============================================================================
--- felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/spi/ResourceProcessor.java (added)
+++ felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/spi/ResourceProcessor.java Sat Aug 2 02:56:01 2008
@@ -0,0 +1,139 @@
+/*
+ * $Header: /cvshome/build/org.osgi.service.deploymentadmin/src/org/osgi/service/deploymentadmin/spi/ResourceProcessor.java,v 1.6 2006/07/11 13:19:02 hargrave 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.spi;
+
+import java.io.InputStream;
+
+/**
+ * ResourceProcessor interface is implemented by processors handling resource files
+ * in deployment packages. Resource Processors expose their services as standard OSGi services.
+ * Bundles exporting the service may arrive in the deployment package (customizers) or may be
+ * preregistered (they are installed prevoiusly). Resource processors has to define the
+ * <code>service.pid</code> standard OSGi service property which should be a unique string.<p>
+ *
+ * The order of the method calls on a particular Resource Processor in case of install/update
+ * session is the following:<p>
+ *
+ * <ol>
+ * <li>{@link #begin(DeploymentSession)}</li>
+ * <li>{@link #process(String, InputStream)} calls till there are resources to process
+ * or {@link #rollback()} and the further steps are ignored</li>
+ * <li>{@link #dropped(String)} calls till there are resources to drop
+ * <li>{@link #prepare()}</li>
+ * <li>{@link #commit()} or {@link #rollback()}</li>
+ * </ol>
+ *
+ * The order of the method calls on a particular Resource Processor in case of uninstall
+ * session is the following:<p>
+ *
+ * <ol>
+ * <li>{@link #begin(DeploymentSession)}</li>
+ * <li>{@link #dropAllResources()} or {@link #rollback()} and the further steps are ignored</li>
+ * <li>{@link #prepare()}</li>
+ * <li>{@link #commit()} or {@link #rollback()}</li>
+ * </ol>
+ */
+public interface ResourceProcessor {
+
+ /**
+ * Called when the Deployment Admin starts a new operation on the given deployment package,
+ * and the resource processor is associated a resource within the package. Only one
+ * deployment package can be processed at a time.
+ *
+ * @param session object that represents the current session to the resource processor
+ * @see DeploymentSession
+ */
+ void begin(DeploymentSession session);
+
+ /**
+ * Called when a resource is encountered in the deployment package for which this resource
+ * processor has been selected to handle the processing of that resource.
+ *
+ * @param name The name of the resource relative to the deployment package root directory.
+ * @param stream The stream for the resource.
+ * @throws ResourceProcessorException if the resource cannot be processed. Only
+ * {@link ResourceProcessorException#CODE_RESOURCE_SHARING_VIOLATION} and
+ * {@link ResourceProcessorException#CODE_OTHER_ERROR} error codes are allowed.
+ */
+ void process(String name, InputStream stream) throws ResourceProcessorException;
+
+ /**
+ * Called when a resource, associated with a particular resource processor, had belonged to
+ * an earlier version of a deployment package but is not present in the current version of
+ * the deployment package. This provides an opportunity for the processor to cleanup any
+ * memory and persistent data being maintained for the particular resource.
+ * This method will only be called during "update" deployment sessions.
+ *
+ * @param resource the name of the resource to drop (it is the same as the value of the
+ * "Name" attribute in the deployment package's manifest)
+ * @throws ResourceProcessorException if the resource is not allowed to be dropped. Only the
+ * {@link ResourceProcessorException#CODE_OTHER_ERROR} error code is allowed
+ */
+ void dropped(String resource) throws ResourceProcessorException;
+
+ /**
+ * This method is called during an "uninstall" deployment session.
+ * This method will be called on all resource processors that are associated with resources
+ * in the deployment package being uninstalled. This provides an opportunity for the processor
+ * to cleanup any memory and persistent data being maintained for the deployment package.
+ *
+ * @throws ResourceProcessorException if all resources could not be dropped. Only the
+ * {@link ResourceProcessorException#CODE_OTHER_ERROR} is allowed.
+ */
+ void dropAllResources() throws ResourceProcessorException;
+
+ /**
+ * This method is called on the Resource Processor immediately before calling the
+ * <code>commit</code> method. The Resource Processor has to check whether it is able
+ * to commit the operations since the last <code>begin</code> method call. If it determines
+ * that it is not able to commit the changes, it has to raise a
+ * <code>ResourceProcessorException</code> with the {@link ResourceProcessorException#CODE_PREPARE}
+ * error code.
+ *
+ * @throws ResourceProcessorException if the resource processor is able to determine it is
+ * not able to commit. Only the {@link ResourceProcessorException#CODE_PREPARE} error
+ * code is allowed.
+ */
+ void prepare() throws ResourceProcessorException;
+
+ /**
+ * Called when the processing of the current deployment package is finished.
+ * This method is called if the processing of the current deployment package was successful,
+ * and the changes must be made permanent.
+ */
+ void commit();
+
+
+ /**
+ * Called when the processing of the current deployment package is finished.
+ * This method is called if the processing of the current deployment package was unsuccessful,
+ * and the changes made during the processing of the deployment package should be removed.
+ */
+ void rollback();
+
+ /**
+ * Processing of a resource passed to the resource processor may take long.
+ * The <code>cancel()</code> method notifies the resource processor that it should
+ * interrupt the processing of the current resource. This method is called by the
+ * <code>DeploymentAdmin</code> implementation after the
+ * <code>DeploymentAdmin.cancel()</code> method is called.
+ */
+ void cancel();
+
+}
Added: felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/spi/ResourceProcessorException.java
URL: http://svn.apache.org/viewvc/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/spi/ResourceProcessorException.java?rev=681945&view=auto
==============================================================================
--- felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/spi/ResourceProcessorException.java (added)
+++ felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/spi/ResourceProcessorException.java Sat Aug 2 02:56:01 2008
@@ -0,0 +1,123 @@
+/*
+ * $Header: /cvshome/build/org.osgi.service.deploymentadmin/src/org/osgi/service/deploymentadmin/spi/ResourceProcessorException.java,v 1.7 2006/07/12 21:22:10 hargrave 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.spi;
+
+import java.io.InputStream;
+
+/**
+ * Checked exception received when something fails during a call to a Resource
+ * Processor. A <code>ResourceProcessorException</code> always contains an error
+ * code (one of the constants specified in this class), and may optionally contain
+ * the textual description of the error condition and a nested cause exception.
+ */
+public class ResourceProcessorException extends Exception {
+
+ /**
+ *
+ */
+ private static final long serialVersionUID = 9135007015668223386L;
+
+ /**
+ * Resource Processors are allowed to raise an exception with this error code
+ * to indicate that the processor is not able to commit the operations it made
+ * since the last call of {@link ResourceProcessor#begin(DeploymentSession)} method.<p>
+ *
+ * Only the {@link ResourceProcessor#prepare()} method is allowed to throw exception
+ * with this error code.
+ */
+ public static final int CODE_PREPARE = 1;
+
+ /**
+ * An artifact of any resource already exists.<p>
+ *
+ * Only the {@link ResourceProcessor#process(String, InputStream)} method
+ * is allowed to throw exception with this error code.
+ */
+ public static final int CODE_RESOURCE_SHARING_VIOLATION = 461;
+
+ /**
+ * Other error condition.<p>
+ *
+ * All Resource Processor methods which throw <code>ResourceProcessorException</code>
+ * is allowed throw an exception with this erro code if the error condition cannot be
+ * categorized.
+ */
+ public static final int CODE_OTHER_ERROR = 463;
+
+ private final int code;
+ private final String message;
+ private final Throwable cause;
+
+ /**
+ * Create an instance of the exception.
+ *
+ * @param code The error code of the failure. Code should be one of the
+ * predefined integer values (<code>CODE_X</code>).
+ * @param message Message associated with the exception
+ * @param cause the originating exception
+ */
+ public ResourceProcessorException(int code, String message, Throwable cause) {
+ this.code = code;
+ this.message = message;
+ this.cause = cause;
+ }
+
+ /**
+ * Create an instance of the exception. Cause exception is implicitly set to
+ * null.
+ *
+ * @param code The error code of the failure. Code should be one of the
+ * predefined integer values (<code>CODE_X</code>).
+ * @param message Message associated with the exception
+ */
+ public ResourceProcessorException(int code, String message) {
+ this(code, message, null);
+ }
+
+ /**
+ * Create an instance of the exception. Cause exception and message are
+ * implicitly set to null.
+ *
+ * @param code The error code of the failure. Code should be one of the
+ * predefined integer values (<code>CODE_X</code>).
+ */
+ public ResourceProcessorException(int code) {
+ this(code, null, null);
+ }
+
+ /**
+ * @return Returns the cause.
+ */
+ public Throwable getCause() {
+ return cause;
+ }
+
+ /**
+ * @return Returns the code.
+ */
+ public int getCode() {
+ return code;
+ }
+
+ /**
+ * @return Returns the message.
+ */
+ public String getMessage() {
+ return message;
+ }
+}