You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@felix.apache.org by ri...@apache.org on 2009/07/24 19:06:44 UTC
svn commit: r797561 [4/9] - in /felix/trunk: org.osgi.compendium/
org.osgi.compendium/src/main/java/info/dmtree/
org.osgi.compendium/src/main/java/info/dmtree/notification/
org.osgi.compendium/src/main/java/info/dmtree/notification/spi/
org.osgi.compen...
Added: felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/component/packageinfo
URL: http://svn.apache.org/viewvc/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/component/packageinfo?rev=797561&view=auto
==============================================================================
--- felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/component/packageinfo (added)
+++ felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/component/packageinfo Fri Jul 24 17:06:37 2009
@@ -0,0 +1 @@
+version 1.1
Modified: 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=797561&r1=797560&r2=797561&view=diff
==============================================================================
--- felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/BundleInfo.java (original)
+++ felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/BundleInfo.java Fri Jul 24 17:06:37 2009
@@ -1,7 +1,5 @@
/*
- * $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.
+ * Copyright (c) OSGi Alliance (2005, 2008). 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.
Modified: 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=797561&r1=797560&r2=797561&view=diff
==============================================================================
--- felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/DeploymentAdmin.java (original)
+++ felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/DeploymentAdmin.java Fri Jul 24 17:06:37 2009
@@ -1,7 +1,5 @@
/*
- * $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.
+ * Copyright (c) OSGi Alliance (2005, 2008). 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.
Modified: 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=797561&r1=797560&r2=797561&view=diff
==============================================================================
--- felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/DeploymentAdminPermission.java (original)
+++ felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/DeploymentAdminPermission.java Fri Jul 24 17:06:37 2009
@@ -1,7 +1,5 @@
/*
- * $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.
+ * Copyright (c) OSGi Alliance (2005, 2008). 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.
@@ -21,7 +19,10 @@
import java.io.InputStream;
import java.lang.reflect.Constructor;
import java.lang.reflect.InvocationTargetException;
-import java.security.*;
+import java.security.AccessController;
+import java.security.Permission;
+import java.security.PermissionCollection;
+import java.security.PrivilegedAction;
import org.osgi.framework.Bundle;
@@ -191,7 +192,7 @@
return c.getConstructor(new Class[] {String.class, String.class});
}
catch (Exception e) {
- throw new RuntimeException(e.getMessage());
+ throw new RuntimeException(e);
}
}});
}
@@ -224,7 +225,7 @@
throw e;
}
catch (Throwable e) {
- throw new RuntimeException(e.toString());
+ throw new RuntimeException(e);
}
}
Modified: 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=797561&r1=797560&r2=797561&view=diff
==============================================================================
--- felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/DeploymentException.java (original)
+++ felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/DeploymentException.java Fri Jul 24 17:06:37 2009
@@ -1,7 +1,5 @@
/*
- * $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.
+ * Copyright (c) OSGi Alliance (2005, 2008). 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.
@@ -203,8 +201,6 @@
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.
@@ -215,9 +211,8 @@
* @param cause the originating exception
*/
public DeploymentException(int code, String message, Throwable cause) {
+ super(message, cause);
this.code = code;
- this.message = message;
- this.cause = cause;
}
/**
@@ -229,7 +224,8 @@
* @param message Message associated with the exception
*/
public DeploymentException(int code, String message) {
- this(code, message, null);
+ super(message);
+ this.code = code;
}
/**
@@ -240,27 +236,40 @@
* predefined integer values (<code>CODE_X</code>).
*/
public DeploymentException(int code) {
- this(code, null, null);
+ super();
+ this.code = code;
}
/**
- * @return Returns the cause.
+ * Returns the cause of this exception or <code>null</code> if no cause was
+ * set.
+ *
+ * @return The cause of this exception or <code>null</code> if no cause was
+ * set.
*/
public Throwable getCause() {
- return cause;
+ return super.getCause();
}
/**
- * @return Returns the code.
+ * Initializes the cause of this exception to the specified value.
+ *
+ * @param cause The cause of this exception.
+ * @return This exception.
+ * @throws IllegalArgumentException If the specified cause is this
+ * exception.
+ * @throws IllegalStateException If the cause of this exception has already
+ * been set.
+ * @since 1.1
*/
- public int getCode() {
- return code;
+ public Throwable initCause(Throwable cause) {
+ return super.initCause(cause);
}
/**
- * @return Returns the message.
+ * @return Returns the code.
*/
- public String getMessage() {
- return message;
+ public int getCode() {
+ return code;
}
}
Modified: 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=797561&r1=797560&r2=797561&view=diff
==============================================================================
--- felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/DeploymentPackage.java (original)
+++ felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/DeploymentPackage.java Fri Jul 24 17:06:37 2009
@@ -1,7 +1,5 @@
/*
- * $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.
+ * Copyright (c) OSGi Alliance (2005, 2008). 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.
@@ -18,223 +16,347 @@
package org.osgi.service.deploymentadmin;
-import org.osgi.framework.*;
+import java.net.URL;
+
+import org.osgi.framework.Bundle;
+import org.osgi.framework.ServiceReference;
+import org.osgi.framework.Version;
/**
- * 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.
- */
+ * 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
+ * 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.
+ * <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
+ * The name of the Deployment Package. This name is the same name as that
+ * specified in the DeploymentPackage-SymbolicName Manifest header.
+ *
+ * @since 1.1
+ */
+ String EVENT_DEPLOYMENTPACKAGE_NAME = "deploymentpackage.name";
+
+ /**
+ * The human readable name of the DP localized to the default locale.
+ *
+ * @since 1.1
+ */
+ String EVENT_DEPLOYMENTPACKAGE_READABLENAME = "deploymentpackage.readablename";
+
+ /**
+ * The currently installed version of the Deployment Package. The attribute
+ * is not present, if no version is installed:
+ * <ul>
+ * <li>in the INSTALL event, when an installDeploymentPackage was called and
+ * no earlier version is present
+ * <li>in the COMPLETE event after the _successfully_ completing an
+ * uninstallDeploymentPackage call
+ * </ul>
+ * The value for this event must be a Version object.
+ *
+ * @since 1.1
+ */
+ String EVENT_DEPLOYMENTPACKAGE_CURRENTVERSION = "deploymentpackage.currentversion";
+
+ /**
+ * 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
+ */
+ String EVENT_DEPLOYMENTPACKAGE_NEXTVERSION = "deploymentpackage.nextversion";
+
+ /**
+ * 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();
-
+ boolean isStale();
+
/**
- * Returns the Deployment Pacakage Symbolic Name of the package.
+ * Returns the Deployment Package Symbolic Name of the package.
*
* @return The name of the deployment package. It cannot be null.
*/
String getName();
-
+
+ /**
+ * Returns the Deployment Package human readable name.
+ *
+ * This method returns the localized human readable name as set with the
+ * <code>DeploymentPackage-Name</code> manifest header using the default
+ * locale. If no header is set, this method will return <code>null</code>.
+ *
+ * @return The human readable name of the deployment package or
+ * <code>null</code> if header is not set.
+ * @since 1.1
+ */
+ String getDisplayName();
+
/**
* 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 a URL pointing to an image that represents the icon for this
+ * Deployment Package.
+ *
+ * The <code>DeploymentPackage-Icon</code> header can set an icon for the
+ * 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 <code>URL</code>'s must point to
+ * a local resource.
+ *
+ * @return An absolute URL to a local (device resident) image resource or
+ * <code>null</code> if not found
+ * @since 1.1
+ */
+ URL getIcon();
+
/**
- * 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.
+ * 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>
*
- * @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);
-
+ * 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/package.html
URL: http://svn.apache.org/viewvc/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/package.html?rev=797561&view=auto
==============================================================================
--- felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/package.html (added)
+++ felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/package.html Fri Jul 24 17:06:37 2009
@@ -0,0 +1,10 @@
+<!-- $Revision: 6204 $ -->
+<BODY>
+<p>Deployment Admin Package Version 1.1.
+<p>Bundles wishing to use this package must list the package
+in the Import-Package header of the bundle's manifest.
+For example:
+<pre>
+Import-Package: org.osgi.service.deploymentadmin; version="[1.1,2.0)"
+</pre>
+</BODY>
Added: felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/packageinfo
URL: http://svn.apache.org/viewvc/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/packageinfo?rev=797561&view=auto
==============================================================================
--- felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/packageinfo (added)
+++ felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/packageinfo Fri Jul 24 17:06:37 2009
@@ -0,0 +1 @@
+version 1.1
Modified: 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=797561&r1=797560&r2=797561&view=diff
==============================================================================
--- felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/spi/DeploymentCustomizerPermission.java (original)
+++ felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/spi/DeploymentCustomizerPermission.java Fri Jul 24 17:06:37 2009
@@ -1,8 +1,6 @@
/*
- * $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.
+ * Copyright (c) OSGi Alliance (2005, 2008). 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.
@@ -21,7 +19,10 @@
import java.lang.reflect.Constructor;
import java.lang.reflect.InvocationTargetException;
-import java.security.*;
+import java.security.AccessController;
+import java.security.Permission;
+import java.security.PermissionCollection;
+import java.security.PrivilegedAction;
import org.osgi.service.deploymentadmin.DeploymentAdminPermission;
@@ -65,7 +66,7 @@
return c.getConstructor(new Class[] {String.class, String.class});
}
catch (Exception e) {
- throw new RuntimeException(e.getMessage());
+ throw new RuntimeException(e);
}
}});
}
@@ -112,7 +113,7 @@
throw e;
}
catch (Throwable e) {
- throw new RuntimeException(e.toString());
+ throw new RuntimeException(e);
}
}
Modified: 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=797561&r1=797560&r2=797561&view=diff
==============================================================================
--- felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/spi/DeploymentSession.java (original)
+++ felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/spi/DeploymentSession.java Fri Jul 24 17:06:37 2009
@@ -1,7 +1,5 @@
/*
- * $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.
+ * Copyright (c) OSGi Alliance (2005, 2008). 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.
Modified: 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=797561&r1=797560&r2=797561&view=diff
==============================================================================
--- felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/spi/ResourceProcessor.java (original)
+++ felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/spi/ResourceProcessor.java Fri Jul 24 17:06:37 2009
@@ -1,7 +1,5 @@
/*
- * $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.
+ * Copyright (c) OSGi Alliance (2005, 2008). 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.
Modified: 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=797561&r1=797560&r2=797561&view=diff
==============================================================================
--- felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/spi/ResourceProcessorException.java (original)
+++ felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/spi/ResourceProcessorException.java Fri Jul 24 17:06:37 2009
@@ -1,7 +1,5 @@
/*
- * $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.
+ * Copyright (c) OSGi Alliance (2005, 2008). 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.
@@ -60,8 +58,6 @@
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.
@@ -72,9 +68,8 @@
* @param cause the originating exception
*/
public ResourceProcessorException(int code, String message, Throwable cause) {
+ super(message, cause);
this.code = code;
- this.message = message;
- this.cause = cause;
}
/**
@@ -86,7 +81,8 @@
* @param message Message associated with the exception
*/
public ResourceProcessorException(int code, String message) {
- this(code, message, null);
+ super(message);
+ this.code = code;
}
/**
@@ -97,27 +93,40 @@
* predefined integer values (<code>CODE_X</code>).
*/
public ResourceProcessorException(int code) {
- this(code, null, null);
+ super();
+ this.code = code;
}
/**
- * @return Returns the cause.
+ * Returns the cause of this exception or <code>null</code> if no cause was
+ * set.
+ *
+ * @return The cause of this exception or <code>null</code> if no cause was
+ * set.
*/
public Throwable getCause() {
- return cause;
+ return super.getCause();
}
/**
- * @return Returns the code.
+ * Initializes the cause of this exception to the specified value.
+ *
+ * @param cause The cause of this exception.
+ * @return This exception.
+ * @throws IllegalArgumentException If the specified cause is this
+ * exception.
+ * @throws IllegalStateException If the cause of this exception has already
+ * been set.
+ * @since 1.0.1
*/
- public int getCode() {
- return code;
+ public Throwable initCause(Throwable cause) {
+ return super.initCause(cause);
}
/**
- * @return Returns the message.
+ * @return Returns the code.
*/
- public String getMessage() {
- return message;
+ public int getCode() {
+ return code;
}
}
Added: felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/spi/package.html
URL: http://svn.apache.org/viewvc/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/spi/package.html?rev=797561&view=auto
==============================================================================
--- felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/spi/package.html (added)
+++ felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/spi/package.html Fri Jul 24 17:06:37 2009
@@ -0,0 +1,12 @@
+<!-- $Revision: 6204 $ -->
+<BODY>
+<p>Deployment Admin SPI Package Version 1.0.
+The SPI is used by Resource Processors.
+<p>Bundles wishing to use this package must list the package
+in the Import-Package header of the bundle's manifest.
+For example:
+<pre>
+Import-Package: org.osgi.service.deploymentadmin.spi; version="[1.0,2.0)"
+</pre>
+</BODY>
+</BODY>
Added: felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/spi/packageinfo
URL: http://svn.apache.org/viewvc/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/spi/packageinfo?rev=797561&view=auto
==============================================================================
--- felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/spi/packageinfo (added)
+++ felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/deploymentadmin/spi/packageinfo Fri Jul 24 17:06:37 2009
@@ -0,0 +1 @@
+version 1.0.1
Modified: felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/device/Constants.java
URL: http://svn.apache.org/viewvc/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/device/Constants.java?rev=797561&r1=797560&r2=797561&view=diff
==============================================================================
--- felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/device/Constants.java (original)
+++ felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/device/Constants.java Fri Jul 24 17:06:37 2009
@@ -1,7 +1,5 @@
/*
- * $Header: /cvshome/build/org.osgi.service.device/src/org/osgi/service/device/Constants.java,v 1.9 2006/07/11 00:54:08 hargrave Exp $
- *
- * Copyright (c) OSGi Alliance (2000, 2006). All Rights Reserved.
+ * Copyright (c) OSGi Alliance (2000, 2008). 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.
@@ -25,7 +23,7 @@
* The values associated with these keys are of type <code>java.lang.String</code>,
* unless otherwise stated.
*
- * @version $Revision: 1.9 $
+ * @version $Revision: 5673 $
* @since 1.1
* @see Device
* @see Driver
Modified: felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/device/Device.java
URL: http://svn.apache.org/viewvc/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/device/Device.java?rev=797561&r1=797560&r2=797561&view=diff
==============================================================================
--- felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/device/Device.java (original)
+++ felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/device/Device.java Fri Jul 24 17:06:37 2009
@@ -1,7 +1,5 @@
/*
- * $Header: /cvshome/build/org.osgi.service.device/src/org/osgi/service/device/Device.java,v 1.10 2006/07/11 00:54:08 hargrave Exp $
- *
- * Copyright (c) OSGi Alliance (2000, 2006). All Rights Reserved.
+ * Copyright (c) OSGi Alliance (2000, 2008). 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.
@@ -25,7 +23,8 @@
* A service must implement this interface or use the
* {@link Constants#DEVICE_CATEGORY} registration property to indicate that it
* is a device. Any services implementing this interface or registered with the
- * <code>DEVICE_CATEGORY</code> property will be discovered by the device manager.
+ * <code>DEVICE_CATEGORY</code> property will be discovered by the device
+ * manager.
*
* <p>
* Device services implementing this interface give the device manager the
@@ -37,8 +36,9 @@
* Specialized device implementations will extend this interface by adding
* methods appropriate to their device category to it.
*
- * @version $Revision: 1.10 $
+ * @version $Revision: 5654 $
* @see Driver
+ * @ThreadSafe
*/
public interface Device {
/**
Modified: felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/device/Driver.java
URL: http://svn.apache.org/viewvc/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/device/Driver.java?rev=797561&r1=797560&r2=797561&view=diff
==============================================================================
--- felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/device/Driver.java (original)
+++ felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/device/Driver.java Fri Jul 24 17:06:37 2009
@@ -1,7 +1,5 @@
/*
- * $Header: /cvshome/build/org.osgi.service.device/src/org/osgi/service/device/Driver.java,v 1.11 2006/07/11 00:54:08 hargrave Exp $
- *
- * Copyright (c) OSGi Alliance (2000, 2006). All Rights Reserved.
+ * Copyright (c) OSGi Alliance (2000, 2008). 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.
@@ -27,9 +25,10 @@
* highest for a particular <code>Device</code> object will be instructed by the
* device manager to attach to the <code>Device</code> object.
*
- * @version $Revision: 1.11 $
+ * @version $Revision: 5654 $
* @see Device
* @see DriverLocator
+ * @ThreadSafe
*/
public interface Driver {
/**
@@ -43,8 +42,8 @@
* <p>
* The return value must be one of the possible match values defined in the
* device category definition for the given Device service, or
- * <code>Device.MATCH_NONE</code> if the category of the Device service is not
- * recognized.
+ * <code>Device.MATCH_NONE</code> if the category of the Device service is
+ * not recognized.
*
* <p>
* In order to make its decision, this Driver service may examine the
@@ -61,15 +60,15 @@
* The match function is called by the device manager during the matching
* process.
*
- * @param reference the <code>ServiceReference</code> object of the device to
- * match
+ * @param reference the <code>ServiceReference</code> object of the device
+ * to match
*
* @return value indicating how well this driver can support the given
* Device service, or <code>Device.MATCH_NONE</code> if it cannot
* support the Device service at all
*
* @throws java.lang.Exception if this Driver service cannot examine the
- * Device service
+ * Device service
*/
public int match(ServiceReference reference) throws Exception;
@@ -78,13 +77,13 @@
* given <code>ServiceReference</code> object.
*
* <p>
- * A return value of <code>null</code> indicates that this Driver service has
- * successfully attached to the given Device service. If this Driver service
- * is unable to attach to the given Device service, but knows of a more
- * suitable Driver service, it must return the <code>DRIVER_ID</code> of that
- * Driver service. This allows for the implementation of referring drivers
- * whose only purpose is to refer to other drivers capable of handling a
- * given Device service.
+ * A return value of <code>null</code> indicates that this Driver service
+ * has successfully attached to the given Device service. If this Driver
+ * service is unable to attach to the given Device service, but knows of a
+ * more suitable Driver service, it must return the <code>DRIVER_ID</code>
+ * of that Driver service. This allows for the implementation of referring
+ * drivers whose only purpose is to refer to other drivers capable of
+ * handling a given Device service.
*
* <p>
* After having attached to the Device service, this driver may register the
@@ -94,15 +93,15 @@
* <p>
* This method is called by the device manager.
*
- * @param reference the <code>ServiceReference</code> object of the device to
- * attach to
+ * @param reference the <code>ServiceReference</code> object of the device
+ * to attach to
*
- * @return <code>null</code> if this Driver service has successfully attached
- * to the given Device service, or the <code>DRIVER_ID</code> of a
- * more suitable driver
+ * @return <code>null</code> if this Driver service has successfully
+ * attached to the given Device service, or the
+ * <code>DRIVER_ID</code> of a more suitable driver
*
* @throws java.lang.Exception if the driver cannot attach to the given
- * device and does not know of a more suitable driver
+ * device and does not know of a more suitable driver
*/
public String attach(ServiceReference reference) throws Exception;
}
Modified: felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/device/DriverLocator.java
URL: http://svn.apache.org/viewvc/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/device/DriverLocator.java?rev=797561&r1=797560&r2=797561&view=diff
==============================================================================
--- felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/device/DriverLocator.java (original)
+++ felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/device/DriverLocator.java Fri Jul 24 17:06:37 2009
@@ -1,7 +1,5 @@
/*
- * $Header: /cvshome/build/org.osgi.service.device/src/org/osgi/service/device/DriverLocator.java,v 1.10 2006/07/12 21:22:12 hargrave Exp $
- *
- * Copyright (c) OSGi Alliance (2000, 2006). All Rights Reserved.
+ * Copyright (c) OSGi Alliance (2000, 2008). 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.
@@ -30,8 +28,9 @@
* providers and encapsulate all provider-specific details related to the
* location and acquisition of driver bundles.
*
- * @version $Revision: 1.10 $
+ * @version $Revision: 5654 $
* @see Driver
+ * @ThreadSafe
*/
public interface DriverLocator {
/**
@@ -56,9 +55,9 @@
*
* @param id the <code>DRIVER_ID</code> of the driver that needs to be
* installed.
- * @return An <code>InputStream</code> object from which the driver bundle can
- * be installed or <code>null</code> if the driver with the given ID
- * cannot be located
+ * @return An <code>InputStream</code> object from which the driver bundle
+ * can be installed or <code>null</code> if the driver with the
+ * given ID cannot be located
* @throws java.io.IOException the input stream for the bundle cannot be
* created
*/
Modified: felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/device/DriverSelector.java
URL: http://svn.apache.org/viewvc/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/device/DriverSelector.java?rev=797561&r1=797560&r2=797561&view=diff
==============================================================================
--- felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/device/DriverSelector.java (original)
+++ felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/device/DriverSelector.java Fri Jul 24 17:06:37 2009
@@ -1,7 +1,5 @@
/*
- * $Header: /cvshome/build/org.osgi.service.device/src/org/osgi/service/device/DriverSelector.java,v 1.9 2006/06/16 16:31:29 hargrave Exp $
- *
- * Copyright (c) OSGi Alliance (2001, 2006). All Rights Reserved.
+ * Copyright (c) OSGi Alliance (2001, 2008). 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.
@@ -25,16 +23,18 @@
* least one Driver service matches, the device manager must choose one. If
* there is a Driver Selector service registered with the Framework, the device
* manager will ask it to make the selection. If there is no Driver Selector
- * service, or if it returns an invalid result, or throws an <code>Exception</code>,
- * the device manager uses the default selection strategy.
+ * service, or if it returns an invalid result, or throws an
+ * <code>Exception</code>, the device manager uses the default selection
+ * strategy.
*
- * @version $Revision: 1.9 $
+ * @version $Revision: 5654 $
* @since 1.1
+ * @ThreadSafe
*/
public interface DriverSelector {
/**
- * Return value from <code>DriverSelector.select</code>, if no Driver service
- * should be attached to the Device service. The value is -1.
+ * Return value from <code>DriverSelector.select</code>, if no Driver
+ * service should be attached to the Device service. The value is -1.
*/
public static final int SELECT_NONE = -1;
Modified: felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/device/Match.java
URL: http://svn.apache.org/viewvc/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/device/Match.java?rev=797561&r1=797560&r2=797561&view=diff
==============================================================================
--- felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/device/Match.java (original)
+++ felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/device/Match.java Fri Jul 24 17:06:37 2009
@@ -1,7 +1,5 @@
/*
- * $Header: /cvshome/build/org.osgi.service.device/src/org/osgi/service/device/Match.java,v 1.9 2006/06/16 16:31:29 hargrave Exp $
- *
- * Copyright (c) OSGi Alliance (2001, 2006). All Rights Reserved.
+ * Copyright (c) OSGi Alliance (2001, 2008). 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.
@@ -23,9 +21,10 @@
* Instances of <code>Match</code> are used in the {@link DriverSelector#select}
* method to identify Driver services matching a Device service.
*
- * @version $Revision: 1.9 $
+ * @version $Revision: 5654 $
* @since 1.1
* @see DriverSelector
+ * @ThreadSafe
*/
public interface Match {
/**
Added: felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/device/package.html
URL: http://svn.apache.org/viewvc/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/device/package.html?rev=797561&view=auto
==============================================================================
--- felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/device/package.html (added)
+++ felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/device/package.html Fri Jul 24 17:06:37 2009
@@ -0,0 +1,10 @@
+<!-- $Revision: 6204 $ -->
+<BODY>
+<p>Device Access Package Version 1.1.
+<p>Bundles wishing to use this package must list the package
+in the Import-Package header of the bundle's manifest.
+For example:
+<pre>
+Import-Package: org.osgi.service.device; version="[1.1,2.0)"
+</pre>
+</BODY>
Added: felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/device/packageinfo
URL: http://svn.apache.org/viewvc/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/device/packageinfo?rev=797561&view=auto
==============================================================================
--- felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/device/packageinfo (added)
+++ felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/device/packageinfo Fri Jul 24 17:06:37 2009
@@ -0,0 +1 @@
+version 1.1
Modified: felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/event/Event.java
URL: http://svn.apache.org/viewvc/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/event/Event.java?rev=797561&r1=797560&r2=797561&view=diff
==============================================================================
--- felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/event/Event.java (original)
+++ felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/event/Event.java Fri Jul 24 17:06:37 2009
@@ -1,7 +1,5 @@
/*
- * $Header: /cvshome/build/org.osgi.service.event/src/org/osgi/service/event/Event.java,v 1.8 2006/07/12 13:17:04 hargrave Exp $
- *
- * Copyright (c) OSGi Alliance (2005, 2006). All Rights Reserved.
+ * Copyright (c) OSGi Alliance (2005, 2009). 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.
@@ -18,7 +16,12 @@
package org.osgi.service.event;
-import java.util.*;
+import java.util.Collections;
+import java.util.Dictionary;
+import java.util.Enumeration;
+import java.util.HashMap;
+import java.util.Iterator;
+import java.util.Map;
import org.osgi.framework.Filter;
@@ -26,48 +29,81 @@
* An event.
*
* <code>Event</code> objects are delivered to <code>EventHandler</code>
- * services which subsrcibe to the topic of the event.
+ * services which subscribe to the topic of the event.
*
- * @version $Revision: 1.8 $
+ * @Immutable
+ * @version $Revision: 7003 $
*/
public class Event {
/**
* The topic of this event.
*/
- String topic;
+ private final String topic;
/**
* The properties carried by this event. Keys are strings and values are
* objects
*/
- Hashtable properties;
+ private final Map /* <String,Object> */properties;
/**
* Constructs an event.
*
* @param topic The topic of the event.
- * @param properties The event's properties (may be <code>null</code>).
+ * @param properties The event's properties (may be <code>null</code>). A
+ * property whose key is not of type <code>String</code> will be
+ * ignored.
+ * @throws IllegalArgumentException If topic is not a valid topic name.
+ * @since 1.2
+ */
+ public Event(String topic, Map/* <String,Object> */properties) {
+ validateTopicName(topic);
+ this.topic = topic;
+ int size = (properties == null) ? 1 : (properties.size() + 1);
+ Map p = new HashMap(size);
+ if (properties != null) {
+ for (Iterator iter = properties.keySet().iterator(); iter.hasNext();) {
+ Object key = iter.next();
+ if (key instanceof String) {
+ Object value = properties.get(key);
+ p.put(key, value);
+ }
+ }
+ }
+ p.put(EventConstants.EVENT_TOPIC, topic);
+ this.properties = p; // safely publish the map
+ }
+
+ /**
+ * Constructs an event.
*
+ * @param topic The topic of the event.
+ * @param properties The event's properties (may be <code>null</code>). A
+ * property whose key is not of type <code>String</code> will be
+ * ignored.
* @throws IllegalArgumentException If topic is not a valid topic name.
*/
- public Event(String topic, Dictionary properties) {
+ public Event(String topic, Dictionary/* <String,Object> */properties) {
+ validateTopicName(topic);
this.topic = topic;
- validateTopicName();
- this.properties = new Hashtable();
+ int size = (properties == null) ? 1 : (properties.size() + 1);
+ Map p = new HashMap(size);
if (properties != null) {
for (Enumeration e = properties.keys(); e.hasMoreElements();) {
- String key = (String) e.nextElement();
- Object value = properties.get(key);
- this.properties.put(key, value);
+ Object key = e.nextElement();
+ if (key instanceof String) {
+ Object value = properties.get(key);
+ p.put(key, value);
+ }
}
}
- this.properties.put(EventConstants.EVENT_TOPIC, topic);
+ p.put(EventConstants.EVENT_TOPIC, topic);
+ this.properties = p; // safely publish the map
}
/**
* Retrieves a property.
*
* @param name the name of the property to retrieve
- *
* @return The value of the property, or <code>null</code> if not found.
*/
public final Object getProperty(String name) {
@@ -80,12 +116,8 @@
* @return A non-empty array with one element per property.
*/
public final String[] getPropertyNames() {
- String[] names = new String[properties.size()];
- Enumeration keys = properties.keys();
- for (int i = 0; keys.hasMoreElements(); i++) {
- names[i] = (String) keys.nextElement();
- }
- return names;
+ return (String[]) properties.keySet().toArray(
+ new String[properties.size()]);
}
/**
@@ -98,31 +130,30 @@
}
/**
- * Tests this event's properties against the given filter.
+ * Tests this event's properties against the given filter using a case
+ * sensitive match.
*
* @param filter The filter to test.
- *
* @return true If this event's properties match the filter, false
* otherwise.
*/
public final boolean matches(Filter filter) {
- return filter.matchCase(properties);
+ return filter.matchCase(new UnmodifiableDictionary(properties));
}
/**
* Compares this <code>Event</code> object to another object.
*
* <p>
- * An event is considered to be <b>equal to </b> another
- * event if the topic is equal and the properties are equal.
+ * An event is considered to be <b>equal to</b> another event if the topic
+ * is equal and the properties are equal.
*
* @param object The <code>Event</code> object to be compared.
- * @return <code>true</code> if <code>object</code> is a
- * <code>Event</code> and is equal to this object;
- * <code>false</code> otherwise.
+ * @return <code>true</code> if <code>object</code> is a <code>Event</code>
+ * and is equal to this object; <code>false</code> otherwise.
*/
public boolean equals(Object object) {
- if (object == this) { // quicktest
+ if (object == this) { // quick test
return true;
}
@@ -140,7 +171,9 @@
* @return An integer which is a hash code value for this object.
*/
public int hashCode() {
- return topic.hashCode() ^ properties.hashCode();
+ int h = 31 * 17 + topic.hashCode();
+ h = 31 * h + properties.hashCode();
+ return h;
}
/**
@@ -149,47 +182,82 @@
* @return The string representation of this event.
*/
public String toString() {
- return getClass().getName() + " [topic=" + topic + "]"; //$NON-NLS-1$ //$NON-NLS-2$
+ return getClass().getName() + " [topic=" + topic + "]";
}
- private static final String SEPARATOR = "/"; //$NON-NLS-1$
-
/**
* Called by the constructor to validate the topic name.
*
+ * @param topic The topic name to validate.
* @throws IllegalArgumentException If the topic name is invalid.
*/
- private void validateTopicName() {
- try {
- StringTokenizer st = new StringTokenizer(topic, SEPARATOR, true);
- validateToken(st.nextToken());
-
- while (st.hasMoreTokens()) {
- st.nextToken(); // consume delimiter
- validateToken(st.nextToken());
- }
- }
- catch (NoSuchElementException e) {
- throw new IllegalArgumentException("invalid topic"); //$NON-NLS-1$
+ private static void validateTopicName(String topic) {
+ char[] chars = topic.toCharArray();
+ int length = chars.length;
+ if (length == 0) {
+ throw new IllegalArgumentException("empty topic");
}
+ for (int i = 0; i < length; i++) {
+ char ch = chars[i];
+ if (ch == '/') {
+ // Can't start or end with a '/' but anywhere else is okay
+ if (i == 0 || (i == length - 1)) {
+ throw new IllegalArgumentException(
+ "invalid topic: "
+ + topic);
+ }
+ // Can't have "//" as that implies empty token
+ if (chars[i-1] == '/') {
+ throw new IllegalArgumentException(
+ "invalid topic: "
+ + topic);
+ }
+ continue;
+ }
+ if (('A' <= ch) && (ch <= 'Z')) {
+ continue;
+ }
+ if (('a' <= ch) && (ch <= 'z')) {
+ continue;
+ }
+ if (('0' <= ch) && (ch <= '9')) {
+ continue;
+ }
+ if ((ch == '_') || (ch == '-')) {
+ continue;
+ }
+ throw new IllegalArgumentException("invalid topic: " + topic);
+ }
}
-
- private static final String tokenAlphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_-"; //$NON-NLS-1$
-
+
/**
- * Validate a token.
- *
- * @throws IllegalArgumentException If the token is invalid.
+ * Unmodifiable wrapper for Dictionary.
*/
- private void validateToken(String token) {
- int length = token.length();
- if (length < 1) { // token must contain at least one character
- throw new IllegalArgumentException("invalid topic"); //$NON-NLS-1$
+ private static class UnmodifiableDictionary extends Dictionary {
+ private final Map wrapped;
+ UnmodifiableDictionary(Map wrapped) {
+ this.wrapped = wrapped;
}
- for (int i = 0; i < length; i++) { // each character in the token must be from the token alphabet
- if (tokenAlphabet.indexOf(token.charAt(i)) == -1) { //$NON-NLS-1$
- throw new IllegalArgumentException("invalid topic"); //$NON-NLS-1$
- }
+ public Enumeration elements() {
+ return Collections.enumeration(wrapped.values());
+ }
+ public Object get(Object key) {
+ return wrapped.get(key);
+ }
+ public boolean isEmpty() {
+ return wrapped.isEmpty();
+ }
+ public Enumeration keys() {
+ return Collections.enumeration(wrapped.keySet());
+ }
+ public Object put(Object key, Object value) {
+ throw new UnsupportedOperationException();
+ }
+ public Object remove(Object key) {
+ throw new UnsupportedOperationException();
+ }
+ public int size() {
+ return wrapped.size();
}
}
}
Modified: felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/event/EventAdmin.java
URL: http://svn.apache.org/viewvc/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/event/EventAdmin.java?rev=797561&r1=797560&r2=797561&view=diff
==============================================================================
--- felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/event/EventAdmin.java (original)
+++ felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/event/EventAdmin.java Fri Jul 24 17:06:37 2009
@@ -1,7 +1,5 @@
/*
- * $Header: /cvshome/build/org.osgi.service.event/src/org/osgi/service/event/EventAdmin.java,v 1.6 2006/06/16 16:31:48 hargrave Exp $
- *
- * Copyright (c) OSGi Alliance (2005, 2006). All Rights Reserved.
+ * Copyright (c) OSGi Alliance (2005, 2008). 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.
@@ -22,32 +20,33 @@
* The Event Admin service. Bundles wishing to publish events must obtain the
* Event Admin service and call one of the event delivery methods.
*
- * @version $Revision: 1.6 $
+ * @ThreadSafe
+ * @version $Revision: 5673 $
*/
public interface EventAdmin {
/**
- * Initiate asynchronous delivery of an event. This method returns to
- * the caller before delivery of the event is completed.
+ * Initiate asynchronous delivery of an event. This method returns to the
+ * caller before delivery of the event is completed.
*
- * @param event The event to send to all listeners which subscribe
- * to the topic of the event.
+ * @param event The event to send to all listeners which subscribe to the
+ * topic of the event.
*
* @throws SecurityException If the caller does not have
- * <code>TopicPermission[topic,PUBLISH]</code> for the topic
- * specified in the event.
+ * <code>TopicPermission[topic,PUBLISH]</code> for the topic
+ * specified in the event.
*/
void postEvent(Event event);
/**
- * Initiate synchronous delivery of an event. This method does not
- * return to the caller until delivery of the event is completed.
+ * Initiate synchronous delivery of an event. This method does not return to
+ * the caller until delivery of the event is completed.
*
- * @param event The event to send to all listeners which subscribe
- * to the topic of the event.
+ * @param event The event to send to all listeners which subscribe to the
+ * topic of the event.
*
* @throws SecurityException If the caller does not have
- * <code>TopicPermission[topic,PUBLISH]</code> for the topic
- * specified in the event.
+ * <code>TopicPermission[topic,PUBLISH]</code> for the topic
+ * specified in the event.
*/
void sendEvent(Event event);
}
Modified: felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/event/EventConstants.java
URL: http://svn.apache.org/viewvc/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/event/EventConstants.java?rev=797561&r1=797560&r2=797561&view=diff
==============================================================================
--- felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/event/EventConstants.java (original)
+++ felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/event/EventConstants.java Fri Jul 24 17:06:37 2009
@@ -1,7 +1,5 @@
/*
- * $Header: /cvshome/build/org.osgi.service.event/src/org/osgi/service/event/EventConstants.java,v 1.14 2006/07/12 21:06:18 hargrave Exp $
- *
- * Copyright (c) OSGi Alliance (2005, 2006). All Rights Reserved.
+ * Copyright (c) OSGi Alliance (2005, 2008). 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.
@@ -18,31 +16,34 @@
package org.osgi.service.event;
+import org.osgi.framework.Bundle;
import org.osgi.framework.Constants;
+import org.osgi.framework.Filter;
+import org.osgi.framework.ServiceReference;
+import org.osgi.framework.Version;
/**
- *
* Defines standard names for <code>EventHandler</code> properties.
*
- * @version $Revision: 1.14 $
+ * @version $Revision: 7368 $
*/
public interface EventConstants {
/**
- * Service registration property (named <code>event.topic</code>)
+ * Service registration property (named <code>event.topics</code>)
* specifying the <code>Event</code> topics of interest to a Event Handler
* service.
* <p>
* Event handlers SHOULD be registered with this property. The value of the
- * property is an array of strings that describe the topics in which the
- * handler is interested. An asterisk ('*') may be used as a trailing
- * wildcard. Event Handlers which do not have a value for this property must
- * not receive events. More precisely, the value of each entry in the array
- * must conform to the following grammar:
+ * property is a string or an array of strings that describe the topics in
+ * which the handler is interested. An asterisk ('*') may be used as a
+ * trailing wildcard. Event Handlers which do not have a value for this
+ * property must not receive events. More precisely, the value of each
+ * string must conform to the following grammar:
*
* <pre>
- * topic-description := '*' | topic ( '/*' )?
- * topic := token ( '/' token )*
+ * topic-description := '*' | topic ( '/*' )?
+ * topic := token ( '/' token )*
* </pre>
*
* @see Event
@@ -51,8 +52,8 @@
/**
* Service Registration property (named <code>event.filter</code>)
- * specifying a filter to further select <code>Event</code> s of interest
- * to a Event Handler service.
+ * specifying a filter to further select <code>Event</code> s of interest to
+ * a Event Handler service.
* <p>
* Event handlers MAY be registered with this property. The value of this
* property is a string containing an LDAP-style filter specification. Any
@@ -67,94 +68,116 @@
* and a warning should be logged.
*
* @see Event
- * @see org.osgi.framework.Filter
+ * @see Filter
*/
public static final String EVENT_FILTER = "event.filter";
/**
- * The Distinguished Name of the bundle relevant to the event.
+ * The Distinguished Names of the signers of the bundle relevant to the
+ * event. The type of the value for this event property is
+ * <code>String</code> or <code>Collection</code> of <code>String</code>.
*/
public static final String BUNDLE_SIGNER = "bundle.signer";
/**
- * The Bundle Symbolic Name of the bundle relevant to the event.
+ * The Bundle Symbolic Name of the bundle relevant to the event. The type of
+ * the value for this event property is <code>String</code>.
*/
public static final String BUNDLE_SYMBOLICNAME = "bundle.symbolicName";
/**
- * The Bundle id of the bundle relevant to the event.
+ * The Bundle id of the bundle relevant to the event. The type of the value
+ * for this event property is <code>Long</code>.
*
* @since 1.1
*/
public static final String BUNDLE_ID = "bundle.id";
/**
- * The Bundle object of the bundle relevant to the event.
+ * The Bundle object of the bundle relevant to the event. The type of the
+ * value for this event property is {@link Bundle}.
*
* @since 1.1
*/
public static final String BUNDLE = "bundle";
/**
- * The actual event object. Used when rebroadcasting an event that was sent
- * via some other event mechanism.
+ * The version of the bundle relevant to the event. The type of the value
+ * for this event property is {@link Version}.
+ *
+ * @since 1.2
+ */
+ public static final String BUNDLE_VERSION = "bundle.version";
+
+ /**
+ * The forwarded event object. Used when rebroadcasting an event that was
+ * sent via some other event mechanism. The type of the value for this event
+ * property is <code>Object</code>.
*/
public static final String EVENT = "event";
/**
- * An exception or error.
+ * An exception or error. The type of the value for this event property is
+ * <code>Throwable</code>.
*/
public static final String EXCEPTION = "exception";
/**
- * Must be equal to the name of the Exception class.
+ * The name of the exception type. Must be equal to the name of the class of
+ * the exception in the event property {@link #EXCEPTION}. The type of the
+ * value for this event property is <code>String</code>.
*
* @since 1.1
*/
public static final String EXCEPTION_CLASS = "exception.class";
/**
- * Must be equal to exception.getMessage()
+ * The exception message. Must be equal to the result of calling
+ * <code>getMessage()</code> on the exception in the event property
+ * {@link #EXCEPTION}. The type of the value for this event property is
+ * <code>String</code>.
*/
public static final String EXCEPTION_MESSAGE = "exception.message";
/**
- * A human-readable message that is usually not localized.
+ * A human-readable message that is usually not localized. The type of the
+ * value for this event property is <code>String</code>.
*/
public static final String MESSAGE = "message";
/**
- * A service
+ * A service reference. The type of the value for this event property is
+ * {@link ServiceReference}.
*/
-
public static final String SERVICE = "service";
/**
- * A service's id.
+ * A service's id. The type of the value for this event property is
+ * <code>Long</code>.
*/
public static final String SERVICE_ID = Constants.SERVICE_ID;
/**
- *
- * A service's objectClass
+ * A service's objectClass. The type of the value for this event property is
+ * <code>String[]</code>.
*/
public static final String SERVICE_OBJECTCLASS = "service.objectClass";
/**
- *
- * A service's persistent identity.
+ * A service's persistent identity. The type of the value for this event
+ * property is <code>String</code>.
*/
public static final String SERVICE_PID = Constants.SERVICE_PID;
/**
- *
* The time when the event occurred, as reported by
- * System.currentTimeMillis()
+ * <code>System.currentTimeMillis()</code>. The type of the value for this
+ * event property is <code>Long</code>.
*/
public static final String TIMESTAMP = "timestamp";
/**
- * This constant was released with an incorrect spelling. It has been
+ * This constant was released with an incorrectly spelled name. It has been
* replaced by {@link #EXCEPTION_CLASS}
*
* @deprecated As of 1.1, replaced by EXCEPTION_CLASS
Modified: felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/event/EventHandler.java
URL: http://svn.apache.org/viewvc/felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/event/EventHandler.java?rev=797561&r1=797560&r2=797561&view=diff
==============================================================================
--- felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/event/EventHandler.java (original)
+++ felix/trunk/org.osgi.compendium/src/main/java/org/osgi/service/event/EventHandler.java Fri Jul 24 17:06:37 2009
@@ -1,7 +1,5 @@
/*
- * $Header: /cvshome/build/org.osgi.service.event/src/org/osgi/service/event/EventHandler.java,v 1.10 2006/07/11 16:43:59 hargrave Exp $
- *
- * Copyright (c) OSGi Alliance (2005, 2006). All Rights Reserved.
+ * Copyright (c) OSGi Alliance (2005, 2008). 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.
@@ -23,43 +21,47 @@
*
* <p>
* <code>EventHandler</code> objects are registered with the Framework service
- * registry and are notified with an <code>Event</code> object when an
- * event is sent or posted.
+ * registry and are notified with an <code>Event</code> object when an event
+ * is sent or posted.
* <p>
* <code>EventHandler</code> objects can inspect the received
* <code>Event</code> object to determine its topic and properties.
*
* <p>
* <code>EventHandler</code> objects must be registered with a service
- * property {@link EventConstants#EVENT_TOPIC} whose value is the list of
- * topics in which the event handler is interesed.
+ * property {@link EventConstants#EVENT_TOPIC} whose value is the list of topics
+ * in which the event handler is interested.
* <p>
* For example:
*
* <pre>
- * String[] topics = new String[] {EventConstants.EVENT_TOPIC, "com/isv/*"};
+ * String[] topics = new String[] {"com/isv/*"};
* Hashtable ht = new Hashtable();
- * ht.put(EVENT_TOPIC, topics);
+ * ht.put(EventConstants.EVENT_TOPIC, topics);
* context.registerService(EventHandler.class.getName(), this, ht);
* </pre>
- * Event Handler services can also be registered with an {@link EventConstants#EVENT_FILTER}
- * service propery to further filter the events. If the syntax of this filter is invalid,
- * then the Event Handler must be ignored by the Event Admin service. The Event Admin
- * service should log a warning.
+ *
+ * Event Handler services can also be registered with an
+ * {@link EventConstants#EVENT_FILTER} service property to further filter the
+ * events. If the syntax of this filter is invalid, then the Event Handler must
+ * be ignored by the Event Admin service. The Event Admin service should log a
+ * warning.
* <p>
* Security Considerations. Bundles wishing to monitor <code>Event</code>
* objects will require <code>ServicePermission[EventHandler,REGISTER]</code>
* to register an <code>EventHandler</code> service. The bundle must also have
- * <code>TopicPermission[topic,SUBSCRIBE]</code> for the topic specified in the
- * event in order to receive the event.
+ * <code>TopicPermission[topic,SUBSCRIBE]</code> for the topic specified in
+ * the event in order to receive the event.
*
* @see Event
*
- * @version $Revision: 1.10 $
+ * @ThreadSafe
+ * @version $Revision: 5673 $
*/
public interface EventHandler {
/**
- * Called by the {@link EventAdmin} service to notify the listener of an event.
+ * Called by the {@link EventAdmin} service to notify the listener of an
+ * event.
*
* @param event The event that occurred.
*/