Skip to main content
aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorThomas Watson2019-01-14 20:59:47 +0000
committerThomas Watson2019-01-16 13:56:09 +0000
commit0adca0fc6508387995616781feebf6875e0a882d (patch)
treea40f7fb78ad8808bd93cb9e69ca72cce6a3cfb70 /bundles/org.eclipse.osgi.services
parentfee68c5ccedbb11974ece1025e8b56200eb986e0 (diff)
downloadrt.equinox.framework-0adca0fc6508387995616781feebf6875e0a882d.tar.gz
rt.equinox.framework-0adca0fc6508387995616781feebf6875e0a882d.tar.xz
rt.equinox.framework-0adca0fc6508387995616781feebf6875e0a882d.zip
Bug 538717 - Update org.osgi.service.cm package for OSGi R7I20190117-2335
Change-Id: I05e4a6a7fb6249e30b1c34ce637d0dadb943032a Signed-off-by: Thomas Watson <tjwatson@us.ibm.com>
Diffstat (limited to 'bundles/org.eclipse.osgi.services')
-rw-r--r--bundles/org.eclipse.osgi.services/.settings/.api_filters148
-rw-r--r--bundles/org.eclipse.osgi.services/META-INF/MANIFEST.MF6
-rw-r--r--bundles/org.eclipse.osgi.services/pom.xml2
-rw-r--r--bundles/org.eclipse.osgi.services/src/org/osgi/service/cm/Configuration.java218
-rw-r--r--bundles/org.eclipse.osgi.services/src/org/osgi/service/cm/ConfigurationAdmin.java122
-rw-r--r--bundles/org.eclipse.osgi.services/src/org/osgi/service/cm/ConfigurationConstants.java46
-rw-r--r--bundles/org.eclipse.osgi.services/src/org/osgi/service/cm/ConfigurationEvent.java36
-rw-r--r--bundles/org.eclipse.osgi.services/src/org/osgi/service/cm/ConfigurationException.java18
-rw-r--r--bundles/org.eclipse.osgi.services/src/org/osgi/service/cm/ConfigurationListener.java10
-rw-r--r--bundles/org.eclipse.osgi.services/src/org/osgi/service/cm/ConfigurationPermission.java108
-rw-r--r--bundles/org.eclipse.osgi.services/src/org/osgi/service/cm/ConfigurationPlugin.java29
-rw-r--r--bundles/org.eclipse.osgi.services/src/org/osgi/service/cm/ManagedService.java38
-rw-r--r--bundles/org.eclipse.osgi.services/src/org/osgi/service/cm/ManagedServiceFactory.java52
-rw-r--r--bundles/org.eclipse.osgi.services/src/org/osgi/service/cm/ReadOnlyConfigurationException.java40
-rw-r--r--bundles/org.eclipse.osgi.services/src/org/osgi/service/cm/SynchronousConfigurationListener.java8
-rw-r--r--bundles/org.eclipse.osgi.services/src/org/osgi/service/cm/package-info.java16
-rw-r--r--bundles/org.eclipse.osgi.services/src/org/osgi/service/cm/packageinfo1
17 files changed, 577 insertions, 321 deletions
diff --git a/bundles/org.eclipse.osgi.services/.settings/.api_filters b/bundles/org.eclipse.osgi.services/.settings/.api_filters
index 4398895df..7fc488fb5 100644
--- a/bundles/org.eclipse.osgi.services/.settings/.api_filters
+++ b/bundles/org.eclipse.osgi.services/.settings/.api_filters
@@ -1,127 +1,131 @@
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<component id="org.eclipse.osgi.services" version="2">
- <resource path="src/org/osgi/service/event/EventConstants.java" type="org.osgi.service.event.EventConstants">
- <filter id="403767336">
+ <resource path="src/org/osgi/service/cm/Configuration.java" type="org.osgi.service.cm.Configuration">
+ <filter comment="Ignore OSGi API" id="403804204">
<message_arguments>
- <message_argument value="org.osgi.service.event.EventConstants"/>
- <message_argument value="EVENT_ADMIN_IMPLEMENTATION"/>
+ <message_argument value="org.osgi.service.cm.Configuration"/>
+ <message_argument value="addAttributes(Configuration.ConfigurationAttribute[])"/>
</message_arguments>
</filter>
- <filter id="403767336">
+ <filter comment="Ignore OSGi API" id="403804204">
<message_arguments>
- <message_argument value="org.osgi.service.event.EventConstants"/>
- <message_argument value="EVENT_ADMIN_SPECIFICATION_VERSION"/>
+ <message_argument value="org.osgi.service.cm.Configuration"/>
+ <message_argument value="getAttributes()"/>
</message_arguments>
</filter>
- <filter id="1209008130">
+ <filter comment="Ignore OSGi API" id="403804204">
<message_arguments>
- <message_argument value="1.4"/>
- <message_argument value="3.7"/>
- <message_argument value="EVENT_ADMIN_IMPLEMENTATION"/>
+ <message_argument value="org.osgi.service.cm.Configuration"/>
+ <message_argument value="getProcessedProperties(ServiceReference&lt;?&gt;)"/>
</message_arguments>
</filter>
- <filter id="1209008130">
+ <filter comment="Ignore OSGi API" id="403804204">
<message_arguments>
- <message_argument value="1.4"/>
- <message_argument value="3.7"/>
- <message_argument value="EVENT_ADMIN_SPECIFICATION_VERSION"/>
+ <message_argument value="org.osgi.service.cm.Configuration"/>
+ <message_argument value="removeAttributes(Configuration.ConfigurationAttribute[])"/>
</message_arguments>
</filter>
- </resource>
- <resource path="src/org/osgi/service/log/FormatterLogger.java" type="org.osgi.service.log.FormatterLogger">
- <filter id="1108344834">
+ <filter comment="Ignore OSGi API" id="403804204">
<message_arguments>
- <message_argument value="1.4"/>
- <message_argument value="3.7"/>
- <message_argument value="org.osgi.service.log.FormatterLogger"/>
+ <message_argument value="org.osgi.service.cm.Configuration"/>
+ <message_argument value="updateIfDifferent(Dictionary&lt;String,?&gt;)"/>
</message_arguments>
</filter>
- </resource>
- <resource path="src/org/osgi/service/log/LogEntry.java" type="org.osgi.service.log.LogEntry">
- <filter id="1209008130">
+ <filter comment="Ignore OSGi API" id="1209008130">
<message_arguments>
- <message_argument value="1.4"/>
- <message_argument value="3.7"/>
- <message_argument value="getLocation()"/>
+ <message_argument value="1.6"/>
+ <message_argument value="3.8"/>
+ <message_argument value="addAttributes(Configuration.ConfigurationAttribute[])"/>
</message_arguments>
</filter>
- <filter id="1209008130">
+ <filter comment="Ignore OSGi API" id="1209008130">
<message_arguments>
- <message_argument value="1.4"/>
- <message_argument value="3.7"/>
- <message_argument value="getLogLevel()"/>
+ <message_argument value="1.6"/>
+ <message_argument value="3.8"/>
+ <message_argument value="getAttributes()"/>
</message_arguments>
</filter>
- <filter id="1209008130">
+ <filter comment="Ignore OSGi API" id="1209008130">
<message_arguments>
- <message_argument value="1.4"/>
- <message_argument value="3.7"/>
- <message_argument value="getLoggerName()"/>
+ <message_argument value="1.6"/>
+ <message_argument value="3.8"/>
+ <message_argument value="getProcessedProperties(ServiceReference&lt;?&gt;)"/>
</message_arguments>
</filter>
- <filter id="1209008130">
+ <filter comment="Ignore OSGi API" id="1209008130">
<message_arguments>
- <message_argument value="1.4"/>
- <message_argument value="3.7"/>
- <message_argument value="getSequence()"/>
+ <message_argument value="1.6"/>
+ <message_argument value="3.8"/>
+ <message_argument value="removeAttributes(Configuration.ConfigurationAttribute[])"/>
</message_arguments>
</filter>
- <filter id="1209008130">
+ <filter comment="Ignore OSGi API" id="1209008130">
<message_arguments>
- <message_argument value="1.4"/>
- <message_argument value="3.7"/>
- <message_argument value="getThreadInfo()"/>
+ <message_argument value="1.6"/>
+ <message_argument value="3.8"/>
+ <message_argument value="updateIfDifferent(Dictionary&lt;String,?&gt;)"/>
</message_arguments>
</filter>
</resource>
- <resource path="src/org/osgi/service/log/LogLevel.java" type="org.osgi.service.log.LogLevel">
- <filter id="1108344834">
+ <resource path="src/org/osgi/service/cm/Configuration.java" type="org.osgi.service.cm.Configuration$ConfigurationAttribute">
+ <filter comment="Ignore OSGi API" id="1209008130">
<message_arguments>
- <message_argument value="1.4"/>
- <message_argument value="3.7"/>
- <message_argument value="org.osgi.service.log.LogLevel"/>
+ <message_argument value="1.6"/>
+ <message_argument value="3.8"/>
+ <message_argument value="ConfigurationAttribute"/>
</message_arguments>
</filter>
</resource>
- <resource path="src/org/osgi/service/log/Logger.java" type="org.osgi.service.log.Logger">
- <filter id="1108344834">
+ <resource path="src/org/osgi/service/cm/ConfigurationAdmin.java" type="org.osgi.service.cm.ConfigurationAdmin">
+ <filter comment="Ignore OSGi API" id="403804204">
<message_arguments>
- <message_argument value="1.4"/>
- <message_argument value="3.7"/>
- <message_argument value="org.osgi.service.log.Logger"/>
+ <message_argument value="org.osgi.service.cm.ConfigurationAdmin"/>
+ <message_argument value="getFactoryConfiguration(String, String)"/>
</message_arguments>
</filter>
- </resource>
- <resource path="src/org/osgi/service/log/LoggerConsumer.java" type="org.osgi.service.log.LoggerConsumer">
- <filter id="1108344834">
+ <filter comment="Ignore OSGi API" id="403804204">
+ <message_arguments>
+ <message_argument value="org.osgi.service.cm.ConfigurationAdmin"/>
+ <message_argument value="getFactoryConfiguration(String, String, String)"/>
+ </message_arguments>
+ </filter>
+ <filter comment="Ignore OSGi API" id="1209008130">
<message_arguments>
- <message_argument value="1.4"/>
- <message_argument value="3.7"/>
- <message_argument value="org.osgi.service.log.LoggerConsumer"/>
+ <message_argument value="1.6"/>
+ <message_argument value="3.8"/>
+ <message_argument value="getFactoryConfiguration(String, String)"/>
+ </message_arguments>
+ </filter>
+ <filter comment="Ignore OSGi API" id="1209008130">
+ <message_arguments>
+ <message_argument value="1.6"/>
+ <message_argument value="3.8"/>
+ <message_argument value="getFactoryConfiguration(String, String, String)"/>
</message_arguments>
</filter>
</resource>
- <resource path="src/org/osgi/service/log/LoggerFactory.java" type="org.osgi.service.log.LoggerFactory">
- <filter id="1108344834">
+ <resource path="src/org/osgi/service/cm/ConfigurationConstants.java" type="org.osgi.service.cm.ConfigurationConstants">
+ <filter comment="Ignore OSGi API" id="1110441988">
<message_arguments>
- <message_argument value="1.4"/>
- <message_argument value="3.7"/>
- <message_argument value="org.osgi.service.log.LoggerFactory"/>
+ <message_argument value="org.osgi.service.cm.ConfigurationConstants"/>
</message_arguments>
</filter>
</resource>
- <resource path="src/org/osgi/service/metatype/MetaTypeService.java" type="org.osgi.service.metatype.MetaTypeService">
- <filter id="403767336">
+ <resource path="src/org/osgi/service/cm/ConfigurationPermission.java" type="org.osgi.service.cm.ConfigurationPermission">
+ <filter comment="Ignore OSGi API" id="1141899266">
<message_arguments>
- <message_argument value="org.osgi.service.metatype.MetaTypeService"/>
- <message_argument value="METATYPE_SPECIFICATION_VERSION"/>
+ <message_argument value="1.6"/>
+ <message_argument value="3.8"/>
+ <message_argument value="ATTRIBUTE"/>
</message_arguments>
</filter>
- <filter id="1209008130">
+ </resource>
+ <resource path="src/org/osgi/service/cm/ReadOnlyConfigurationException.java" type="org.osgi.service.cm.ReadOnlyConfigurationException">
+ <filter comment="Ignore OSGi API" id="1108344834">
<message_arguments>
- <message_argument value="1.4"/>
- <message_argument value="3.7"/>
- <message_argument value="METATYPE_SPECIFICATION_VERSION"/>
+ <message_argument value="1.6"/>
+ <message_argument value="3.8"/>
+ <message_argument value="org.osgi.service.cm.ReadOnlyConfigurationException"/>
</message_arguments>
</filter>
</resource>
diff --git a/bundles/org.eclipse.osgi.services/META-INF/MANIFEST.MF b/bundles/org.eclipse.osgi.services/META-INF/MANIFEST.MF
index 41fa4d1d3..e9d9afb02 100644
--- a/bundles/org.eclipse.osgi.services/META-INF/MANIFEST.MF
+++ b/bundles/org.eclipse.osgi.services/META-INF/MANIFEST.MF
@@ -2,13 +2,13 @@ Manifest-Version: 1.0
Bundle-ManifestVersion: 2
Bundle-Name: %osgiServices
Bundle-SymbolicName: org.eclipse.osgi.services
-Bundle-Version: 3.7.200.qualifier
+Bundle-Version: 3.8.0.qualifier
Bundle-Description: %osgiServicesDes
Bundle-Localization: plugin
Bundle-Vendor: %eclipse.org
Bundle-DocUrl: http://www.eclipse.org
Bundle-ContactAddress: www.eclipse.org
-Export-Package: org.osgi.service.cm;version="1.5";uses:="org.osgi.framework",
+Export-Package: org.osgi.service.cm;version="1.6";uses:="org.osgi.framework",
org.osgi.service.component;version="1.3";uses:="org.osgi.framework",
org.osgi.service.component.annotations;version="1.3",
org.osgi.service.component.runtime;version="1.3";uses:="org.osgi.framework,org.osgi.util.promise,org.osgi.service.component.runtime.dto",
@@ -31,7 +31,7 @@ Import-Package: javax.servlet;resolution:=optional,
org.osgi.dto;version="1.0",
org.osgi.framework;version="1.6",
org.osgi.framework.dto;version="1.8.0",
- org.osgi.service.cm;version="[1.5,1.6)",
+ org.osgi.service.cm;version="[1.6,1.7)",
org.osgi.service.component;version="[1.3,1.4)",
org.osgi.service.component.annotations;version="[1.3,1.4)",
org.osgi.service.component.runtime; version="[1.3,1.4)",
diff --git a/bundles/org.eclipse.osgi.services/pom.xml b/bundles/org.eclipse.osgi.services/pom.xml
index 1589d9c59..6e383dbda 100644
--- a/bundles/org.eclipse.osgi.services/pom.xml
+++ b/bundles/org.eclipse.osgi.services/pom.xml
@@ -19,7 +19,7 @@
</parent>
<groupId>org.eclipse.osgi</groupId>
<artifactId>org.eclipse.osgi.services</artifactId>
- <version>3.7.200-SNAPSHOT</version>
+ <version>3.8.0-SNAPSHOT</version>
<packaging>eclipse-plugin</packaging>
<build>
<plugins>
diff --git a/bundles/org.eclipse.osgi.services/src/org/osgi/service/cm/Configuration.java b/bundles/org.eclipse.osgi.services/src/org/osgi/service/cm/Configuration.java
index b9057fdde..81d3935dc 100644
--- a/bundles/org.eclipse.osgi.services/src/org/osgi/service/cm/Configuration.java
+++ b/bundles/org.eclipse.osgi.services/src/org/osgi/service/cm/Configuration.java
@@ -1,5 +1,5 @@
/*
- * Copyright (c) OSGi Alliance (2001, 2013). All Rights Reserved.
+ * Copyright (c) OSGi Alliance (2001, 2018). 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,17 +18,18 @@ package org.osgi.service.cm;
import java.io.IOException;
import java.util.Dictionary;
+import java.util.Set;
+
import org.osgi.annotation.versioning.ProviderType;
import org.osgi.framework.Filter;
+import org.osgi.framework.ServiceReference;
/**
* The configuration information for a {@code ManagedService} or
- * {@code ManagedServiceFactory} object.
- *
- * The Configuration Admin service uses this interface to represent the
- * configuration information for a {@code ManagedService} or for a service
- * instance of a {@code ManagedServiceFactory}.
- *
+ * {@code ManagedServiceFactory} object. The Configuration Admin service uses
+ * this interface to represent the configuration information for a
+ * {@code ManagedService} or for a service instance of a
+ * {@code ManagedServiceFactory}.
* <p>
* A {@code Configuration} object contains a configuration dictionary and allows
* the properties to be updated via this object. Bundles wishing to receive
@@ -36,7 +37,6 @@ import org.osgi.framework.Filter;
* {@code ManagedService} or {@code ManagedServiceFactory}. Only administrative
* bundles, and bundles wishing to update their own configurations need to use
* this class.
- *
* <p>
* The properties handled in this configuration have case insensitive
* {@code String} objects as keys. However, case must be preserved from the last
@@ -47,20 +47,16 @@ import org.osgi.framework.Filter;
* location of the target bundle that registered a Managed Service or a Managed
* Service Factory. However, if the location starts with {@code ?} then the
* location indicates multiple delivery. In such a case the configuration must
- * be delivered to all targets.
- *
- * If security is on, the Configuration Permission can be used to restrict the
- * targets that receive updates. The Configuration Admin must only update a
- * target when the configuration location matches the location of the target's
- * bundle or the target bundle has a Configuration Permission with the action
- * {@link ConfigurationPermission#TARGET} and a name that matches the
- * configuration location. The name in the permission may contain wildcards (
- * {@code '*'}) to match the location using the same substring matching rules as
- * {@link Filter}.
- *
- * Bundles can always create, manipulate, and be updated from configurations
- * that have a location that matches their bundle location.
- *
+ * be delivered to all targets. If security is on, the Configuration Permission
+ * can be used to restrict the targets that receive updates. The Configuration
+ * Admin must only update a target when the configuration location matches the
+ * location of the target's bundle or the target bundle has a Configuration
+ * Permission with the action {@link ConfigurationPermission#TARGET} and a name
+ * that matches the configuration location. The name in the permission may
+ * contain wildcards ( {@code '*'}) to match the location using the same
+ * substring matching rules as {@link Filter}. Bundles can always create,
+ * manipulate, and be updated from configurations that have a location that
+ * matches their bundle location.
* <p>
* If a configuration's location is {@code null}, it is not yet bound to a
* location. It will become bound to the location of the first bundle that
@@ -70,15 +66,26 @@ import org.osgi.framework.Filter;
* The same {@code Configuration} object is used for configuring both a Managed
* Service Factory and a Managed Service. When it is important to differentiate
* between these two the term "factory configuration" is used.
- *
+ *
* @author $Id$
* @ThreadSafe
*/
@ProviderType
public interface Configuration {
/**
+ * Configuration Attributes.
+ * @since 1.6
+ */
+ enum ConfigurationAttribute {
+ /**
+ * The configuration is read only.
+ */
+ READ_ONLY;
+ }
+
+ /**
* Get the PID for this {@code Configuration} object.
- *
+ *
* @return the PID for this {@code Configuration} object.
* @throws IllegalStateException if this configuration has been deleted
*/
@@ -86,16 +93,16 @@ public interface Configuration {
/**
* Return the properties of this {@code Configuration} object.
- *
+ *
* The {@code Dictionary} object returned is a private copy for the caller
* and may be changed without influencing the stored configuration. The keys
* in the returned dictionary are case insensitive and are always of type
* {@code String}.
- *
+ *
* <p>
* If called just after the configuration is created and before update has
* been called, this method returns {@code null}.
- *
+ *
* @return A private copy of the properties for the caller or {@code null}.
* These properties must not contain the "service.bundleLocation"
* property. The value of this property may be obtained from the
@@ -104,9 +111,36 @@ public interface Configuration {
*/
public Dictionary<String, Object> getProperties();
- /**
+ /**
+ * Return the processed properties of this {@code Configuration} object.
+ * <p>
+ * The {@code Dictionary} object returned is a private copy for the caller
+ * and may be changed without influencing the stored configuration. The keys
+ * in the returned dictionary are case insensitive and are always of type
+ * {@code String}.
+ * <p>
+ * Before the properties are returned they are processed by all the
+ * registered {@link ConfigurationPlugin}s handling this configuration.
+ * <p>
+ * If called just after the configuration is created and before update has
+ * been called, this method returns {@code null}.
+ *
+ * @param reference The reference to the Managed Service or Managed Service
+ * Factory to pass to the registered {@link ConfigurationPlugin}s
+ * handling this configuration. Must not be {@code null}.
+ * @return A private copy of the processed properties for the caller or
+ * {@code null}. These properties must not contain the
+ * "service.bundleLocation" property. The value of this property may
+ * be obtained from the {@link #getBundleLocation()} method.
+ * @throws IllegalStateException If this configuration has been deleted.
+ * @since 1.6
+ */
+ public Dictionary<String,Object> getProcessedProperties(
+ ServiceReference< ? > reference);
+
+ /**
* Update the properties of this {@code Configuration} object.
- *
+ * <p>
* Stores the properties in persistent storage after adding or overwriting
* the following properties:
* <ul>
@@ -115,39 +149,40 @@ public interface Configuration {
* to the factory PID else it is not set.</li>
* </ul>
* These system properties are all of type {@code String}.
- *
* <p>
* If the corresponding Managed Service/Managed Service Factory is
* registered, its updated method must be called asynchronously. Else, this
* callback is delayed until aforementioned registration occurs.
- *
* <p>
* Also notifies all Configuration Listeners with a
* {@link ConfigurationEvent#CM_UPDATED} event.
- *
+ *
* @param properties the new set of properties for this configuration
+ * @throws ReadOnlyConfigurationException If the configuration is
+ * {@link ConfigurationAttribute#READ_ONLY read only}.
* @throws IOException if update cannot be made persistent
* @throws IllegalArgumentException if the {@code Dictionary} object
- * contains invalid configuration types or contains case variants of
- * the same key name.
+ * contains invalid configuration types or contains case
+ * variants of the same key name.
* @throws IllegalStateException If this configuration has been deleted.
*/
public void update(Dictionary<String, ?> properties) throws IOException;
/**
* Delete this {@code Configuration} object.
- *
+ * <p>
* Removes this configuration object from the persistent store. Notify
* asynchronously the corresponding Managed Service or Managed Service
* Factory. A {@link ManagedService} object is notified by a call to its
* {@code updated} method with a {@code null} properties argument. A
* {@link ManagedServiceFactory} object is notified by a call to its
* {@code deleted} method.
- *
* <p>
* Also notifies all Configuration Listeners with a
* {@link ConfigurationEvent#CM_DELETED} event.
- *
+ *
+ * @throws ReadOnlyConfigurationException If the configuration is
+ * {@link ConfigurationAttribute#READ_ONLY read only}.
* @throws IOException If delete fails.
* @throws IllegalStateException If this configuration has been deleted.
*/
@@ -156,7 +191,7 @@ public interface Configuration {
/**
* For a factory configuration return the PID of the corresponding Managed
* Service Factory, else return {@code null}.
- *
+ *
* @return factory PID or {@code null}
* @throws IllegalStateException If this configuration has been deleted.
*/
@@ -164,51 +199,77 @@ public interface Configuration {
/**
* Update the {@code Configuration} object with the current properties.
- *
* Initiate the {@code updated} callback to the Managed Service or Managed
* Service Factory with the current properties asynchronously.
- *
* <p>
* This is the only way for a bundle that uses a Configuration Plugin
* service to initiate a callback. For example, when that bundle detects a
* change that requires an update of the Managed Service or Managed Service
* Factory via its {@code ConfigurationPlugin} object.
- *
+ *
* @see ConfigurationPlugin
* @throws IOException if update cannot access the properties in persistent
- * storage
+ * storage
* @throws IllegalStateException If this configuration has been deleted.
*/
public void update() throws IOException;
/**
- * Bind this {@code Configuration} object to the specified location.
+ * Update the properties of this {@code Configuration} object if the
+ * provided properties are different than the currently stored set.
+ * Properties are compared as follows.
+ * <ul>
+ * <li>Scalars are compared using {@code equals}</li>
+ * <li>Arrays are compared using {@code Arrays.equals}</li>
+ * <li>Collections are compared using {@code equals}</li>
+ * </ul>
+ * If the new properties are not different than the current properties, no
+ * operation is performed. Otherwise, the behavior of this method is
+ * identical to the {@link #update(Dictionary)} method.
*
+ * @param properties The new set of properties for this configuration.
+ * @return If the properties are different and the configuration is updated
+ * {@code true} is returned. If the properties are the same,
+ * {@code false} is returned.
+ * @throws ReadOnlyConfigurationException If the configuration is
+ * {@link ConfigurationAttribute#READ_ONLY read only}.
+ * @throws IOException If update cannot be made persistent.
+ * @throws IllegalArgumentException If the {@code Dictionary} object
+ * contains invalid configuration types or contains case
+ * variants of the same key name.
+ * @throws IllegalStateException If this configuration has been deleted.
+ * @since 1.6
+ */
+ public boolean updateIfDifferent(Dictionary<String, ? > properties)
+ throws IOException;
+
+ /**
+ * Bind this {@code Configuration} object to the specified location.
+ *
* If the location parameter is {@code null} then the {@code Configuration}
* object will not be bound to a location/region. It will be set to the
* bundle's location before the first time a Managed Service/Managed Service
* Factory receives this {@code Configuration} object via the updated method
* and before any plugins are called. The bundle location or region will be
* set persistently.
- *
+ *
* <p>
* If the location starts with {@code ?} then all targets registered with
* the given PID must be updated.
- *
+ *
* <p>
* If the location is changed then existing targets must be informed. If
* they can no longer see this configuration, the configuration must be
* deleted or updated with {@code null}. If this configuration becomes
* visible then they must be updated with this configuration.
- *
+ *
* <p>
* Also notifies all Configuration Listeners with a
* {@link ConfigurationEvent#CM_LOCATION_CHANGED} event.
- *
+ *
* @param location a location, region, or {@code null}
* @throws IllegalStateException If this configuration has been deleted.
* @throws SecurityException when the required permissions are not available
- * @throws SecurityException when the required permissions are not available
* @security ConfigurationPermission[this.location,CONFIGURE] if
* this.location is not {@code null}
* @security ConfigurationPermission[location,CONFIGURE] if location is not
@@ -220,12 +281,12 @@ public interface Configuration {
/**
* Get the bundle location.
- *
+ *
* Returns the bundle location or region to which this configuration is
* bound, or {@code null} if it is not yet bound to a bundle location or
* region. If the location starts with {@code ?} then the configuration is
* delivered to all targets and not restricted to a single bundle.
- *
+ *
* @return location to which this configuration is bound, or {@code null}.
* @throws IllegalStateException If this configuration has been deleted.
* @throws SecurityException when the required permissions are not available
@@ -233,18 +294,18 @@ public interface Configuration {
* this.location is not {@code null}
* @security ConfigurationPermission["*",CONFIGURE] if this.location is
* {@code null}
- *
+ *
*/
public String getBundleLocation();
/**
* Get the change count.
- *
+ *
* Each Configuration must maintain a change counter that is incremented
* with a positive value every time the configuration is updated and its
* properties are stored. The counter must be incremented before the targets
* are updated and events are sent out.
- *
+ *
* @return A monotonically increasing value reflecting changes in this
* Configuration.
* @throws IllegalStateException If this configuration has been deleted.
@@ -253,23 +314,66 @@ public interface Configuration {
public long getChangeCount();
/**
- * Equality is defined to have equal PIDs
+ * Add attributes to the configuration.
*
- * Two Configuration objects are equal when their PIDs are equal.
+ * @param attrs The attributes to add.
+ * @throws IOException If the new state cannot be persisted.
+ * @throws IllegalStateException If this configuration has been deleted.
+ * @throws SecurityException when the required permissions are not available
+ * @security ConfigurationPermission[this.location,ATTRIBUTE] if
+ * this.location is not {@code null}
+ * @security ConfigurationPermission["*",ATTRIBUTE] if this.location is
+ * {@code null}
+ * @since 1.6
+ */
+ public void addAttributes(ConfigurationAttribute... attrs)
+ throws IOException;
+
+ /**
+ * Get the attributes of this configuration.
+ *
+ * @return The set of attributes.
+ * @throws IllegalStateException If this configuration has been deleted.
+ * @since 1.6
+ */
+ public Set<ConfigurationAttribute> getAttributes();
+
+ /**
+ * Remove attributes from this configuration.
*
+ * @param attrs The attributes to remove.
+ * @throws IOException If the new state cannot be persisted.
+ * @throws IllegalStateException If this configuration has been deleted.
+ * @throws SecurityException when the required permissions are not available
+ * @security ConfigurationPermission[this.location,ATTRIBUTE] if
+ * this.location is not {@code null}
+ * @security ConfigurationPermission["*",ATTRIBUTE] if this.location is
+ * {@code null}
+ * @since 1.6
+ */
+ public void removeAttributes(ConfigurationAttribute... attrs)
+ throws IOException;
+
+ /**
+ * Equality is defined to have equal PIDs
+ *
+ * Two Configuration objects are equal when their PIDs are equal.
+ *
* @param other {@code Configuration} object to compare against
* @return {@code true} if equal, {@code false} if not a
* {@code Configuration} object or one with a different PID.
*/
+ @Override
public boolean equals(Object other);
/**
* Hash code is based on PID.
- *
+ *
* The hash code for two Configuration objects must be the same when the
* Configuration PID's are the same.
- *
+ *
* @return hash code for this Configuration object
*/
+ @Override
public int hashCode();
}
diff --git a/bundles/org.eclipse.osgi.services/src/org/osgi/service/cm/ConfigurationAdmin.java b/bundles/org.eclipse.osgi.services/src/org/osgi/service/cm/ConfigurationAdmin.java
index caf295a2a..04d52783f 100644
--- a/bundles/org.eclipse.osgi.services/src/org/osgi/service/cm/ConfigurationAdmin.java
+++ b/bundles/org.eclipse.osgi.services/src/org/osgi/service/cm/ConfigurationAdmin.java
@@ -1,5 +1,5 @@
/*
- * Copyright (c) OSGi Alliance (2001, 2015). All Rights Reserved.
+ * Copyright (c) OSGi Alliance (2001, 2018). 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,42 +18,37 @@ package org.osgi.service.cm;
import java.io.IOException;
import java.util.Dictionary;
+
import org.osgi.annotation.versioning.ProviderType;
import org.osgi.framework.Filter;
import org.osgi.framework.InvalidSyntaxException;
/**
* Service for administering configuration data.
- *
* <p>
* The main purpose of this interface is to store bundle configuration data
* persistently. This information is represented in {@code Configuration}
* objects. The actual configuration data is a {@code Dictionary} of properties
* inside a {@code Configuration} object.
- *
* <p>
* There are two principally different ways to manage configurations. First
* there is the concept of a Managed Service, where configuration data is
* uniquely associated with an object registered with the service registry.
- *
* <p>
* Next, there is the concept of a factory where the Configuration Admin service
* will maintain 0 or more {@code Configuration} objects for a Managed Service
* Factory that is registered with the Framework.
- *
* <p>
* The first concept is intended for configuration data about "things/services"
* whose existence is defined externally, e.g. a specific printer. Factories are
* intended for "things/services" that can be created any number of times, e.g.
* a configuration for a DHCP server for different networks.
- *
* <p>
* Bundles that require configuration should register a Managed Service or a
* Managed Service Factory in the service registry. A registration property
* named {@code service.pid} (persistent identifier or PID) must be used to
* identify this Managed Service or Managed Service Factory to the Configuration
* Admin service.
- *
* <p>
* When the ConfigurationAdmin detects the registration of a Managed Service, it
* checks its persistent storage for a configuration object whose
@@ -62,7 +57,6 @@ import org.osgi.framework.InvalidSyntaxException;
* {@link ManagedService#updated(Dictionary)} method with the new properties.
* The implementation of a Configuration Admin service must run these call-backs
* asynchronously to allow proper synchronization.
- *
* <p>
* When the Configuration Admin service detects a Managed Service Factory
* registration, it checks its storage for configuration objects whose
@@ -72,14 +66,12 @@ import org.osgi.framework.InvalidSyntaxException;
* the new properties. The calls to the {@code updated} method of a
* {@code ManagedServiceFactory} must be executed sequentially and not overlap
* in time.
- *
* <p>
* In general, bundles having permission to use the Configuration Admin service
* can only access and modify their own configuration information. Accessing or
* modifying the configuration of other bundles requires
* {@code ConfigurationPermission[location,CONFIGURE]}, where location is the
* configuration location.
- *
* <p>
* {@code Configuration} objects can be <i>bound</i> to a specified bundle
* location or to a region (configuration location starts with {@code ?}). If a
@@ -88,11 +80,9 @@ import org.osgi.framework.InvalidSyntaxException;
* service must detect if the bundle corresponding to the location is
* uninstalled. If this occurs, the {@code Configuration} object must be
* unbound, that is its location field is set back to {@code null}.
- *
* <p>
* If target's bundle location matches the configuration location it is always
* updated.
- *
* <p>
* If the configuration location starts with {@code ?}, that is, the location is
* a region, then the configuration must be delivered to all targets registered
@@ -102,19 +92,17 @@ import org.osgi.framework.InvalidSyntaxException;
* security must be verified using the
* {@link org.osgi.framework.Bundle#hasPermission(Object)} method on the target
* bundle.
- *
* <p>
* If a target cannot be updated because the location does not match or it has
* no permission and security is active then the Configuration Admin service
* must not do the normal callback.
- *
* <p>
* The method descriptions of this class refer to a concept of "the calling
* bundle". This is a loose way of referring to the bundle which obtained the
* Configuration Admin service from the service registry. Implementations of
* {@code ConfigurationAdmin} must use a
* {@link org.osgi.framework.ServiceFactory} to support this concept.
- *
+ *
* @author $Id$
* @ThreadSafe
*/
@@ -123,7 +111,7 @@ public interface ConfigurationAdmin {
/**
* Configuration property naming the Factory PID in the configuration
* dictionary. The property's value is of type {@code String}.
- *
+ *
* @since 1.1
*/
public final static String SERVICE_FACTORYPID = "service.factoryPid";
@@ -132,29 +120,29 @@ public interface ConfigurationAdmin {
* associated with a {@code Configuration} object. This property can be
* searched for but must not appear in the configuration dictionary for
* security reason. The property's value is of type {@code String}.
- *
+ *
* @since 1.1
*/
public final static String SERVICE_BUNDLELOCATION = "service.bundleLocation";
/**
* Create a new factory {@code Configuration} object with a new PID.
- *
+ *
* The properties of the new {@code Configuration} object are {@code null}
* until the first time that its {@link Configuration#update(Dictionary)}
* method is called.
- *
+ *
* <p>
* It is not required that the {@code factoryPid} maps to a registered
* Managed Service Factory.
- *
+ *
* <p>
* The {@code Configuration} object is bound to the location of the calling
* bundle. It is possible that the same factoryPid has associated
* configurations that are bound to different bundles. Bundles should only
* see the factory configurations that they are bound to or have the proper
* permission.
- *
+ *
* @param factoryPid PID of factory (not {@code null}).
* @return A new {@code Configuration} object.
* @throws IOException if access to persistent storage fails.
@@ -163,15 +151,15 @@ public interface ConfigurationAdmin {
/**
* Create a new factory {@code Configuration} object with a new PID.
- *
+ *
* The properties of the new {@code Configuration} object are {@code null}
* until the first time that its {@link Configuration#update(Dictionary)}
* method is called.
- *
+ *
* <p>
* It is not required that the {@code factoryPid} maps to a registered
* Managed Service Factory.
- *
+ *
* <p>
* The {@code Configuration} is bound to the location specified. If this
* location is {@code null} it will be bound to the location of the first
@@ -179,11 +167,11 @@ public interface ConfigurationAdmin {
* It is possible that the same factoryPid has associated configurations
* that are bound to different bundles. Bundles should only see the factory
* configurations that they are bound to or have the proper permission.
- *
+ *
* <p>
* If the location starts with {@code ?} then the configuration must be
* delivered to all targets with the corresponding PID.
- *
+ *
* @param factoryPid PID of factory (not {@code null}).
* @param location A bundle location string, or {@code null}.
* @return a new {@code Configuration} object.
@@ -199,12 +187,12 @@ public interface ConfigurationAdmin {
/**
* Get an existing {@code Configuration} object from the persistent store,
* or create a new {@code Configuration} object.
- *
+ *
* <p>
* If a {@code Configuration} with this PID already exists in Configuration
* Admin service return it. The location parameter is ignored in this case
* though it is still used for a security check.
- *
+ *
* <p>
* Else, return a new {@code Configuration} object. This new object is bound
* to the location and the properties are set to {@code null}. If the
@@ -212,7 +200,7 @@ public interface ConfigurationAdmin {
* with the corresponding PID is registered for the first time. If the
* location starts with {@code ?} then the configuration is bound to all
* targets that are registered with the corresponding PID.
- *
+ *
* @param pid Persistent identifier.
* @param location The bundle location string, or {@code null}.
* @return An existing or new {@code Configuration} object.
@@ -232,15 +220,15 @@ public interface ConfigurationAdmin {
/**
* Get an existing or new {@code Configuration} object from the persistent
* store.
- *
+ *
* If the {@code Configuration} object for this PID does not exist, create a
* new {@code Configuration} object for that PID, where properties are
* {@code null}. Bind its location to the calling bundle's location.
- *
+ *
* <p>
* Otherwise, if the location of the existing {@code Configuration} object
* is {@code null}, set it to the calling bundle's location.
- *
+ *
* @param pid persistent identifier.
* @return an existing or new {@code Configuration} matching the PID.
* @throws IOException if access to persistent storage fails.
@@ -251,20 +239,82 @@ public interface ConfigurationAdmin {
*/
public Configuration getConfiguration(String pid) throws IOException;
+ /**
+ * Get an existing or new {@code Configuration} object from the persistent
+ * store. The PID for this {@code Configuration} object is generated from
+ * the provided factory PID and the name by starting with the factory PID
+ * appending a tilde ({@code '~'} &#92;u007E), and then appending the name.
+ * <p>
+ * If a {@code Configuration} with this PID already exists in Configuration
+ * Admin service return it. The location parameter is ignored in this case
+ * though it is still used for a security check.
+ * <p>
+ * Else, return a new {@code Configuration} object. This new object is bound
+ * to the location and the properties are set to {@code null}. If the
+ * location parameter is {@code null}, it will be set when a Managed Service
+ * with the corresponding PID is registered for the first time. If the
+ * location starts with {@code ?} then the configuration is bound to all
+ * targets that are registered with the corresponding PID.
+ *
+ * @param factoryPid PID of factory (not {@code null}).
+ * @param name A name for {@code Configuration} (not {@code null}).
+ * @param location The bundle location string, or {@code null}.
+ * @return An existing or new {@code Configuration} object.
+ * @throws IOException if access to persistent storage fails.
+ * @throws SecurityException when the require permissions are not available
+ * @security ConfigurationPermission[*,CONFIGURE] if location is
+ * {@code null} or if the returned configuration {@code c} already
+ * exists and c.location is {@code null}
+ * @security ConfigurationPermission[location,CONFIGURE] if location is not
+ * {@code null}
+ * @security ConfigurationPermission[c.location,CONFIGURE] if the returned
+ * configuration {@code c} already exists and c.location is not
+ * {@code null}
+ * @since 1.6
+ */
+ public Configuration getFactoryConfiguration(String factoryPid, String name,
+ String location) throws IOException;
+
+ /**
+ * Get an existing or new {@code Configuration} object from the persistent
+ * store. The PID for this {@code Configuration} object is generated from
+ * the provided factory PID and the name by starting with the factory PID
+ * appending a tilde ({@code '~'} &#92;u007E), and then appending the name.
+ * <p>
+ * If a {@code Configuration} object for this PID does not exist, create a
+ * new {@code Configuration} object for that PID, where properties are
+ * {@code null}. Bind its location to the calling bundle's location.
+ * <p>
+ * Otherwise, if the location of the existing {@code Configuration} object
+ * is {@code null}, set it to the calling bundle's location.
+ *
+ * @param factoryPid PID of factory (not {@code null}).
+ * @param name A name for {@code Configuration} (not {@code null}).
+ * @return an existing or new {@code Configuration} matching the PID.
+ * @throws IOException if access to persistent storage fails.
+ * @throws SecurityException when the required permission is not available
+ * @security ConfigurationPermission[c.location,CONFIGURE] If the
+ * configuration {@code c} already exists and c.location is not
+ * {@code null}
+ * @since 1.6
+ */
+ public Configuration getFactoryConfiguration(String factoryPid, String name)
+ throws IOException;
+
/**
* List the current {@code Configuration} objects which match the filter.
- *
+ *
* <p>
* Only {@code Configuration} objects with non- {@code null} properties are
* considered current. That is, {@code Configuration.getProperties()} is
* guaranteed not to return {@code null} for each of the returned
* {@code Configuration} objects.
- *
+ *
* <p>
* When there is no security on then all configurations can be returned. If
* security is on, the caller must have
* ConfigurationPermission[location,CONFIGURE].
- *
+ *
* <p>
* The syntax of the filter string is as defined in the {@link Filter}
* class. The filter can test any configuration properties including the
@@ -276,7 +326,7 @@ public interface ConfigurationAdmin {
* </ul>
* The filter can also be {@code null}, meaning that all
* {@code Configuration} objects should be returned.
- *
+ *
* @param filter A filter string, or {@code null} to retrieve all
* {@code Configuration} objects.
* @return All matching {@code Configuration} objects, or {@code null} if
diff --git a/bundles/org.eclipse.osgi.services/src/org/osgi/service/cm/ConfigurationConstants.java b/bundles/org.eclipse.osgi.services/src/org/osgi/service/cm/ConfigurationConstants.java
new file mode 100644
index 000000000..3e96b9e44
--- /dev/null
+++ b/bundles/org.eclipse.osgi.services/src/org/osgi/service/cm/ConfigurationConstants.java
@@ -0,0 +1,46 @@
+/*
+ * Copyright (c) OSGi Alliance (2017). 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.cm;
+
+
+/**
+ * Defines standard constants for the Configuration Admin service.
+ *
+ * @author $Id$
+ */
+public final class ConfigurationConstants {
+ private ConfigurationConstants() {
+ // non-instantiable
+ }
+
+
+ /**
+ * The name of the implementation capability for the Configuration Admin
+ * specification
+ *
+ * @since 1.6
+ */
+ public static final String CONFIGURATION_ADMIN_IMPLEMENTATION = "osgi.cm";
+
+ /**
+ * The version of the implementation capability for the Configuration Admin
+ * specification
+ *
+ * @since 1.6
+ */
+ public static final String CONFIGURATION_ADMIN_SPECIFICATION_VERSION = "1.6.0";
+}
diff --git a/bundles/org.eclipse.osgi.services/src/org/osgi/service/cm/ConfigurationEvent.java b/bundles/org.eclipse.osgi.services/src/org/osgi/service/cm/ConfigurationEvent.java
index d0c13bb6c..8b32e6323 100644
--- a/bundles/org.eclipse.osgi.services/src/org/osgi/service/cm/ConfigurationEvent.java
+++ b/bundles/org.eclipse.osgi.services/src/org/osgi/service/cm/ConfigurationEvent.java
@@ -1,6 +1,6 @@
/*
- * Copyright (c) OSGi Alliance (2004, 2013). All Rights Reserved.
- *
+ * Copyright (c) OSGi Alliance (2004, 2017). 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
@@ -17,16 +17,15 @@
package org.osgi.service.cm;
import java.util.Dictionary;
+
import org.osgi.framework.ServiceReference;
/**
* A Configuration Event.
- *
* <p>
* {@code ConfigurationEvent} objects are delivered to all registered
* {@code ConfigurationListener} service objects. ConfigurationEvents must be
* delivered in chronological order with respect to each listener.
- *
* <p>
* A type code is used to identify the type of event. The following event types
* are defined:
@@ -36,14 +35,13 @@ import org.osgi.framework.ServiceReference;
* <li>{@link #CM_LOCATION_CHANGED}</li>
* </ul>
* Additional event types may be defined in the future.
- *
* <p>
* Security Considerations. {@code ConfigurationEvent} objects do not provide
* {@code Configuration} objects, so no sensitive configuration information is
* available from the event. If the listener wants to locate the
* {@code Configuration} object for the specified pid, it must use
* {@code ConfigurationAdmin}.
- *
+ *
* @see ConfigurationListener
* @Immutable
* @author $Id$
@@ -52,22 +50,22 @@ import org.osgi.framework.ServiceReference;
public class ConfigurationEvent {
/**
* A {@code Configuration} has been updated.
- *
+ *
* <p>
* This {@code ConfigurationEvent} type that indicates that a
* {@code Configuration} object has been updated with new properties.
- *
+ *
* An event is fired when a call to {@link Configuration#update(Dictionary)}
* successfully changes a configuration.
*/
public static final int CM_UPDATED = 1;
/**
* A {@code Configuration} has been deleted.
- *
+ *
* <p>
* This {@code ConfigurationEvent} type that indicates that a
* {@code Configuration} object has been deleted.
- *
+ *
* An event is fired when a call to {@link Configuration#delete()}
* successfully deletes a configuration.
*/
@@ -75,21 +73,21 @@ public class ConfigurationEvent {
/**
* The location of a {@code Configuration} has been changed.
- *
+ *
* <p>
* This {@code ConfigurationEvent} type that indicates that the location of
* a {@code Configuration} object has been changed.
- *
+ *
* An event is fired when a call to
* {@link Configuration#setBundleLocation(String)} successfully changes the
* location.
- *
+ *
* @since 1.4
*/
public static final int CM_LOCATION_CHANGED = 3;
/**
* Type of this event.
- *
+ *
* @see #getType()
*/
private final int type;
@@ -109,7 +107,7 @@ public class ConfigurationEvent {
/**
* Constructs a {@code ConfigurationEvent} object from the given
* {@code ServiceReference} object, event type, and pids.
- *
+ *
* @param reference The {@code ServiceReference} object of the Configuration
* Admin service that created this event.
* @param type The event type. See {@link #getType()}.
@@ -131,7 +129,7 @@ public class ConfigurationEvent {
/**
* Returns the factory pid of the associated configuration.
- *
+ *
* @return Returns the factory pid of the associated configuration if the
* target of the configuration is a ManagedServiceFactory. Otherwise
* {@code null} if the target of the configuration is a
@@ -143,7 +141,7 @@ public class ConfigurationEvent {
/**
* Returns the pid of the associated configuration.
- *
+ *
* @return Returns the pid of the associated configuration.
*/
public String getPid() {
@@ -159,7 +157,7 @@ public class ConfigurationEvent {
* <li>{@link #CM_DELETED}</li>
* <li>{@link #CM_LOCATION_CHANGED}</li>
* </ul>
- *
+ *
* @return The type of this event.
*/
public int getType() {
@@ -169,7 +167,7 @@ public class ConfigurationEvent {
/**
* Return the {@code ServiceReference} object of the Configuration Admin
* service that created this event.
- *
+ *
* @return The {@code ServiceReference} object for the Configuration Admin
* service that created this event.
*/
diff --git a/bundles/org.eclipse.osgi.services/src/org/osgi/service/cm/ConfigurationException.java b/bundles/org.eclipse.osgi.services/src/org/osgi/service/cm/ConfigurationException.java
index d4646fc2a..c3045e569 100644
--- a/bundles/org.eclipse.osgi.services/src/org/osgi/service/cm/ConfigurationException.java
+++ b/bundles/org.eclipse.osgi.services/src/org/osgi/service/cm/ConfigurationException.java
@@ -1,5 +1,5 @@
/*
- * Copyright (c) OSGi Alliance (2001, 2013). All Rights Reserved.
+ * Copyright (c) OSGi Alliance (2001, 2017). 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.
@@ -19,18 +19,18 @@ package org.osgi.service.cm;
/**
* An {@code Exception} class to inform the Configuration Admin service of
* problems with configuration data.
- *
+ *
* @author $Id$
*/
public class ConfigurationException extends Exception {
- static final long serialVersionUID = -1690090413441769377L;
+ private static final long serialVersionUID = -1690090413441769377L;
private final String property;
private final String reason;
/**
* Create a {@code ConfigurationException} object.
- *
+ *
* @param property name of the property that caused the problem,
* {@code null} if no specific property was the cause
* @param reason reason for failure
@@ -43,7 +43,7 @@ public class ConfigurationException extends Exception {
/**
* Create a {@code ConfigurationException} object.
- *
+ *
* @param property name of the property that caused the problem,
* {@code null} if no specific property was the cause
* @param reason reason for failure
@@ -58,7 +58,7 @@ public class ConfigurationException extends Exception {
/**
* Return the property name that caused the failure or null.
- *
+ *
* @return name of property or null if no specific property caused the
* problem
*/
@@ -68,7 +68,7 @@ public class ConfigurationException extends Exception {
/**
* Return the reason for this exception.
- *
+ *
* @return reason of the failure
*/
public String getReason() {
@@ -77,7 +77,7 @@ public class ConfigurationException extends Exception {
/**
* Returns the cause of this exception or {@code null} if no cause was set.
- *
+ *
* @return The cause of this exception or {@code null} if no cause was set.
* @since 1.2
*/
@@ -88,7 +88,7 @@ public class ConfigurationException extends Exception {
/**
* 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
diff --git a/bundles/org.eclipse.osgi.services/src/org/osgi/service/cm/ConfigurationListener.java b/bundles/org.eclipse.osgi.services/src/org/osgi/service/cm/ConfigurationListener.java
index ee8427b3d..172985388 100644
--- a/bundles/org.eclipse.osgi.services/src/org/osgi/service/cm/ConfigurationListener.java
+++ b/bundles/org.eclipse.osgi.services/src/org/osgi/service/cm/ConfigurationListener.java
@@ -1,6 +1,6 @@
/*
- * Copyright (c) OSGi Alliance (2004, 2013). All Rights Reserved.
- *
+ * Copyright (c) OSGi Alliance (2004, 2017). 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
@@ -21,7 +21,6 @@ import org.osgi.annotation.versioning.ConsumerType;
/**
* Listener for Configuration Events. When a {@code ConfigurationEvent} is
* fired, it is asynchronously delivered to all {@code ConfigurationListener}s.
- *
* <p>
* {@code ConfigurationListener} objects are registered with the Framework
* service registry and are notified with a {@code ConfigurationEvent} object
@@ -31,12 +30,11 @@ import org.osgi.annotation.versioning.ConsumerType;
* {@code ConfigurationEvent} object to determine its type, the pid of the
* {@code Configuration} object with which it is associated, and the
* Configuration Admin service that fired the event.
- *
* <p>
* Security Considerations. Bundles wishing to monitor configuration events will
* require {@code ServicePermission[ConfigurationListener,REGISTER]} to register
* a {@code ConfigurationListener} service.
- *
+ *
* @author $Id$
* @since 1.2
* @ThreadSafe
@@ -45,7 +43,7 @@ import org.osgi.annotation.versioning.ConsumerType;
public interface ConfigurationListener {
/**
* Receives notification of a Configuration that has changed.
- *
+ *
* @param event The {@code ConfigurationEvent}.
*/
public void configurationEvent(ConfigurationEvent event);
diff --git a/bundles/org.eclipse.osgi.services/src/org/osgi/service/cm/ConfigurationPermission.java b/bundles/org.eclipse.osgi.services/src/org/osgi/service/cm/ConfigurationPermission.java
index ea3f7764e..949278d47 100644
--- a/bundles/org.eclipse.osgi.services/src/org/osgi/service/cm/ConfigurationPermission.java
+++ b/bundles/org.eclipse.osgi.services/src/org/osgi/service/cm/ConfigurationPermission.java
@@ -1,6 +1,6 @@
/*
- * Copyright (c) OSGi Alliance (2004, 2013). All Rights Reserved.
- *
+ * Copyright (c) OSGi Alliance (2004, 2017). 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
@@ -30,6 +30,7 @@ import java.util.Enumeration;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
+
import org.osgi.framework.Filter;
/**
@@ -42,7 +43,7 @@ import org.osgi.framework.Filter;
*/
public final class ConfigurationPermission extends BasicPermission {
- static final long serialVersionUID = 5716868734811965383L;
+ private static final long serialVersionUID = 5716868734811965383L;
/**
* Provides permission to create new configurations for other bundles as
* well as manipulate them. The action string {@value #CONFIGURE}.
@@ -52,14 +53,23 @@ public final class ConfigurationPermission extends BasicPermission {
/**
* The permission to be updated, that is, act as a Managed Service or
* Managed Service Factory. The action string {@value #TARGET}.
- *
+ *
* @since 1.4
*/
public final static String TARGET = "target";
- private final static int ACTION_CONFIGURE = 0x00000001;
+ /**
+ * Provides permission to set or remove an attribute on the configuration.
+ * The action string {@value #ATTRIBUTE}.
+ *
+ * @since 1.6
+ */
+ public final static String ATTRIBUTE = "attribute";
+
+ private final static int ACTION_CONFIGURE = 0x00000001;
private final static int ACTION_TARGET = 0x00000002;
- private final static int ACTION_ALL = ACTION_CONFIGURE | ACTION_TARGET;
+ private final static int ACTION_ATTRIBUTE = 0x00000004;
+ private final static int ACTION_ALL = ACTION_CONFIGURE | ACTION_TARGET | ACTION_ATTRIBUTE;
final static int ACTION_NONE = 0;
/**
@@ -69,7 +79,7 @@ public final class ConfigurationPermission extends BasicPermission {
/**
* The actions in canonical form.
- *
+ *
* @serial
*/
private volatile String actions = null;
@@ -81,13 +91,13 @@ public final class ConfigurationPermission extends BasicPermission {
/**
* Create a new ConfigurationPermission.
- *
+ *
* @param name Name of the permission. Wildcards ({@code '*'}) are allowed
- * in the name. During {@link #implies(Permission)}, the name is
- * matched to the requested permission using the substring matching
- * rules used by {@link Filter}s.
+ * in the name. During {@link #implies(Permission)}, the name is
+ * matched to the requested permission using the substring
+ * matching rules used by {@link Filter}s.
* @param actions Comma separated list of {@link #CONFIGURE},
- * {@link #TARGET} (case insensitive).
+ * {@link #TARGET}, {@link #ATTRIBUTE} (case insensitive).
*/
public ConfigurationPermission(String name, String actions) {
@@ -96,7 +106,7 @@ public final class ConfigurationPermission extends BasicPermission {
/**
* Package private constructor used by ConfigurationPermissionCollection.
- *
+ *
* @param name location string
* @param mask action mask
*/
@@ -107,7 +117,7 @@ public final class ConfigurationPermission extends BasicPermission {
/**
* Called by constructors and when deserialized.
- *
+ *
* @param mask action mask
*/
private void setTransients(int mask) {
@@ -120,7 +130,7 @@ public final class ConfigurationPermission extends BasicPermission {
/**
* Parse action string into action mask.
- *
+ *
* @param actions Action string.
* @return action mask.
*/
@@ -171,10 +181,23 @@ public final class ConfigurationPermission extends BasicPermission {
matchlen = 9;
mask |= ACTION_CONFIGURE;
- } else {
- // parse error
- throw new IllegalArgumentException("invalid actions: " + actions);
- }
+ } else
+ if (i >= 8 && (a[i - 8] == 'a' || a[i - 8] == 'A')
+ && (a[i - 7] == 't' || a[i - 7] == 'T')
+ && (a[i - 6] == 't' || a[i - 6] == 'T')
+ && (a[i - 5] == 'r' || a[i - 5] == 'R')
+ && (a[i - 4] == 'i' || a[i - 4] == 'I')
+ && (a[i - 3] == 'b' || a[i - 3] == 'B')
+ && (a[i - 2] == 'u' || a[i - 2] == 'U')
+ && (a[i - 1] == 't' || a[i - 1] == 'T')
+ && (a[i] == 'e' || a[i] == 'E')) {
+ matchlen = 9;
+ mask |= ACTION_ATTRIBUTE;
+ } else {
+ // parse error
+ throw new IllegalArgumentException("invalid actions: " + actions);
+ }
+
// make sure we didn't just match the tail of a word
// like "ackbarftarget". Also, skip to the comma.
@@ -209,7 +232,7 @@ public final class ConfigurationPermission extends BasicPermission {
/**
* Parse the name for wildcard processing.
- *
+ *
* @param name The name of the permission.
* @return {@code null} is the name has no wildcards or a
* {@code List<String>} where element is a substring to match or
@@ -220,7 +243,7 @@ public final class ConfigurationPermission extends BasicPermission {
return null;
}
char[] chars = name.toCharArray();
- StringBuffer sb = new StringBuffer(chars.length);
+ StringBuilder sb = new StringBuilder(chars.length);
List<String> sub = new ArrayList<String>(10);
@@ -272,7 +295,7 @@ public final class ConfigurationPermission extends BasicPermission {
/**
* Determines if a {@code ConfigurationPermission} object "implies" the
* specified permission.
- *
+ *
* @param p The target permission to check.
* @return {@code true} if the specified permission is implied by this
* object; {@code false} otherwise.
@@ -290,7 +313,7 @@ public final class ConfigurationPermission extends BasicPermission {
/**
* Internal implies method. Used by the implies and the permission
* collection implies methods.
- *
+ *
* @param requested The requested ConfigurationPermission which has already
* be validated as a proper argument.
* @param effective The effective actions with which to start.
@@ -355,7 +378,7 @@ public final class ConfigurationPermission extends BasicPermission {
* Determines the equality of two {@code ConfigurationPermission} objects.
* <p>
* Two {@code ConfigurationPermission} objects are equal.
- *
+ *
* @param obj The object being compared for equality with this object.
* @return {@code true} if {@code obj} is equivalent to this
* {@code ConfigurationPermission}; {@code false} otherwise.
@@ -377,7 +400,7 @@ public final class ConfigurationPermission extends BasicPermission {
/**
* Returns the hash code value for this object.
- *
+ *
* @return Hash code value for this object.
*/
@@ -391,11 +414,11 @@ public final class ConfigurationPermission extends BasicPermission {
/**
* Returns the canonical string representation of the
* {@code ConfigurationPermission} actions.
- *
* <p>
* Always returns present {@code ConfigurationPermission} actions in the
- * following order: {@value #CONFIGURE}, {@value #TARGET}
- *
+ * following order: {@value #CONFIGURE}, {@value #TARGET},
+ * {@value #ATTRIBUTE}.
+ *
* @return Canonical string representation of the
* {@code ConfigurationPermission} actions.
*/
@@ -403,7 +426,7 @@ public final class ConfigurationPermission extends BasicPermission {
public String getActions() {
String result = actions;
if (result == null) {
- StringBuffer sb = new StringBuffer();
+ StringBuilder sb = new StringBuilder();
boolean comma = false;
int mask = action_mask;
@@ -416,6 +439,13 @@ public final class ConfigurationPermission extends BasicPermission {
if (comma)
sb.append(',');
sb.append(TARGET);
+ comma = true;
+ }
+
+ if ((mask & ACTION_ATTRIBUTE) == ACTION_ATTRIBUTE) {
+ if (comma)
+ sb.append(',');
+ sb.append(ATTRIBUTE);
}
actions = result = sb.toString();
@@ -427,7 +457,7 @@ public final class ConfigurationPermission extends BasicPermission {
/**
* Returns a new {@code PermissionCollection} object suitable for storing
* {@code ConfigurationPermission}s.
- *
+ *
* @return A new {@code PermissionCollection} object.
*/
@Override
@@ -461,7 +491,7 @@ public final class ConfigurationPermission extends BasicPermission {
/**
* Stores a set of {@code ConfigurationPermission} permissions.
- *
+ *
* @see java.security.Permission
* @see java.security.Permissions
* @see java.security.PermissionCollection
@@ -470,7 +500,7 @@ final class ConfigurationPermissionCollection extends PermissionCollection {
static final long serialVersionUID = -6917638867081695839L;
/**
* Collection of permissions.
- *
+ *
* @serial
* @GuardedBy this
*/
@@ -478,7 +508,7 @@ final class ConfigurationPermissionCollection extends PermissionCollection {
/**
* Boolean saying if "*" is in the collection.
- *
+ *
* @serial
* @GuardedBy this
*/
@@ -486,7 +516,7 @@ final class ConfigurationPermissionCollection extends PermissionCollection {
/**
* Creates an empty {@code ConfigurationPermissionCollection} object.
- *
+ *
*/
public ConfigurationPermissionCollection() {
permissions = new HashMap<String, ConfigurationPermission>();
@@ -497,12 +527,12 @@ final class ConfigurationPermissionCollection extends PermissionCollection {
* Adds the specified permission to the
* {@code ConfigurationPermissionCollection}. The key for the hash is the
* interface name of the service.
- *
+ *
* @param permission The {@code Permission} object to add.
- *
+ *
* @exception IllegalArgumentException If the permission is not an
* {@code ConfigurationPermission}.
- *
+ *
* @exception SecurityException If this ConfigurationPermissionCollection
* object has been marked read-only.
*/
@@ -542,7 +572,7 @@ final class ConfigurationPermissionCollection extends PermissionCollection {
/**
* Determines if the specified permissions implies the permissions expressed
* in {@code permission}.
- *
+ *
* @param permission The Permission object to compare with this
* {@code ConfigurationPermission} object.
* @return {@code true} if {@code permission} is a proper subset of a
@@ -584,7 +614,7 @@ final class ConfigurationPermissionCollection extends PermissionCollection {
/**
* Returns an enumeration of all {@code ConfigurationPermission} objects in
* the container.
- *
+ *
* @return Enumeration of all {@code ConfigurationPermission} objects.
*/
@Override
diff --git a/bundles/org.eclipse.osgi.services/src/org/osgi/service/cm/ConfigurationPlugin.java b/bundles/org.eclipse.osgi.services/src/org/osgi/service/cm/ConfigurationPlugin.java
index a3c11ec22..f89d83b72 100644
--- a/bundles/org.eclipse.osgi.services/src/org/osgi/service/cm/ConfigurationPlugin.java
+++ b/bundles/org.eclipse.osgi.services/src/org/osgi/service/cm/ConfigurationPlugin.java
@@ -1,5 +1,5 @@
/*
- * Copyright (c) OSGi Alliance (2001, 2013). All Rights Reserved.
+ * Copyright (c) OSGi Alliance (2001, 2017). 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.
@@ -17,13 +17,13 @@
package org.osgi.service.cm;
import java.util.Dictionary;
+
import org.osgi.annotation.versioning.ConsumerType;
import org.osgi.framework.ServiceReference;
/**
* A service interface for processing configuration dictionary before the
* update.
- *
* <p>
* A bundle registers a {@code ConfigurationPlugin} object in order to process
* configuration updates before they reach the Managed Service or Managed
@@ -33,11 +33,9 @@ import org.osgi.framework.ServiceReference;
* {@code updated} method. The Configuration Plugin service thus has the
* opportunity to view and modify the properties before they are passed to the
* Managed Service or Managed Service Factory.
- *
* <p>
* Configuration Plugin (plugin) services have full read/write access to all
* configuration information that passes through them.
- *
* <p>
* The {@code Integer} {@code service.cmRanking} registration property may be
* specified. Not specifying this registration property, or setting it to
@@ -47,18 +45,15 @@ import org.osgi.framework.ServiceReference;
* higher ranked ones. In the event of more than one plugin having the same
* value of {@code service.cmRanking}, then the Configuration Admin service
* arbitrarily chooses the order in which they are called.
- *
* <p>
* By convention, plugins with {@code service.cmRanking < 0} or
* {@code service.cmRanking > 1000} should not make modifications to the
* properties.
- *
* <p>
* The Configuration Admin service has the right to hide properties from
* plugins, or to ignore some or all the changes that they make. This might be
* done for security reasons. Any such behavior is entirely implementation
* defined.
- *
* <p>
* A plugin may optionally specify a {@code cm.target} registration property
* whose value is the PID of the Managed Service or Managed Service Factory
@@ -67,7 +62,7 @@ import org.osgi.framework.ServiceReference;
* Managed Service or Managed Service Factory with the specified PID. Omitting
* the {@code cm.target} registration property means that the plugin is called
* for all configuration updates.
- *
+ *
* @author $Id$
* @ThreadSafe
*/
@@ -77,7 +72,7 @@ public interface ConfigurationPlugin {
* A service property to limit the Managed Service or Managed Service
* Factory configuration dictionaries a Configuration Plugin service
* receives.
- *
+ *
* This property contains a {@code String[]} of PIDs. A Configuration Admin
* service must call a Configuration Plugin service only when this property
* is not set, or the target service's PID is listed in this property.
@@ -85,13 +80,13 @@ public interface ConfigurationPlugin {
public static final String CM_TARGET = "cm.target";
/**
* A service property to specify the order in which plugins are invoked.
- *
+ *
* This property contains an {@code Integer} ranking of the plugin. Not
* specifying this registration property, or setting it to something other
* than an {@code Integer}, is the same as setting it to the {@code Integer}
* zero. This property determines the order in which plugins are invoked.
* Lower ranked plugins are called before higher ranked ones.
- *
+ *
* @since 1.2
*/
public static final String CM_RANKING = "service.cmRanking";
@@ -102,21 +97,23 @@ public interface ConfigurationPlugin {
* Configuration Plugin services are called in increasing order of their
* {@code service.cmRanking} property. If this property is undefined or is a
* non- {@code Integer} type, 0 is used.
- *
+ *
* <p>
* This method should not modify the properties unless the
* {@code service.cmRanking} of this plugin is in the range
- * {@code 0 <= service.cmRanking <= 1000}.
+ * {@code 0 <= service.cmRanking <= 1000}. Any modification
+ * from this plugin is ignored.
* <p>
* If this method throws any {@code Exception}, the Configuration Admin
- * service must catch it and should log it.
- *
+ * service must catch it and should log it. Any modifications made by the
+ * plugin before the exception is thrown are applied.
+ *
* <p>
* A Configuration Plugin will only be called for properties from
* configurations that have a location for which the Configuration Plugin
* has permission when security is active. When security is not active, no
* filtering is done.
- *
+ *
* @param reference reference to the Managed Service or Managed Service
* Factory
* @param properties The configuration properties. This argument must not
diff --git a/bundles/org.eclipse.osgi.services/src/org/osgi/service/cm/ManagedService.java b/bundles/org.eclipse.osgi.services/src/org/osgi/service/cm/ManagedService.java
index b85f71d92..9775796b5 100644
--- a/bundles/org.eclipse.osgi.services/src/org/osgi/service/cm/ManagedService.java
+++ b/bundles/org.eclipse.osgi.services/src/org/osgi/service/cm/ManagedService.java
@@ -1,5 +1,5 @@
/*
- * Copyright (c) OSGi Alliance (2001, 2015). All Rights Reserved.
+ * Copyright (c) OSGi Alliance (2001, 2017). 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.
@@ -17,30 +17,27 @@
package org.osgi.service.cm;
import java.util.Dictionary;
+
import org.osgi.annotation.versioning.ConsumerType;
/**
* A service that can receive configuration data from a Configuration Admin
* service.
- *
* <p>
* A Managed Service is a service that needs configuration data. Such an object
* should be registered with the Framework registry with the {@code service.pid}
* property set to some unique identifier called a PID.
- *
* <p>
* If the Configuration Admin service has a {@code Configuration} object
* corresponding to this PID, it will callback the {@code updated()} method of
* the {@code ManagedService} object, passing the properties of that
* {@code Configuration} object.
- *
* <p>
* If it has no such {@code Configuration} object, then it calls back with a
* {@code null} properties argument. Registering a Managed Service will always
* result in a callback to the {@code updated()} method provided the
* Configuration Admin service is, or becomes active. This callback must always
* be done asynchronously.
- *
* <p>
* Else, every time that either of the {@code updated()} methods is called on
* that {@code Configuration} object, the {@code ManagedService.updated()}
@@ -48,19 +45,18 @@ import org.osgi.annotation.versioning.ConsumerType;
* called on that {@code Configuration} object, {@code ManagedService.updated()}
* is called with a {@code null} for the properties parameter. All these
* callbacks must be done asynchronously.
- *
* <p>
* The following example shows the code of a serial port that will create a port
* depending on configuration information.
- *
+ *
* <pre>
- *
+ *
* class SerialPort implements ManagedService {
- *
+ *
* ServiceRegistration registration;
* Hashtable configuration;
* CommPortIdentifier id;
- *
+ *
* synchronized void open(CommPortIdentifier id,
* BundleContext context) {
* this.id = id;
@@ -70,7 +66,7 @@ import org.osgi.annotation.versioning.ConsumerType;
* getDefaults()
* );
* }
- *
+ *
* Hashtable getDefaults() {
* Hashtable defaults = new Hashtable();
* defaults.put( &quot;port&quot;, id.getName() );
@@ -80,7 +76,7 @@ import org.osgi.annotation.versioning.ConsumerType;
* &quot;com.acme.serialport.&quot; + id.getName() );
* return defaults;
* }
- *
+ *
* public synchronized void updated(
* Dictionary configuration ) {
* if ( configuration == null )
@@ -92,21 +88,21 @@ import org.osgi.annotation.versioning.ConsumerType;
* }
* ...
* }
- *
* </pre>
- *
* <p>
* As a convention, it is recommended that when a Managed Service is updated, it
* should copy all the properties it does not recognize into the service
* registration properties. This will allow the Configuration Admin service to
* set properties on services which can then be used by other applications.
- *
* <p>
* Normally, a single Managed Service for a given PID is given the configuration
* dictionary, this is the configuration that is bound to the location of the
* registering bundle. However, when security is on, a Managed Service can have
* Configuration Permission to also be updated for other locations.
- *
+ * <p>
+ * If a Managed Service is registered without the {@code service.pid} property,
+ * it will be ignored.
+ *
* @author $Id$
* @ThreadSafe
*/
@@ -114,14 +110,14 @@ import org.osgi.annotation.versioning.ConsumerType;
public interface ManagedService {
/**
* Update the configuration for a Managed Service.
- *
+ *
* <p>
* When the implementation of {@code updated(Dictionary)} detects any kind
* of error in the configuration properties, it should create a new
* {@code ConfigurationException} which describes the problem. This can
* allow a management system to provide useful information to a human
* administrator.
- *
+ *
* <p>
* If this method throws any other {@code Exception}, the Configuration
* Admin service must catch it and should log it.
@@ -131,19 +127,19 @@ public interface ManagedService {
* Managed Service can be assured that the callback will not take place
* during registration when they execute the registration in a synchronized
* method.
- *
+ *
* <p>
* If the location allows multiple managed services to be called back for a
* single configuration then the callbacks must occur in service ranking
* order. Changes in the location must be reflected by deleting the
* configuration if the configuration is no longer visible and updating when
* it becomes visible.
- *
+ *
* <p>
* If no configuration exists for the corresponding PID, or the bundle has
* no access to the configuration, then the bundle must be called back with
* a {@code null} to signal that CM is active but there is no data.
- *
+ *
* @param properties A copy of the Configuration properties, or {@code null}
* . This argument must not contain the "service.bundleLocation"
* property. The value of this property may be obtained from the
diff --git a/bundles/org.eclipse.osgi.services/src/org/osgi/service/cm/ManagedServiceFactory.java b/bundles/org.eclipse.osgi.services/src/org/osgi/service/cm/ManagedServiceFactory.java
index 97807d23b..1c34a86e1 100644
--- a/bundles/org.eclipse.osgi.services/src/org/osgi/service/cm/ManagedServiceFactory.java
+++ b/bundles/org.eclipse.osgi.services/src/org/osgi/service/cm/ManagedServiceFactory.java
@@ -1,5 +1,5 @@
/*
- * Copyright (c) OSGi Alliance (2001, 2013). All Rights Reserved.
+ * Copyright (c) OSGi Alliance (2001, 2017). 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.
@@ -17,17 +17,15 @@
package org.osgi.service.cm;
import java.util.Dictionary;
+
import org.osgi.annotation.versioning.ConsumerType;
/**
- * Manage multiple service instances.
- *
- * Bundles registering this interface are giving the Configuration Admin service
- * the ability to create and configure a number of instances of a service that
- * the implementing bundle can provide. For example, a bundle implementing a
- * DHCP server could be instantiated multiple times for different interfaces
- * using a factory.
- *
+ * Manage multiple service instances. Bundles registering this interface are
+ * giving the Configuration Admin service the ability to create and configure a
+ * number of instances of a service that the implementing bundle can provide.
+ * For example, a bundle implementing a DHCP server could be instantiated
+ * multiple times for different interfaces using a factory.
* <p>
* Each of these <i>service instances </i> is represented, in the persistent
* storage of the Configuration Admin service, by a factory
@@ -38,7 +36,6 @@ import org.osgi.annotation.versioning.ConsumerType;
* create a new factory instance based on these configuration properties. When
* called with a PID that it has seen before, it should update that existing
* service instance with the new configuration information.
- *
* <p>
* In general it is expected that the implementation of this interface will
* maintain a data structure that maps PIDs to the factory instances that it has
@@ -47,13 +44,12 @@ import org.osgi.annotation.versioning.ConsumerType;
* object with the service registry, its PID should match the PID of the
* corresponding {@code Configuration} object (but it should <b>not </b> be
* registered as a Managed Service!).
- *
* <p>
* An example that demonstrates the use of a factory. It will create serial
* ports under command of the Configuration Admin service.
- *
+ *
* <pre>
- *
+ *
* class SerialPortFactory
* implements ManagedServiceFactory {
* ServiceRegistration registration;
@@ -90,9 +86,11 @@ import org.osgi.annotation.versioning.ConsumerType;
* }
* ...
* }
- *
* </pre>
- *
+ * <p>
+ * If a {@code ManagedServiceFactory} is registered without the {@code service.pid}
+ * property, it will be ignored.
+ *
* @author $Id$
* @ThreadSafe
*/
@@ -100,7 +98,7 @@ import org.osgi.annotation.versioning.ConsumerType;
public interface ManagedServiceFactory {
/**
* Return a descriptive name of this factory.
- *
+ *
* @return the name for the factory, which might be localized
*/
public String getName();
@@ -108,38 +106,38 @@ public interface ManagedServiceFactory {
/**
* Create a new instance, or update the configuration of an existing
* instance.
- *
+ *
* If the PID of the {@code Configuration} object is new for the Managed
* Service Factory, then create a new factory instance, using the
* configuration {@code properties} provided. Else, update the service
* instance with the provided {@code properties}.
- *
+ *
* <p>
* If the factory instance is registered with the Framework, then the
* configuration {@code properties} should be copied to its registry
* properties. This is not mandatory and security sensitive properties
* should obviously not be copied.
- *
+ *
* <p>
* If this method throws any {@code Exception}, the Configuration Admin
* service must catch it and should log it.
- *
+ *
* <p>
* When the implementation of updated detects any kind of error in the
* configuration properties, it should create a new
* {@link ConfigurationException} which describes the problem.
- *
+ *
* <p>
* The Configuration Admin service must call this method asynchronously.
* This implies that implementors of the {@code ManagedServiceFactory} class
* can be assured that the callback will not take place during registration
* when they execute the registration in a synchronized method.
- *
+ *
* <p>
* If the security allows multiple managed service factories to be called
* back for a single configuration then the callbacks must occur in service
* ranking order.
- *
+ *
* <p>
* It is valid to create multiple factory instances that are bound to
* different locations. Managed Service Factory services must only be
@@ -148,7 +146,7 @@ public interface ManagedServiceFactory {
* Changes in the location must be reflected by deleting the corresponding
* configuration if the configuration is no longer visible or updating when
* it becomes visible.
- *
+ *
* @param pid The PID for this configuration.
* @param properties A copy of the configuration properties. This argument
* must not contain the service.bundleLocation" property. The value
@@ -163,18 +161,18 @@ public interface ManagedServiceFactory {
/**
* Remove a factory instance.
- *
+ *
* Remove the factory instance associated with the PID. If the instance was
* registered with the service registry, it should be unregistered. The
* Configuration Admin must call deleted for each instance it received in
* {@link #updated(String, Dictionary)}.
- *
+ *
* <p>
* If this method throws any {@code Exception}, the Configuration Admin
* service must catch it and should log it.
* <p>
* The Configuration Admin service must call this method asynchronously.
- *
+ *
* @param pid the PID of the service to be removed
*/
public void deleted(String pid);
diff --git a/bundles/org.eclipse.osgi.services/src/org/osgi/service/cm/ReadOnlyConfigurationException.java b/bundles/org.eclipse.osgi.services/src/org/osgi/service/cm/ReadOnlyConfigurationException.java
new file mode 100644
index 000000000..1574cef6d
--- /dev/null
+++ b/bundles/org.eclipse.osgi.services/src/org/osgi/service/cm/ReadOnlyConfigurationException.java
@@ -0,0 +1,40 @@
+/*
+ * Copyright (c) OSGi Alliance (2016, 2017). 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.cm;
+
+import org.osgi.service.cm.Configuration.ConfigurationAttribute;
+
+/**
+ * An {@code Exception} class to inform the client of a {@code Configuration}
+ * about the {@link ConfigurationAttribute#READ_ONLY read only} state of a
+ * configuration object.
+ *
+ * @author $Id$
+ * @since 1.6
+ */
+public class ReadOnlyConfigurationException extends RuntimeException {
+ private static final long serialVersionUID = 1898442024230518832L;
+
+ /**
+ * Create a {@code ReadOnlyConfigurationException} object.
+ *
+ * @param reason reason for failure
+ */
+ public ReadOnlyConfigurationException(String reason) {
+ super(reason);
+ }
+}
diff --git a/bundles/org.eclipse.osgi.services/src/org/osgi/service/cm/SynchronousConfigurationListener.java b/bundles/org.eclipse.osgi.services/src/org/osgi/service/cm/SynchronousConfigurationListener.java
index 6eb8494c3..b59e4b0d9 100644
--- a/bundles/org.eclipse.osgi.services/src/org/osgi/service/cm/SynchronousConfigurationListener.java
+++ b/bundles/org.eclipse.osgi.services/src/org/osgi/service/cm/SynchronousConfigurationListener.java
@@ -1,6 +1,6 @@
/*
- * Copyright (c) OSGi Alliance (2012, 2013). All Rights Reserved.
- *
+ * Copyright (c) OSGi Alliance (2012, 2017). 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
@@ -22,7 +22,6 @@ import org.osgi.annotation.versioning.ConsumerType;
* Synchronous Listener for Configuration Events. When a
* {@code ConfigurationEvent} is fired, it is synchronously delivered to all
* {@code SynchronousConfigurationListener}s.
- *
* <p>
* {@code SynchronousConfigurationListener} objects are registered with the
* Framework service registry and are synchronously notified with a
@@ -32,13 +31,12 @@ import org.osgi.annotation.versioning.ConsumerType;
* {@code ConfigurationEvent} object to determine its type, the PID of the
* {@code Configuration} object with which it is associated, and the
* Configuration Admin service that fired the event.
- *
* <p>
* Security Considerations. Bundles wishing to synchronously monitor
* configuration events will require
* {@code ServicePermission[SynchronousConfigurationListener,REGISTER]} to
* register a {@code SynchronousConfigurationListener} service.
- *
+ *
* @author $Id$
* @since 1.5
* @ThreadSafe
diff --git a/bundles/org.eclipse.osgi.services/src/org/osgi/service/cm/package-info.java b/bundles/org.eclipse.osgi.services/src/org/osgi/service/cm/package-info.java
index f83587772..ba67de8bb 100644
--- a/bundles/org.eclipse.osgi.services/src/org/osgi/service/cm/package-info.java
+++ b/bundles/org.eclipse.osgi.services/src/org/osgi/service/cm/package-info.java
@@ -1,6 +1,6 @@
/*
- * Copyright (c) OSGi Alliance (2010, 2013). All Rights Reserved.
- *
+ * Copyright (c) OSGi Alliance (2010, 2017). 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
@@ -15,27 +15,25 @@
*/
/**
- * Configuration Admin Package Version 1.5.
- *
+ * Configuration Admin Package Version 1.6.
* <p>
* Bundles wishing to use this package must list the package in the
* Import-Package header of the bundle's manifest. This package has two types of
* users: the consumers that use the API in this package and the providers that
* implement the API in this package.
- *
* <p>
* Example import for consumers using the API in this package:
* <p>
- * {@code Import-Package: org.osgi.service.cm; version="[1.5,2.0)"}
+ * {@code Import-Package: org.osgi.service.cm; version="[1.6,2.0)"}
* <p>
* Example import for providers implementing the API in this package:
* <p>
- * {@code Import-Package: org.osgi.service.cm; version="[1.5,1.6)"}
- *
+ * {@code Import-Package: org.osgi.service.cm; version="[1.6,1.7)"}
+ *
* @author $Id$
*/
-@Version("1.5")
+@Version(ConfigurationConstants.CONFIGURATION_ADMIN_SPECIFICATION_VERSION)
package org.osgi.service.cm;
import org.osgi.annotation.versioning.Version;
diff --git a/bundles/org.eclipse.osgi.services/src/org/osgi/service/cm/packageinfo b/bundles/org.eclipse.osgi.services/src/org/osgi/service/cm/packageinfo
deleted file mode 100644
index ccee95e92..000000000
--- a/bundles/org.eclipse.osgi.services/src/org/osgi/service/cm/packageinfo
+++ /dev/null
@@ -1 +0,0 @@
-version 1.5

Back to the top