You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@tuscany.apache.org by rf...@apache.org on 2009/08/19 01:04:29 UTC
svn commit: r805623 [1/2] - in /tuscany/java/sca/modules/node-impl-osgi:
META-INF/ src/main/java/org/apache/tuscany/sca/osgi/service/discovery/impl/
src/main/java/org/apache/tuscany/sca/osgi/service/remoteadmin/
src/main/java/org/apache/tuscany/sca/osg...
Author: rfeng
Date: Tue Aug 18 23:04:29 2009
New Revision: 805623
URL: http://svn.apache.org/viewvc?rev=805623&view=rev
Log:
Update the osgi remote service admin interfaces/classes
Modified:
tuscany/java/sca/modules/node-impl-osgi/META-INF/MANIFEST.MF
tuscany/java/sca/modules/node-impl-osgi/src/main/java/org/apache/tuscany/sca/osgi/service/discovery/impl/LocalDiscoveryService.java
tuscany/java/sca/modules/node-impl-osgi/src/main/java/org/apache/tuscany/sca/osgi/service/remoteadmin/EndpointDescription.java
tuscany/java/sca/modules/node-impl-osgi/src/main/java/org/apache/tuscany/sca/osgi/service/remoteadmin/EndpointListener.java
tuscany/java/sca/modules/node-impl-osgi/src/main/java/org/apache/tuscany/sca/osgi/service/remoteadmin/EndpointPermission.java
tuscany/java/sca/modules/node-impl-osgi/src/main/java/org/apache/tuscany/sca/osgi/service/remoteadmin/ExportRegistration.java
tuscany/java/sca/modules/node-impl-osgi/src/main/java/org/apache/tuscany/sca/osgi/service/remoteadmin/ImportRegistration.java
tuscany/java/sca/modules/node-impl-osgi/src/main/java/org/apache/tuscany/sca/osgi/service/remoteadmin/RemoteAdminEvent.java
tuscany/java/sca/modules/node-impl-osgi/src/main/java/org/apache/tuscany/sca/osgi/service/remoteadmin/RemoteAdminListener.java
tuscany/java/sca/modules/node-impl-osgi/src/main/java/org/apache/tuscany/sca/osgi/service/remoteadmin/RemoteConstants.java
tuscany/java/sca/modules/node-impl-osgi/src/main/java/org/apache/tuscany/sca/osgi/service/remoteadmin/RemoteServiceAdmin.java
tuscany/java/sca/modules/node-impl-osgi/src/main/java/org/apache/tuscany/sca/osgi/service/remoteadmin/impl/EndpointDescriptionImpl.java
tuscany/java/sca/modules/node-impl-osgi/src/main/java/org/apache/tuscany/sca/osgi/service/remoteadmin/impl/RemoteControllerImpl.java
tuscany/java/sca/modules/node-impl-osgi/src/main/java/org/apache/tuscany/sca/osgi/service/remoteadmin/impl/RemoteServiceAdminImpl.java
Modified: tuscany/java/sca/modules/node-impl-osgi/META-INF/MANIFEST.MF
URL: http://svn.apache.org/viewvc/tuscany/java/sca/modules/node-impl-osgi/META-INF/MANIFEST.MF?rev=805623&r1=805622&r2=805623&view=diff
==============================================================================
--- tuscany/java/sca/modules/node-impl-osgi/META-INF/MANIFEST.MF (original)
+++ tuscany/java/sca/modules/node-impl-osgi/META-INF/MANIFEST.MF Tue Aug 18 23:04:29 2009
@@ -12,6 +12,9 @@
javax.xml.stream,
org.apache.tuscany.sca.assembly;version="2.0.0",
org.apache.tuscany.sca.assembly.builder;version="2.0.0",
+ org.apache.tuscany.sca.common.java.collection;version="2.0.0",
+ org.apache.tuscany.sca.common.java.io;version="2.0.0",
+ org.apache.tuscany.sca.common.xml.stax;version="2.0.0",
org.apache.tuscany.sca.contribution;version="2.0.0",
org.apache.tuscany.sca.contribution.processor;version="2.0.0",
org.apache.tuscany.sca.contribution.resolver;version="2.0.0",
Modified: tuscany/java/sca/modules/node-impl-osgi/src/main/java/org/apache/tuscany/sca/osgi/service/discovery/impl/LocalDiscoveryService.java
URL: http://svn.apache.org/viewvc/tuscany/java/sca/modules/node-impl-osgi/src/main/java/org/apache/tuscany/sca/osgi/service/discovery/impl/LocalDiscoveryService.java?rev=805623&r1=805622&r2=805623&view=diff
==============================================================================
--- tuscany/java/sca/modules/node-impl-osgi/src/main/java/org/apache/tuscany/sca/osgi/service/discovery/impl/LocalDiscoveryService.java (original)
+++ tuscany/java/sca/modules/node-impl-osgi/src/main/java/org/apache/tuscany/sca/osgi/service/discovery/impl/LocalDiscoveryService.java Tue Aug 18 23:04:29 2009
@@ -27,17 +27,19 @@
import java.util.ArrayList;
import java.util.Collections;
import java.util.Enumeration;
+import java.util.HashMap;
import java.util.Iterator;
import java.util.List;
import java.util.Map;
+import java.util.UUID;
import java.util.Map.Entry;
import java.util.logging.Level;
-import javax.xml.stream.XMLInputFactory;
-import javax.xml.stream.XMLOutputFactory;
import javax.xml.stream.XMLStreamReader;
import org.apache.tuscany.sca.assembly.AssemblyFactory;
+import org.apache.tuscany.sca.common.java.io.IOHelper;
+import org.apache.tuscany.sca.common.xml.stax.StAXHelper;
import org.apache.tuscany.sca.contribution.processor.ExtensibleStAXArtifactProcessor;
import org.apache.tuscany.sca.contribution.processor.StAXArtifactProcessor;
import org.apache.tuscany.sca.contribution.processor.StAXArtifactProcessorExtensionPoint;
@@ -48,15 +50,16 @@
import org.apache.tuscany.sca.monitor.Monitor;
import org.apache.tuscany.sca.monitor.MonitorFactory;
import org.apache.tuscany.sca.osgi.service.remoteadmin.EndpointDescription;
+import org.apache.tuscany.sca.osgi.service.remoteadmin.RemoteConstants;
import org.apache.tuscany.sca.osgi.service.remoteadmin.impl.EndpointDescriptionImpl;
import org.osgi.framework.Bundle;
import org.osgi.framework.BundleContext;
import org.osgi.framework.BundleEvent;
import org.osgi.framework.BundleListener;
+import org.osgi.framework.Constants;
public class LocalDiscoveryService extends AbstractDiscoveryService implements BundleListener {
- private XMLInputFactory xmlInputFactory;
- private XMLOutputFactory xmlOutputFactory;
+ private StAXHelper staxHelper;
private AssemblyFactory assemblyFactory;
private StAXArtifactProcessor processor;
@@ -71,8 +74,7 @@
FactoryExtensionPoint factories = registry.getExtensionPoint(FactoryExtensionPoint.class);
this.assemblyFactory = factories.getFactory(AssemblyFactory.class);
- this.xmlInputFactory = factories.getFactory(XMLInputFactory.class);
- this.xmlOutputFactory = factories.getFactory(XMLOutputFactory.class);
+ this.staxHelper = StAXHelper.getInstance(registry);
StAXArtifactProcessorExtensionPoint processors =
registry.getExtensionPoint(StAXArtifactProcessorExtensionPoint.class);
UtilityExtensionPoint utilities = this.registry.getExtensionPoint(UtilityExtensionPoint.class);
@@ -81,18 +83,32 @@
if (monitorFactory != null) {
monitor = monitorFactory.createMonitor();
}
- processor = new ExtensibleStAXArtifactProcessor(processors, xmlInputFactory, xmlOutputFactory, monitor);
+ processor =
+ new ExtensibleStAXArtifactProcessor(processors, staxHelper.getInputFactory(),
+ staxHelper.getOutputFactory(), monitor);
processExistingBundles();
}
public void bundleChanged(BundleEvent event) {
- switch (event.getType()) {
- case STARTED:
- discover(event.getBundle());
- break;
- case STOPPING:
- removeServicesDeclaredInBundle(event.getBundle());
- break;
+ try {
+ switch (event.getType()) {
+ case STARTED:
+ discover(event.getBundle());
+ break;
+ case STOPPING:
+ removeServicesDeclaredInBundle(event.getBundle());
+ break;
+ }
+ } catch (Throwable e) {
+ logger.log(Level.SEVERE, e.getMessage(), e);
+ if (e instanceof Error) {
+ throw (Error)e;
+ } else if (e instanceof RuntimeException) {
+ throw (RuntimeException)e;
+ } else {
+ // Should not happen
+ throw new RuntimeException(e);
+ }
}
}
@@ -137,8 +153,16 @@
}
private EndpointDescription createEndpointDescription(ServiceDescription sd) {
- // Endpoint endpoint = assemblyFactory.createEndpoint();
- EndpointDescription sed = new EndpointDescriptionImpl(sd.getInterfaces(), sd.getProperties());
+ Map<String, Object> props = new HashMap<String, Object>(sd.getProperties());
+ props.put(Constants.OBJECTCLASS, sd.getInterfaces().toArray(new String[sd.getInterfaces().size()]));
+ if (!props.containsKey(RemoteConstants.ENDPOINT_REMOTE_SERVICE_ID)) {
+ props.put(RemoteConstants.ENDPOINT_REMOTE_SERVICE_ID, UUID.randomUUID().toString());
+ }
+ if (!props.containsKey(RemoteConstants.ENDPOINT_URI)) {
+ props.put(RemoteConstants.ENDPOINT_URI, UUID.randomUUID().toString());
+ }
+
+ EndpointDescription sed = new EndpointDescriptionImpl(props);
return sed;
}
@@ -167,9 +191,9 @@
}
private ServiceDescriptions loadServiceDescriptions(URL url) throws Exception {
- InputStream is = url.openStream();
+ InputStream is = IOHelper.openStream(url);
try {
- XMLStreamReader reader = xmlInputFactory.createXMLStreamReader(is);
+ XMLStreamReader reader = staxHelper.createXMLStreamReader(is);
reader.nextTag();
Object model = processor.read(reader);
if (model instanceof ServiceDescriptions) {
Modified: tuscany/java/sca/modules/node-impl-osgi/src/main/java/org/apache/tuscany/sca/osgi/service/remoteadmin/EndpointDescription.java
URL: http://svn.apache.org/viewvc/tuscany/java/sca/modules/node-impl-osgi/src/main/java/org/apache/tuscany/sca/osgi/service/remoteadmin/EndpointDescription.java?rev=805623&r1=805622&r2=805623&view=diff
==============================================================================
--- tuscany/java/sca/modules/node-impl-osgi/src/main/java/org/apache/tuscany/sca/osgi/service/remoteadmin/EndpointDescription.java (original)
+++ tuscany/java/sca/modules/node-impl-osgi/src/main/java/org/apache/tuscany/sca/osgi/service/remoteadmin/EndpointDescription.java Tue Aug 18 23:04:29 2009
@@ -1,146 +1,296 @@
/*
+ * Copyright (c) OSGi Alliance (2008, 2009). All Rights Reserved.
*
- * Licensed to the Apache Software Foundation (ASF) under one
- * or more contributor license agreements. See the NOTICE file
- * distributed with this work for additional information
- * regarding copyright ownership. The ASF licenses this file
- * to you 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.
+ * 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.apache.tuscany.sca.osgi.service.remoteadmin;
-import java.net.URI;
+import java.io.Serializable;
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.Hashtable;
+import java.util.Iterator;
import java.util.List;
import java.util.Map;
+import org.osgi.framework.Constants;
+import org.osgi.framework.ServiceReference;
import org.osgi.framework.Version;
/**
* A description of an endpoint that provides sufficient information for a
- * compatible distribution provider to create a connection to this endpoint An
- * Endpoint Description is easy to transfer between different systems. This
+ * compatible distribution provider to create a connection to this endpoint
+ *
+ * An Endpoint Description is easy to transfer between different systems. This
* allows it to be used as a communications device to convey available endpoint
- * information to nodes in a network. An Endpoint Description reflects the
- * perspective of an importer. That is, the property keys have been chosen to
- * match filters that are created by client bundles that need a service.
+ * information to nodes in a network.
+ *
+ * An Endpoint Description reflects the perspective of an importer. That is, the
+ * property keys have been chosen to match filters that are created by client
+ * bundles that need a service.
*
* @Immutable
+ * @version $Revision$
*/
-public interface EndpointDescription {
+public class EndpointDescription implements Serializable {
+ private static final long serialVersionUID = 1L;
+ private static Version nullVersion = new Version("0");
+
+ final Map/* <String,Object> */properties = new Hashtable/* <String,Object> */();
+ final List /* String */interfaces;
+ final String remoteServiceId;
+ final String uri;
+
/**
- * Returns the configuration types. A distribution provider exports a
- * service with an endpoint. This endpoint uses some kind of communications
- * protocol with a set of configuration parameters. There are many different
- * types but each endpoint is configured by only one configuration type.
- * However, a distribution provider can be aware of different configuration
- * types and provide synonyms to increase the change a receiving distributon
- * provider can create a connection to this endpoint. This value represents
- * the RemoteConstants.SERVICE_IMPORTED_CONFIGS
- *
- * @return Returns The configuration type used for the associated endpoint
- * and optionally synonyms.
- */
- public List<String> getConfigurationTypes();
-
- /**
- * Return the list of intents implemented by this endpoint. The intents are
- * based on the service.intents on an imported service, except for any
- * intents that are additionally provided by the importing distribution
- * provider. All qualified intents must have been expanded. The property the
- * intents come from is RemoteConstants.SERVICE_INTENTS
+ * Create an Endpoint Description based on a Map.
*
- * @return A list of expanded intents that are provided by this endpoint.
+ * @param properties
+ * @throws IllegalArgumentException
+ * When the properties are not proper for an Endpoint
+ * Description
*/
- public List<String> getIntents();
+
+ public EndpointDescription(Map/* <String,Object> */properties) throws IllegalArgumentException {
+ this.properties.putAll(properties);
+
+ interfaces = verifyInterfacesProperty();
+ remoteServiceId = verifyStringProperty(RemoteConstants.ENDPOINT_REMOTE_SERVICE_ID);
+ uri = verifyStringProperty(RemoteConstants.ENDPOINT_URI);
+ }
/**
- * Answer the list of interfaces implemented by the exported service. If
- * this Endpoint Description does not map to a service, then this List must
- * be empty. The value of the interfaces is derived from the objectClass
- * property.
+ * Create an Endpoint Description based on a reference.
*
- * @return The list of Java interface names accessible by this endpoint
+ * @param ref A service reference that is exportable
+ * @throws IllegalArgumentException
+ */
+ public EndpointDescription(ServiceReference ref) throws IllegalArgumentException {
+ String[] keys = ref.getPropertyKeys();
+ for (int i = 0; i > keys.length; i++)
+ properties.put(keys[i], ref.getProperty(keys[i]));
+
+ interfaces = verifyInterfacesProperty();
+ remoteServiceId = verifyStringProperty(RemoteConstants.ENDPOINT_REMOTE_SERVICE_ID);
+ uri = verifyStringProperty(RemoteConstants.ENDPOINT_URI);
+ }
+
+ /**
+ * Verify and obtain the interface list from the properties.
+ * @return A list with the interface names.
+ * @throws IllegalArgumentException when
*/
- public List<String> getInterfaces();
+ protected List /* <String> */verifyInterfacesProperty() {
+ List l = null;
+
+ Object objectClass = properties.get(Constants.OBJECTCLASS);
+ if (objectClass == null)
+ l = Collections.EMPTY_LIST;
+ else if (!(objectClass instanceof String[]))
+ throw new IllegalArgumentException("objectClass must be a String[]");
+ else {
+ l = Collections.unmodifiableList(Arrays.asList((String[])objectClass));
+ for (Iterator i = l.iterator(); i.hasNext();) {
+ String interf = (String)i.next();
+ try {
+ getInterfaceVersion(interf);
+ } catch (Exception e) {
+ throw new IllegalArgumentException("Improper version for interface " + interf + " caused by " + e);
+ }
+ }
+ }
+ return l;
+ }
/**
- * Answer the version of the given interface. The version is encoded by
- * prefixing the given interface name with endpoint.version., and then using
- * this as a property key. The value must then be the Version object. For
- * example: endpoint.version.com.acme.Foo
+ * Verify and obtain the a required String property.
+ * @param propName The name of the
+ * @return The value of the property.
+ * @throws IllegalArgumentException when the property is not set or doesn't
+ * have the correct data type.
+ */
+ protected String verifyStringProperty(String propName) {
+ Object r = properties.get(propName);
+ if (r == null) {
+ throw new IllegalArgumentException("Required property not set: " + propName);
+ }
+ if (!(r instanceof String)) {
+ throw new IllegalArgumentException("Required property is not a string: " + propName);
+ }
+ return (String)r;
+ }
+
+ /**
+ * Returns the endpoint's URI.
*
- * @param name The name of the interface for which a version is requested
- * @return Returns The version of the given interface or null if the
- * interface has no version in this Endpoint Description
+ * The URI is an opaque id for an endpoint in URI form. No two different
+ * endpoints must have the same URI, two Endpoint Descriptions with the same
+ * URI must represent the same endpoint.
+ *
+ * The value of the URI is stored in the
+ * {@link RemoteConstants#ENDPOINT_URI} property.
+ *
+ * @return The URI of the endpoint, never null.
*/
- public Version getInterfaceVersion(String name);
+ public String getURI() {
+ return uri;
+ }
/**
- * Returns An immutable map referring to the properties of this Endpoint
- * Description.
+ * Answer the list of interfaces implemented by the exported service.
+ *
+ * If this Endpoint Description does not map to a service, then this List
+ * must be empty.
+ *
+ * The value of the interfaces is derived from the <code>objectClass</code>
+ * property.
*
- * @return Returns all endpoint properties.
+ * @return The read only list of Java interface names accessible by this
+ * endpoint.
*/
- public Map<String, Object> getProperties();
+ public List/* <String> */getInterfaces() {
+ return interfaces;
+ }
+
+ /**
+ * Answer the version of the given interface.
+ *
+ * The version is encoded by prefixing the given interface name with
+ * <code>endpoint.version.</code>, and then using this as a property key.
+ * The value must then be the <code>Version</code> object. For example:
+ *
+ * <pre>
+ * endpoint.version.com.acme.Foo
+ * </pre>
+ *
+ * @param name
+ * The name of the interface for which a version is requested
+ * @return The version of the given interface or <code>null</code> if the
+ * interface has no version in this Endpoint Description
+ */
+ public Version getInterfaceVersion(String name) {
+ String v = (String)properties.get("endpoint.version." + name);
+ if (v == null) {
+ return nullVersion;
+ } else {
+ return new Version(v);
+ }
+ }
/**
* Returns the universally unique id for the service exported through this
- * endpoint. Each service in the OSGi service registry has a universally
- * unique id. The UUID can be used to detect that two Endpoint Descriptions
- * really refer to the same registered service instance in some remote
- * framework. This UUID can be used to filter out duplicate ways of
- * communicating with the same service. The service UUID is constructed from
- * two properties. It is first the org.osgi.framework.uuid System property
- * set by the framework or through configuration. This property must
- * uniquely represents the UUID of a framework instance. This UUID must not
- * contain any dots ('.' .). This is suffixed with a dot and then the
- * service.id service property of the service.
- * <p>
- * For example: 72dc5fd9-5f8f-4f8f-9821-9ebb433a5b72.121
- * <p>
+ * endpoint.
+ *
+ * Each service in the OSGi service registry has a universally unique id.
+ * The UUID can be used to detect that two Endpoint Descriptions really
+ * refer to the same registered service instance in some remote framework.
+ * This UUID can be used to filter out duplicate ways of communicating with
+ * the same service.
+ *
+ * The service UUID is constructed from two properties. It is first the
+ * <code>org.osgi.framework.uuid</code> System property set by the
+ * framework or through configuration. This property must uniquely
+ * represents the UUID of a framework instance. This UUID must not contain
+ * any dots ('.' \u002E). This is suffixed with a dot and then the
+ * <code>service.id</code> service property of the service.
+ *
+ * For example:
+ *
+ * <pre>
+ * 72dc5fd9-5f8f-4f8f-9821-9ebb433a5b72.121
+ * </pre>
+ *
* If this Endpoint Description does not map to a remote OSGi service, for
* example some web service, then the Endpoint Description must not have a
* service UUID. If two endpoints have the same URI, then they must refer to
* the same OSGi service.
*
- * @return Returns Unique id of a service or null if this Endpoint
+ * Starting . is not an OSGi service.
+ *
+ * @return Unique id of a service or <code>null</code> if this Endpoint
* Description does not relate to an OSGi service
+ *
*/
- public String getRemoteServiceID();
+ public String getRemoteServiceID() {
+ return remoteServiceId;
+ }
/**
- * Returns the endpoint's URI. The URI is an opaque id for an endpoint in
- * URI form. No two different endpoints must have the same URI, two Endpoint
- * Descriptions with the same URI must represent the same endpoint. The
- * value of the URI is stored in the RemoteConstants.ENDPOINT_URI property.
+ * Returns the configuration types.
*
- * @return Returns The URI of the endpoint, never null.
+ * A distribution provider exports a service with an endpoint. This endpoint
+ * uses some kind of communications protocol with a set of configuration
+ * parameters. There are many different types but each endpoint is
+ * configured by only one configuration type. However, a distribution
+ * provider can be aware of different configuration types and provide
+ * synonyms to increase the change a receiving distribution provider can
+ * create a connection to this endpoint.
+ *
+ * This value represents the
+ * {@link RemoteConstants#SERVICE_IMPORTED_CONFIGS}
+ *
+ * @return The configuration type used for the associated endpoint and
+ * optionally synonyms.
*/
- public URI getURI();
+ public List/* <String> */getConfigurationTypes() {
+ // TODO
+ return null;
+ }
+
+ /**
+ * Return the list of intents implemented by this endpoint.
+ *
+ * The intents are based on the service.intents on an imported service,
+ * except for any intents that are additionally provided by the importing
+ * distribution provider. All qualified intents must have been expanded.
+ *
+ * The property the intents come from is
+ * {@link RemoteConstants#SERVICE_INTENTS}
+ *
+ * @return A list of expanded intents that are provided by this endpoint.
+ */
+ public List/* <String> */getIntents() {
+ // TODO
+ return null;
+
+ }
+
+ /**
+ * Returns all endpoint properties.
+ *
+ * @return An immutable map referring to the properties of this Endpoint
+ * Description.
+ */
+ public Map/* <String, Object> */getProperties() {
+ // TODO
+ return Collections.unmodifiableMap(properties);
+ }
/**
* Two endpoints are equal if their URIs are equal, the hash code is
* therefore derived from the URI.
*/
- public int hashCode();
+ public int hashCode() {
+ // TODO
+ return getURI().hashCode();
+ }
/**
* Two endpoints are equal if their URIs are equal.
- *
- * @param other
- * @return
*/
- public boolean equals(Object other);
-
+ public boolean equals(Object other) {
+ if (other instanceof EndpointDescription) {
+ return getURI().equals(((EndpointDescription)other).getURI());
+ }
+ return false;
+ }
}
Modified: tuscany/java/sca/modules/node-impl-osgi/src/main/java/org/apache/tuscany/sca/osgi/service/remoteadmin/EndpointListener.java
URL: http://svn.apache.org/viewvc/tuscany/java/sca/modules/node-impl-osgi/src/main/java/org/apache/tuscany/sca/osgi/service/remoteadmin/EndpointListener.java?rev=805623&r1=805622&r2=805623&view=diff
==============================================================================
--- tuscany/java/sca/modules/node-impl-osgi/src/main/java/org/apache/tuscany/sca/osgi/service/remoteadmin/EndpointListener.java (original)
+++ tuscany/java/sca/modules/node-impl-osgi/src/main/java/org/apache/tuscany/sca/osgi/service/remoteadmin/EndpointListener.java Tue Aug 18 23:04:29 2009
@@ -1,67 +1,67 @@
-/*
- *
- * Licensed to the Apache Software Foundation (ASF) under one
- * or more contributor license agreements. See the NOTICE file
- * distributed with this work for additional information
- * regarding copyright ownership. The ASF licenses this file
- * to you 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.apache.tuscany.sca.osgi.service.remoteadmin;
/**
- * A whiteboard service that represents a listener for endpoints. An Endpoint
- * Listener represents a participant in the distributed model that is interested
- * in Endpoint Descriptions. This whiteboard service can be used in many
- * different scenarios. However, the primary use case is to allow a remote
- * controller to be informed of End Point Descriptions available in the network
- * and inform the network about available End Point Descriptions. Both the
- * network bundle and the controller bundle register a Endpoint Listener
- * service. The controller informs the network bundle about End Points that it
- * creates. The network bundles then uses a protocol like for example SLP to
- * announce these local end-points to the network. If the network bundle
- * discovers a new Endpoint through its discovery protocol, then it sends an End
- * Point Description to all the End Point Listener services that are registered
- * (except its own) that have specified an interest in that endpoint.
- * <p>
- * Endpoint Listener services can express their scope with the service property
- * ENDPOINT_LISTENER_SCOPE. This service property is a list of filters. An
- * Endpoint Description should only be given to a Endpoint Listener when there
- * is at least one filter that matches the Endpoint Description properties.
- * given to it. This filter model is quite flexible. For example, a discovery
- * bundle is only interested in locally originating Endpoint Descriptions. The
- * following filter ensure that it only sees local endpoints.
- * <p>
- * (org.osgi.framework.uuid=72dc5fd9-5f8f-4f8f-9821- 9ebb433a5b72)<br>
+ * A whiteboard service that represents a listener for endpoints.
+ *
+ * An Endpoint Listener represents a participant in the distributed model that
+ * is interested in Endpoint Descriptions.
+ *
+ * This whiteboard service can be used in many different scenarios. However, the
+ * primary use case is to allow a remote controller to be informed of End Point
+ * Descriptions available in the network and inform the network about available
+ * End Point Descriptions.
+ *
+ * Both the network bundle and the controller bundle register a Endpoint
+ * Listener service. The controller informs the network bundle about End Points
+ * that it creates. The network bundles then uses a protocol like for example
+ * SLP to announce these local end-points to the network.
+ *
+ * If the network bundle discovers a new Endpoint through its discovery
+ * protocol, then it sends an End Point Description to all the End Point
+ * Listener services that are registered (except its own) that have specified an
+ * interest in that endpoint.
+ *
+ * Endpoint Listener services can express their <i>scope</i> with the service
+ * property {@link #ENDPOINT_LISTENER_SCOPE}. This service property is a list
+ * of filters. An Endpoint Description should only be given to a Endpoint
+ * Listener when there is at least one filter that matches the Endpoint
+ * Description properties. given to it.
+ *
+ * This filter model is quite flexible. For example, a discovery bundle is only
+ * interested in locally originating Endpoint Descriptions. The following filter
+ * ensure that it only sees local endpoints.
+ *
+ * <pre>
+ * (org.osgi.framework.uuid=72dc5fd9-5f8f-4f8f-9821-9ebb433a5b72)
+ * </pre>
+ *
* In the same vein, a controller that is only interested in remote Endpoint
* Descriptions can use a filter like:
- * <p>
- * (!(org.osgi.framework.uuid=72dc5fd9-5f8f-4f8f-9821-9ebb433a5b72)) <br>
+ *
+ * <pre>
+ * (!(org.osgi.framework.uuid=72dc5fd9-5f8f-4f8f-9821-9ebb433a5b72))
+ * </pre>
+ *
* Where in both cases, the given UUID is the UUID of the local framework that
- * can be found in the Framework properties. The Endpoint Listeners scope maps
- * very well to the service hooks. A controller can just register all filters
- * found from the Listener Hook as its scope. This will automatically provide it
- * with all known endpoints that match the given scope, without having to
- * inspect the filter string. In general, when an Endpoint Description is
- * discovered, it should be dispatched to all registered Endpoint Listener
- * services. If a new Endpoint Listener is registered, it should be informed
- * about all currently known Endpoints that match its scope. If a getter of the
- * Endpoint Listener service is unregistered, then all its registered Endpoint
- * Description objects must be removed. The Endpoint Listener models a best
- * effort approach. Participating bundles should do their utmost to keep the
- * listeners up to date, but implementers should realize that many endpoints
- * come through unreliable discovery processes.
+ * can be found in the Framework properties.
+ *
+ * The Endpoint Listener's scope maps very well to the service hooks. A
+ * controller can just register all filters found from the Listener Hook as its
+ * scope. This will automatically provide it with all known endpoints that match
+ * the given scope, without having to inspect the filter string.
+ *
+ * In general, when an Endpoint Description is discovered, it should be
+ * dispatched to all registered Endpoint Listener services. If a new Endpoint
+ * Listener is registered, it should be informed about all currently known
+ * Endpoints that match its scope. If a getter of the Endpoint Listener service
+ * is unregistered, then all its registered Endpoint Description objects must be
+ * removed.
+ *
+ * The Endpoint Listener models a <i>best effort</i> approach. Participating
+ * bundles should do their utmost to keep the listeners up to date, but
+ * implementers should realize that many endpoints come through unreliable
+ * discovery processes.
+ *
*
* @ThreadSafe
*/
@@ -69,33 +69,41 @@
/**
* Specifies the interest of this listener with filters. This listener is
* only interested in Endpoint Descriptions where its properties match the
- * given filter. The type of this property must be String+.
+ * given filter. The type of this property must be <code>String+</code>.
*/
- public static final String ENDPOINT_LISTENER_SCOPE = "endpoint.listener.scope";
+ String ENDPOINT_LISTENER_SCOPE = "endpoint.listener.scope";
/**
- * Register an endpoint with this listener. If the endpoint matches one of
- * the filters registered with the ENDPOINT_LISTENER_SCOPE service property
- * then this filter should be given as the matchedFilter parameter. When
- * this service is first registered or it is modified, it should receive all
- * known endpoints matching the filter.
- *
- * @param endpoint The Endpoint Description to be published
- * @param matchedFilter matchedFilter The filter from the
- * ENDPOINT_LISTENER_SCOPE that matched the endpoint, must not be
- * null.
+ * Register an endpoint with this listener.
+ *
+ * If the endpoint matches one of the filters registered with the
+ * {@link #ENDPOINT_LISTENER_SCOPE} service property then this filter should
+ * be given as the <code>matchedFilter</code> parameter.
+ *
+ * When this service is first registered or it is modified, it should
+ * receive all known endpoints matching the filter.
+ *
+ * @param endpoint
+ * The Endpoint Description to be published
+ * @param matchedFilter
+ * The filter from the {@link #ENDPOINT_LISTENER_SCOPE} that
+ * matched the endpoint, must not be <code>null</code>.
*/
- public void addEndpoint(EndpointDescription endpoint, String matchedFilter);
+ void addEndpoint(EndpointDescription endpoint, String matchedFilter);
/**
- * Remove the registration of an endpoint. If an endpoint that was
- * registered with the addEndpoint method is no longer available then this
- * method should be called. This will remove the endpoint from the listener.
+ * Remove the registration of an endpoint.
+ *
+ * If an endpoint that was registered with the {@link #addEndpoint}
+ * method is no longer available then this method should be called. This
+ * will remove the endpoint from the listener.
+ *
* It is not necessary to remove endpoints when the service is unregistered
* or modified in such a way that not all endpoints match the interest
* filter anymore.
*
- * @param endpoint The Endpoint Description that is no longer valid.
+ * @param endpoint
+ * The Endpoint Description that is no longer valid.
*/
- public void removeEndpoint(EndpointDescription endpoint);
+ void removeEndpoint(EndpointDescription endpoint);
}
Modified: tuscany/java/sca/modules/node-impl-osgi/src/main/java/org/apache/tuscany/sca/osgi/service/remoteadmin/EndpointPermission.java
URL: http://svn.apache.org/viewvc/tuscany/java/sca/modules/node-impl-osgi/src/main/java/org/apache/tuscany/sca/osgi/service/remoteadmin/EndpointPermission.java?rev=805623&r1=805622&r2=805623&view=diff
==============================================================================
--- tuscany/java/sca/modules/node-impl-osgi/src/main/java/org/apache/tuscany/sca/osgi/service/remoteadmin/EndpointPermission.java (original)
+++ tuscany/java/sca/modules/node-impl-osgi/src/main/java/org/apache/tuscany/sca/osgi/service/remoteadmin/EndpointPermission.java Tue Aug 18 23:04:29 2009
@@ -1,172 +1,918 @@
+package org.apache.tuscany.sca.osgi.service.remoteadmin;
+
+// TODO Hacked from ServiePermission
+
/*
- *
- * Licensed to the Apache Software Foundation (ASF) under one
- * or more contributor license agreements. See the NOTICE file
- * distributed with this work for additional information
- * regarding copyright ownership. The ASF licenses this file
- * to you 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
+ * Copyright (c) OSGi Alliance (2000, 2009). All Rights Reserved.
*
- * 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.
+ * 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.apache.tuscany.sca.osgi.service.remoteadmin;
+import java.io.*;
+import java.security.*;
+import java.util.*;
-import java.security.BasicPermission;
-import java.security.Permission;
-import java.security.PermissionCollection;
+import org.osgi.framework.*;
/**
- * A bundles authority to register or get a service.
+ * A bundle's authority to register or get a service.
* <ul>
- * <li>The register action allows a bundle to register a service on the
- * specified names.
- * <li>The get action allows a bundle to detect a service and get it.
- * EndpointPermission to get the specific service.
+ * <li>The <code>register</code> action allows a bundle to register a service
+ * on the specified names.
+ * <li>The <code>get</code> action allows a bundle to detect a service and
+ * get it.
* </ul>
+ * Permission to get a service is required in order to detect events regarding
+ * the service. Untrusted bundles should not be able to detect the presence of
+ * certain services unless they have the appropriate
+ * <code>EndpointPermission</code> to get the specific service.
*
* @ThreadSafe
+ * @version $Revision$
*/
+
public final class EndpointPermission extends BasicPermission {
- private static final long serialVersionUID = 577543263888050488L;
+ static final long serialVersionUID = -7662148639076511574L;
/**
- * The action string get.
+ * The action string <code>get</code>.
*/
- public static final String EXPORT = "export";
+ public final static String EXPORT = "export";
/**
- * The action string register.
+ * The action string <code>register</code>.
*/
- public static final String IMPORT = "import";
-
- private String actions;
-
- /**
- *Create a new EndpointPermission.
- *
- * @param name The service class name The name of the service is specified
- * as a fully qualified class name. Wildcards may be used.
- * <p>
- * name ::= <class name> | <class name ending in ".*"> | *
- * <p>
- * Examples:
- * <ul>
- * <li>org.osgi.service.http.HttpService
- * <li>org.osgi.service.http.*
- * <li>*
- * </ul>
- * For the get action, the name can also be a filter expression.
- * The filter gives access to the service properties as well as
- * the following attributes:
- * <p>
- * <ul>
- * <li>signer - A Distinguished Name chain used to sign the
- * bundle publishing the service. Wildcards in a DN are not
- * matched according to the filter string rules, but according to
- * the rules defined for a DN chain.
- * <li>location - The location of the bundle publishing the
- * service.
- * <li>id - The bundle ID of the bundle publishing the service.
- * <li>name - The symbolic name of the bundle publishing the
- * service.
- * </ul>
- * Since the above attribute names may conflict with service
- * property names used by a service, you can prefix an attribute
- * name with '@' in the filter expression to match against the
- * service property and not one of the above attributes. Filter
- * attribute names are processed in a case sensitive manner
- * unless the attribute references a service property. Service
- * properties names are case insensitive.
- * <p>
- * There are two possible actions: get and register. The get
- * permission allows the owner of this permission to obtain a
- * service with this name. The register permission allows the
- * bundle to register a service under that name.
- * @param actions actions get,register (canonical order)
- * @throws IllegalArgumentException If the specified name is a filter
- * expression and either the specified action is not get or the
- * filter has an invalid syntax.
+ public final static String IMPORT = "import";
+
+ public final static String LISTENING = "listening";
+
+ private final static int ACTION_EXPORT = 0x00000001;
+ private final static int ACTION_IMPORT = 0x00000002;
+ private final static int ACTION_ALL = ACTION_EXPORT | ACTION_IMPORT;
+ final static int ACTION_NONE = 0;
+
+ /**
+ * The actions mask.
+ */
+ transient int action_mask;
+
+ /**
+ * The actions in canonical form.
+ *
+ * @serial
+ */
+ private volatile String actions = null;
+
+ /**
+ * The service used by this EndpointPermission. Must be null if not
+ * constructed with a service.
+ */
+ transient final EndpointDescription endpoint;
+
+ /**
+ * The object classes for this EndpointPermission. Must be null if not
+ * constructed with a service.
+ */
+ transient final String[] objectClass;
+
+ /**
+ * If this EndpointPermission was constructed with a filter, this holds a
+ * Filter matching object used to evaluate the filter in implies.
+ */
+ transient Filter filter;
+
+ /**
+ * This dictionary holds the properties of the permission, used to match a
+ * filter in implies. This is not initialized until necessary, and then
+ * cached in this object.
+ */
+ private transient volatile Dictionary properties;
+
+ /**
+ * True if constructed with a name and the name is "*" or ends with ".*".
+ */
+ private transient boolean wildcard;
+
+ /**
+ * If constructed with a name and the name ends with ".*", this contains the
+ * name without the final "*".
+ */
+ private transient String prefix;
+
+ /**
+ * Create a new EndpointPermission.
+ *
+ * <p>
+ * The name of the service is specified as a fully qualified class name.
+ * Wildcards may be used.
+ *
+ * <pre>
+ * name ::= <class name> | <class name ending in ".*"> | *
+ * </pre>
+ *
+ * Examples:
+ *
+ * <pre>
+ * org.osgi.service.http.HttpService
+ * org.osgi.service.http.*
+ * *
+ * </pre>
+ *
+ * For the <code>get</code> action, the name can also be a filter
+ * expression. The filter gives access to the service properties as well as
+ * the following attributes:
+ * <ul>
+ * <li>signer - A Distinguished Name chain used to sign the bundle
+ * publishing the service. Wildcards in a DN are not matched according to
+ * the filter string rules, but according to the rules defined for a DN
+ * chain.</li>
+ * <li>location - The location of the bundle publishing the service.</li>
+ * <li>id - The bundle ID of the bundle publishing the service.</li>
+ * <li>name - The symbolic name of the bundle publishing the service.</li>
+ * </ul>
+ * Since the above attribute names may conflict with service property names
+ * used by a service, you can prefix an attribute name with '@' in the
+ * filter expression to match against the service property and not one of
+ * the above attributes. Filter attribute names are processed in a case
+ * sensitive manner unless the attribute references a service property.
+ * Service properties names are case insensitive.
+ *
+ * <p>
+ * There are two possible actions: <code>get</code> and
+ * <code>register</code>. The <code>get</code> permission allows the
+ * owner of this permission to obtain a service with this name. The
+ * <code>register</code> permission allows the bundle to register a
+ * service under that name.
+ *
+ * @param name
+ * The service class name
+ * @param actions
+ * <code>get</code>,<code>register</code> (canonical order)
+ * @throws IllegalArgumentException
+ * If the specified name is a filter expression and either the
+ * specified action is not <code>get</code> or the filter has
+ * an invalid syntax.
*/
public EndpointPermission(String name, String actions) {
- super(name);
- this.actions = actions;
+ this(name, parseActions(actions));
+ if ((filter != null) && ((action_mask & ACTION_ALL) != ACTION_EXPORT)) {
+ throw new IllegalArgumentException("invalid action string for filter expression");
+ }
}
/**
- * Creates a new requested EndpointPermission object to be used by code that
- * must perform checkPermission for the get action. EndpointPermission
- * objects created with this constructor cannot be added to a
- * EndpointPermission permission collection.
+ * Creates a new requested <code>EndpointPermission</code> object to be
+ * used by code that must perform <code>checkPermission</code> for the
+ * <code>get</code> action. <code>EndpointPermission</code> objects
+ * created with this constructor cannot be added to a
+ * <code>EndpointPermission</code> permission collection.
*
- * @param endpoint The requested service.
- * @param actions The action get.
- * @throws IllegalArgumentException If the specified action is not get or
- * reference is null.
+ * @param endpoint
+ * The requested service.
+ * @param actions
+ * The action <code>get</code>.
+ * @throws IllegalArgumentException
+ * If the specified action is not <code>get</code> or
+ * reference is <code>null</code>.
+ * @since 1.5
*/
public EndpointPermission(EndpointDescription endpoint, String actions) {
- super(null);
- this.actions = actions;
+ super(createName(endpoint));
+ setTransients(null, parseActions(actions));
+ this.endpoint = endpoint;
+ this.objectClass = (String[])endpoint.getProperties().get(Constants.OBJECTCLASS);
+ if ((action_mask & ACTION_ALL) != ACTION_EXPORT) {
+ throw new IllegalArgumentException("invalid action string");
+ }
}
/**
- * Determines the equality of two EndpointPermission objects. Checks that
- * specified object has the same class name and action as this
- * EndpointPermission. obj The object to test for equality.
+ * Create a permission name from a EndpointDescription TODO Needs work
*
- * @return true if obj is a EndpointPermission, and has the same class name
- * and actions as this EndpointPermission object; false otherwise.
+ * @param endpoint
+ * EndpointDescription to use to create permission name.
+ * @return permission name.
*/
- public boolean equals(Object obj) {
- return super.equals(obj);
+ private static String createName(EndpointDescription endpoint) {
+ if (endpoint == null) {
+ throw new IllegalArgumentException("reference must not be null");
+ }
+ StringBuffer sb = new StringBuffer("(service.id=");
+ // TODO sb.append(endpoint.getProperty(Constants.SERVICE_ID));
+ sb.append(")");
+ return sb.toString();
+ }
+
+ /**
+ * Package private constructor used by EndpointPermissionCollection.
+ *
+ * @param name
+ * class name
+ * @param mask
+ * action mask
+ */
+ EndpointPermission(String name, int mask) {
+ super(name);
+ setTransients(parseFilter(name), mask);
+ this.endpoint = null;
+ this.objectClass = null;
+ }
+
+ /**
+ * Called by constructors and when deserialized.
+ *
+ * @param mask
+ * action mask
+ */
+ private void setTransients(Filter f, int mask) {
+ if ((mask == ACTION_NONE) || ((mask & ACTION_ALL) != mask)) {
+ throw new IllegalArgumentException("invalid action string");
+ }
+ action_mask = mask;
+ filter = f;
+ if (f == null) {
+ String name = getName();
+ int l = name.length();
+ /* if "*" or endsWith ".*" */
+ wildcard = ((name.charAt(l - 1) == '*') && ((l == 1) || (name.charAt(l - 2) == '.')));
+ if (wildcard && (l > 1)) {
+ prefix = name.substring(0, l - 1);
+ }
+ }
+ }
+
+ /**
+ * Parse action string into action mask.
+ *
+ * @param actions
+ * Action string.
+ * @return action mask.
+ */
+ private static int parseActions(String actions) {
+ boolean seencomma = false;
+
+ int mask = ACTION_NONE;
+
+ if (actions == null) {
+ return mask;
+ }
+
+ char[] a = actions.toCharArray();
+
+ int i = a.length - 1;
+ if (i < 0)
+ return mask;
+
+ while (i != -1) {
+ char c;
+
+ // skip whitespace
+ while ((i != -1) && ((c = a[i]) == ' ' || c == '\r' || c == '\n' || c == '\f' || c == '\t'))
+ i--;
+
+ // check for the known strings
+ int matchlen;
+
+ if (i >= 2 && (a[i - 2] == 'g' || a[i - 2] == 'G')
+ && (a[i - 1] == 'e' || a[i - 1] == 'E')
+ && (a[i] == 't' || a[i] == 'T')) {
+ matchlen = 3;
+ mask |= ACTION_EXPORT;
+
+ } else if (i >= 7 && (a[i - 7] == 'r' || a[i - 7] == 'R')
+ && (a[i - 6] == 'e' || a[i - 6] == 'E')
+ && (a[i - 5] == 'g' || a[i - 5] == 'G')
+ && (a[i - 4] == 'i' || a[i - 4] == 'I')
+ && (a[i - 3] == 's' || a[i - 3] == 'S')
+ && (a[i - 2] == 't' || a[i - 2] == 'T')
+ && (a[i - 1] == 'e' || a[i - 1] == 'E')
+ && (a[i] == 'r' || a[i] == 'R')) {
+ matchlen = 8;
+ mask |= ACTION_IMPORT;
+
+ } else {
+ // parse error
+ throw new IllegalArgumentException("invalid permission: " + actions);
+ }
+
+ // make sure we didn't just match the tail of a word
+ // like "ackbarfregister". Also, skip to the comma.
+ seencomma = false;
+ while (i >= matchlen && !seencomma) {
+ switch (a[i - matchlen]) {
+ case ',':
+ seencomma = true;
+ /* FALLTHROUGH */
+ case ' ':
+ case '\r':
+ case '\n':
+ case '\f':
+ case '\t':
+ break;
+ default:
+ throw new IllegalArgumentException("invalid permission: " + actions);
+ }
+ i--;
+ }
+
+ // point i at the location of the comma minus one (or -1).
+ i -= matchlen;
+ }
+
+ if (seencomma) {
+ throw new IllegalArgumentException("invalid permission: " + actions);
+ }
+
+ return mask;
+ }
+
+ /**
+ * Parse filter string into a Filter object.
+ *
+ * @param filterString
+ * The filter string to parse.
+ * @return a Filter for this bundle. If the specified filterString is not a
+ * filter expression, then <code>null</code> is returned.
+ * @throws IllegalArgumentException
+ * If the filter syntax is invalid.
+ */
+ private static Filter parseFilter(String filterString) {
+ filterString = filterString.trim();
+ if (filterString.charAt(0) != '(') {
+ return null;
+ }
+
+ try {
+ return FrameworkUtil.createFilter(filterString);
+ } catch (InvalidSyntaxException e) {
+ IllegalArgumentException iae = new IllegalArgumentException("invalid filter");
+ iae.initCause(e);
+ throw iae;
+ }
+ }
+
+ /**
+ * Determines if a <code>EndpointPermission</code> object "implies" the
+ * specified permission.
+ *
+ * @param p
+ * The target permission to check.
+ * @return <code>true</code> if the specified permission is implied by
+ * this object; <code>false</code> otherwise.
+ */
+ public boolean implies(Permission p) {
+ if (!(p instanceof EndpointPermission)) {
+ return false;
+ }
+ EndpointPermission requested = (EndpointPermission)p;
+ if (endpoint != null) {
+ return false;
+ }
+ // if requested permission has a filter, then it is an invalid argument
+ if (requested.filter != null) {
+ return false;
+ }
+ return implies0(requested, ACTION_NONE);
+ }
+
+ /**
+ * Internal implies method. Used by the implies and the permission
+ * collection implies methods.
+ *
+ * @param requested
+ * The requested EndpointPermission which has already be
+ * validated as a proper argument. The requested
+ * EndpointPermission must not have a filter expression.
+ * @param effective
+ * The effective actions with which to start.
+ * @return <code>true</code> if the specified permission is implied by
+ * this object; <code>false</code> otherwise.
+ */
+ boolean implies0(EndpointPermission requested, int effective) {
+ /* check actions first - much faster */
+ effective |= action_mask;
+ final int desired = requested.action_mask;
+ if ((effective & desired) != desired) {
+ return false;
+ }
+ /* we have name of "*" */
+ if (wildcard && (prefix == null)) {
+ return true;
+ }
+ /* if we have a filter */
+ Filter f = filter;
+ if (f != null) {
+ return f.matchCase(requested.getProperties());
+ }
+ /* if requested permission not created with EndpointDescription */
+ String[] requestedNames = requested.objectClass;
+ if (requestedNames == null) {
+ return super.implies(requested);
+ }
+ /* requested permission created with EndpointDescription */
+ if (wildcard) {
+ int pl = prefix.length();
+ for (int i = 0, l = requestedNames.length; i < l; i++) {
+ String requestedName = requestedNames[i];
+ if ((requestedName.length() > pl) && requestedName.startsWith(prefix)) {
+ return true;
+ }
+ }
+ } else {
+ String name = getName();
+ for (int i = 0, l = requestedNames.length; i < l; i++) {
+ if (requestedNames[i].equals(name)) {
+ return true;
+ }
+ }
+ }
+ return false;
}
/**
* Returns the canonical string representation of the actions. Always
- * returns present actions in the following order: get, register.
+ * returns present actions in the following order: <code>get</code>,
+ * <code>register</code>.
*
* @return The canonical string representation of the actions.
*/
public String getActions() {
- return actions;
+ String result = actions;
+ if (result == null) {
+ StringBuffer sb = new StringBuffer();
+ boolean comma = false;
+
+ int mask = action_mask;
+ if ((mask & ACTION_EXPORT) == ACTION_EXPORT) {
+ sb.append(EXPORT);
+ comma = true;
+ }
+
+ if ((mask & ACTION_IMPORT) == ACTION_IMPORT) {
+ if (comma)
+ sb.append(',');
+ sb.append(IMPORT);
+ }
+
+ actions = result = sb.toString();
+ }
+
+ return result;
}
/**
- * Returns the hash code value for this object. Returns Hash code value for
- * this object.
+ * Returns a new <code>PermissionCollection</code> object for storing
+ * <code>EndpointPermission<code> objects.
+ *
+ * @return A new <code>PermissionCollection</code> object suitable for storing
+ * <code>EndpointPermission</code> objects.
+ */
+ public PermissionCollection newPermissionCollection() {
+ return new EndpointPermissionCollection();
+ }
+
+ /**
+ * Determines the equality of two EndpointPermission objects.
*
- * @return
+ * Checks that specified object has the same class name and action as this
+ * <code>EndpointPermission</code>.
+ *
+ * @param obj
+ * The object to test for equality.
+ * @return true if obj is a <code>EndpointPermission</code>, and has the
+ * same class name and actions as this
+ * <code>EndpointPermission</code> object; <code>false</code>
+ * otherwise.
+ */
+ public boolean equals(Object obj) {
+ if (obj == this) {
+ return true;
+ }
+
+ if (!(obj instanceof EndpointPermission)) {
+ return false;
+ }
+
+ EndpointPermission sp = (EndpointPermission)obj;
+
+ return (action_mask == sp.action_mask) && getName().equals(sp.getName())
+ && ((endpoint == sp.endpoint) || ((endpoint != null) && (sp.endpoint != null) && endpoint
+ .equals(sp.endpoint)));
+ }
+
+ /**
+ * Returns the hash code value for this object.
+ *
+ * @return Hash code value for this object.
*/
public int hashCode() {
- return super.hashCode();
+ int h = 31 * 17 + getName().hashCode();
+ h = 31 * h + getActions().hashCode();
+ if (endpoint != null) {
+ h = 31 * h + endpoint.hashCode();
+ }
+ return h;
+ }
+
+ /**
+ * WriteObject is called to save the state of this permission to a stream.
+ * The actions are serialized, and the superclass takes care of the name.
+ */
+ private synchronized void writeObject(java.io.ObjectOutputStream s) throws IOException {
+ if (endpoint != null) {
+ throw new NotSerializableException("cannot serialize");
+ }
+ // Write out the actions. The superclass takes care of the name
+ // call getActions to make sure actions field is initialized
+ if (actions == null)
+ getActions();
+ s.defaultWriteObject();
+ }
+
+ /**
+ * readObject is called to restore the state of this permission from a
+ * stream.
+ */
+ private synchronized void readObject(java.io.ObjectInputStream s) throws IOException, ClassNotFoundException {
+ // Read in the action, then initialize the rest
+ s.defaultReadObject();
+ setTransients(parseFilter(getName()), parseActions(actions));
}
/**
- *Determines if a EndpointPermission object "implies" the specified
- * permission.
+ * Called by <code><@link EndpointPermission#implies(Permission)></code>.
*
- * @param p The target permission to check.
- * @return true if the specified permission is implied by this object; false
- * otherwise. newPermissionCollection()
+ * @return a dictionary of properties for this permission.
*/
- public boolean implies(Permission p) {
- return super.implies(p);
+ private Dictionary/*<String,Object>*/getProperties() {
+ Dictionary/*<String, Object>*/result = properties;
+ if (result != null) {
+ return result;
+ }
+ if (endpoint == null) {
+ result = new Hashtable/*<String, Object>*/(1);
+ if (filter == null) {
+ result.put(Constants.OBJECTCLASS, new String[] {getName()});
+ }
+ return properties = result;
+ }
+ final Map props = new HashMap(4);
+ // TODO needs work
+ /*
+ final Bundle bundle = endpoint.getBundle();
+ if (bundle != null) {
+ AccessController.doPrivileged(new PrivilegedAction() {
+ public Object run() {
+ props.put("id", new Long(bundle.getBundleId()));
+ props.put("location", bundle.getLocation());
+ String name = bundle.getSymbolicName();
+ if (name != null) {
+ props.put("name", name);
+ }
+ SignerProperty signer = new SignerProperty(bundle);
+ if (signer.isBundleSigned()) {
+ props.put("signer", signer);
+ }
+ return null;
+ }
+ });
+ }
+ */
+ return properties = new Properties(props, endpoint);
}
+ private static class Properties extends Dictionary {
+ private final Map properties;
+ private final EndpointDescription service;
+
+ Properties(Map properties, EndpointDescription service) {
+ this.properties = properties;
+ this.service = service;
+ }
+
+ public Object get(Object k) {
+ if (!(k instanceof String)) {
+ return null;
+ }
+ String key = (String)k;
+ if (key.charAt(0) == '@') {
+ return service.getProperties().get(key.substring(1));
+ }
+ Object value = properties.get(key);
+ if (value != null) { // fall back to service properties
+ return value;
+ }
+ return service.getProperties().get(key);
+ }
+
+ public int size() {
+ return properties.size() + service.getProperties().size();
+ }
+
+ public boolean isEmpty() {
+ // we can return false because this must never be empty
+ return false;
+ }
+
+ public Enumeration keys() {
+ Collection pk = properties.keySet();
+ String spk[] =
+ (String[])service.getProperties().keySet().toArray(new String[service.getProperties().size()]);
+ List all = new ArrayList(pk.size() + spk.length);
+ all.addAll(pk);
+ add: for (int i = 0, length = spk.length; i < length; i++) {
+ String key = spk[i];
+ for (Iterator iter = pk.iterator(); iter.hasNext();) {
+ if (key.equalsIgnoreCase((String)iter.next())) {
+ continue add;
+ }
+ }
+ all.add(key);
+ }
+ return Collections.enumeration(all);
+ }
+
+ public Enumeration elements() {
+ Collection pk = properties.keySet();
+ String spk[] =
+ (String[])service.getProperties().keySet().toArray(new String[service.getProperties().size()]);
+ List all = new ArrayList(pk.size() + spk.length);
+ all.addAll(properties.values());
+ add: for (int i = 0, length = spk.length; i < length; i++) {
+ String key = spk[i];
+ for (Iterator iter = pk.iterator(); iter.hasNext();) {
+ if (key.equalsIgnoreCase((String)iter.next())) {
+ continue add;
+ }
+ }
+ all.add(service.getProperties().get(key));
+ }
+ return Collections.enumeration(all);
+ }
+
+ public Object put(Object key, Object value) {
+ throw new UnsupportedOperationException();
+ }
+
+ public Object remove(Object key) {
+ throw new UnsupportedOperationException();
+ }
+ }
+}
+
+/**
+ * Stores a set of EndpointPermission permissions.
+ *
+ * @see java.security.Permission
+ * @see java.security.Permissions
+ * @see java.security.PermissionCollection
+ */
+final class EndpointPermissionCollection extends PermissionCollection {
+ static final long serialVersionUID = 662615640374640621L;
/**
- * Returns a new PermissionCollection object for storing EndpointPermission
- * objects.
+ * Table of permissions.
*
- * @return A new PermissionCollection object suitable for storing
- * EndpointPermission objects.
+ * @GuardedBy this
*/
- public PermissionCollection newPermissionCollection() {
- return super.newPermissionCollection();
+ private transient Map permissions;
+
+ /**
+ * Boolean saying if "*" is in the collection.
+ *
+ * @serial
+ * @GuardedBy this
+ */
+ private boolean all_allowed;
+
+ /**
+ * Table of permissions with filter expressions.
+ *
+ * @serial
+ * @GuardedBy this
+ */
+ private Map filterPermissions;
+
+ /**
+ * Creates an empty EndpointPermissions object.
+ */
+ public EndpointPermissionCollection() {
+ permissions = new HashMap();
+ all_allowed = false;
+ }
+
+ /**
+ * Adds a permission to this permission collection.
+ *
+ * @param permission
+ * The Permission object to add.
+ * @throws IllegalArgumentException
+ * If the specified permission is not a EndpointPermission
+ * object.
+ * @throws SecurityException
+ * If this <code>EndpointPermissionCollection</code> object
+ * has been marked read-only.
+ */
+ public void add(final Permission permission) {
+ if (!(permission instanceof EndpointPermission)) {
+ throw new IllegalArgumentException("invalid permission: " + permission);
+ }
+ if (isReadOnly()) {
+ throw new SecurityException("attempt to add a Permission to a " + "readonly PermissionCollection");
+ }
+
+ final EndpointPermission sp = (EndpointPermission)permission;
+ if (sp.endpoint != null) {
+ throw new IllegalArgumentException("cannot add to collection: " + sp);
+ }
+
+ final String name = sp.getName();
+ final Filter f = sp.filter;
+ synchronized (this) {
+ /* select the bucket for the permission */
+ Map pc;
+ if (f != null) {
+ pc = filterPermissions;
+ if (pc == null) {
+ filterPermissions = pc = new HashMap();
+ }
+ } else {
+ pc = permissions;
+ }
+ final EndpointPermission existing = (EndpointPermission)pc.get(name);
+
+ if (existing != null) {
+ final int oldMask = existing.action_mask;
+ final int newMask = sp.action_mask;
+ if (oldMask != newMask) {
+ pc.put(name, new EndpointPermission(name, oldMask | newMask));
+ }
+ } else {
+ pc.put(name, sp);
+ }
+
+ if (!all_allowed) {
+ if (name.equals("*")) {
+ all_allowed = true;
+ }
+ }
+ }
+ }
+
+ /**
+ * Determines if a set of permissions implies the permissions expressed in
+ * <code>permission</code>.
+ *
+ * @param permission
+ * The Permission object to compare.
+ * @return <code>true</code> if <code>permission</code> is a proper
+ * subset of a permission in the set; <code>false</code>
+ * otherwise.
+ */
+ public boolean implies(final Permission permission) {
+ if (!(permission instanceof EndpointPermission)) {
+ return false;
+ }
+ final EndpointPermission requested = (EndpointPermission)permission;
+ /* if requested permission has a filter, then it is an invalid argument */
+ if (requested.filter != null) {
+ return false;
+ }
+
+ int effective = EndpointPermission.ACTION_NONE;
+ Collection perms;
+ synchronized (this) {
+ final int desired = requested.action_mask;
+ /* short circuit if the "*" Permission was added */
+ if (all_allowed) {
+ EndpointPermission sp = (EndpointPermission)permissions.get("*");
+ if (sp != null) {
+ effective |= sp.action_mask;
+ if ((effective & desired) == desired) {
+ return true;
+ }
+ }
+ }
+
+ String[] requestedNames = requested.objectClass;
+ /* if requested permission not created with EndpointDescription */
+ if (requestedNames == null) {
+ effective |= effective(requested.getName(), desired, effective);
+ if ((effective & desired) == desired) {
+ return true;
+ }
+ }
+ /* requested permission created with EndpointDescription */
+ else {
+ for (int i = 0, l = requestedNames.length; i < l; i++) {
+ if ((effective(requestedNames[i], desired, effective) & desired) == desired) {
+ return true;
+ }
+ }
+ }
+ Map pc = filterPermissions;
+ if (pc == null) {
+ return false;
+ }
+ perms = pc.values();
+ }
+
+ /* iterate one by one over filteredPermissions */
+ for (Iterator iter = perms.iterator(); iter.hasNext();) {
+ if (((EndpointPermission)iter.next()).implies0(requested, effective)) {
+ return true;
+ }
+ }
+ return false;
+ }
+
+ /**
+ * Consult permissions map to compute the effective permission for the
+ * requested permission name.
+ *
+ * @param requestedName
+ * The requested service name.
+ * @param desired
+ * The desired actions.
+ * @param effective
+ * The effective actions.
+ * @return The new effective actions.
+ */
+ private int effective(String requestedName, final int desired, int effective) {
+ final Map pc = permissions;
+ EndpointPermission sp = (EndpointPermission)pc.get(requestedName);
+ // strategy:
+ // Check for full match first. Then work our way up the
+ // name looking for matches on a.b.*
+ if (sp != null) {
+ // we have a direct hit!
+ effective |= sp.action_mask;
+ if ((effective & desired) == desired) {
+ return effective;
+ }
+ }
+ // work our way up the tree...
+ int last;
+ int offset = requestedName.length() - 1;
+ while ((last = requestedName.lastIndexOf(".", offset)) != -1) {
+ requestedName = requestedName.substring(0, last + 1) + "*";
+ sp = (EndpointPermission)pc.get(requestedName);
+ if (sp != null) {
+ effective |= sp.action_mask;
+ if ((effective & desired) == desired) {
+ return effective;
+ }
+ }
+ offset = last - 1;
+ }
+ /*
+ * we don't have to check for "*" as it was already checked before we
+ * were called.
+ */
+ return effective;
+ }
+
+ /**
+ * Returns an enumeration of all the <code>EndpointPermission</code>
+ * objects in the container.
+ *
+ * @return Enumeration of all the EndpointPermission objects.
+ */
+ public synchronized Enumeration elements() {
+ List all = new ArrayList(permissions.values());
+ Map pc = filterPermissions;
+ if (pc != null) {
+ all.addAll(pc.values());
+ }
+ return Collections.enumeration(all);
+ }
+
+ /* serialization logic */
+ private static final ObjectStreamField[] serialPersistentFields =
+ {new ObjectStreamField("permissions", Hashtable.class), new ObjectStreamField("all_allowed", Boolean.TYPE),
+ new ObjectStreamField("filterPermissions", HashMap.class)};
+
+ private synchronized void writeObject(ObjectOutputStream out) throws IOException {
+ Hashtable hashtable = new Hashtable(permissions);
+ ObjectOutputStream.PutField pfields = out.putFields();
+ pfields.put("permissions", hashtable);
+ pfields.put("all_allowed", all_allowed);
+ pfields.put("filterPermissions", filterPermissions);
+ out.writeFields();
+ }
+
+ private synchronized void readObject(java.io.ObjectInputStream in) throws IOException, ClassNotFoundException {
+ ObjectInputStream.GetField gfields = in.readFields();
+ Hashtable hashtable = (Hashtable)gfields.get("permissions", null);
+ permissions = new HashMap(hashtable);
+ all_allowed = gfields.get("all_allowed", false);
+ filterPermissions = (HashMap)gfields.get("filterPermissions", null);
}
}
Modified: tuscany/java/sca/modules/node-impl-osgi/src/main/java/org/apache/tuscany/sca/osgi/service/remoteadmin/ExportRegistration.java
URL: http://svn.apache.org/viewvc/tuscany/java/sca/modules/node-impl-osgi/src/main/java/org/apache/tuscany/sca/osgi/service/remoteadmin/ExportRegistration.java?rev=805623&r1=805622&r2=805623&view=diff
==============================================================================
--- tuscany/java/sca/modules/node-impl-osgi/src/main/java/org/apache/tuscany/sca/osgi/service/remoteadmin/ExportRegistration.java (original)
+++ tuscany/java/sca/modules/node-impl-osgi/src/main/java/org/apache/tuscany/sca/osgi/service/remoteadmin/ExportRegistration.java Tue Aug 18 23:04:29 2009
@@ -1,71 +1,63 @@
-/*
- *
- * Licensed to the Apache Software Foundation (ASF) under one
- * or more contributor license agreements. See the NOTICE file
- * distributed with this work for additional information
- * regarding copyright ownership. The ASF licenses this file
- * to you 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.apache.tuscany.sca.osgi.service.remoteadmin;
-import org.osgi.framework.ServiceReference;
+import org.osgi.framework.*;
/**
- * An Export Registration associates a service to a local endpoint. The Export
- * Registration can be used to delete the endpoint associated with an this
- * registration. It is created with the
- * RemoteAdmin.exportService(ServiceReference) method. When this Export
- * Registration has been unregistered, the methods must all return null.
+ * An Export Registration associates a service to a local endpoint.
+ *
+ * The Export Registration can be used to delete the endpoint associated with an
+ * this registration. It is created with the{@link RemoteAdmin#exportService(ServiceReference)}
+ * method.
+ *
+ * When this Export Registration has been unregistered, the methods must all
+ * return <code>null</code>.
*
* @ThreadSafe
*/
public interface ExportRegistration {
/**
- * Delete the local endpoint and disconnect any remote distribution
- * providers. After this method returns, all the methods must return null.
- * This method has no effect when the endpoint is already destroyed or being
- * destroyed.
+ * Return the service being exported.
+ *
+ * @return The service being exported, must be <code>null</code> when this
+ * registration is unregistered.
+ * @throws IllegalStateException Thrown when this object was not properly initialized, see {@link #getException()}
*/
- public void close();
+ ServiceReference getExportedService() throws IllegalStateException;
/**
- *Return the Endpoint Description that is created for this registration.
+ * Return the Endpoint Description that is created for this registration.
*
* @return the local Endpoint Description
+ * @throws IllegalStateException Thrown when this object was not properly initialized, see {@link #getException()}
*/
- public EndpointDescription getEndpointDescription();
+ EndpointDescription getEndpointDescription();
/**
- * Exception for any error during the import process. If the Remote Admin
- * for some reasons is unable to create a registration, then it must return
- * a Throwable from this method. In this case, all other methods must return
- * on this interface must thrown an Illegal State Exception. If no error
- * occurred, this method must return null. The error must be set before this
- * Import Registration is returned. Asynchronously occurring errors must be
- * reported to the log.
+ * Delete the local endpoint and disconnect any remote distribution
+ * providers. After this method returns, all the methods must return
+ * <code>null</code>.
*
- * @return The exception that occurred during the creation of the
- * registration or null if no exception occurred.
+ * This method has no effect when the endpoint is already destroyed or being
+ * destroyed.
*/
- public Throwable getException();
+ void close();
/**
- * Return the service being exported.
+ * Exception for any error during the import process.
+ *
+ * If the Remote Admin for some reasons is unable to create a registration,
+ * then it must return a <code>Throwable</code> from this method. In this
+ * case, all other methods must return on this interface must thrown an
+ * Illegal State Exception. If no error occurred, this method must return
+ * <code>null</code>.
+ *
+ * The error must be set before this Import Registration is returned.
+ * Asynchronously occurring errors must be reported to the log.
*
- * @return The service being exported, must be null when this registration
- * is unregistered.
+ * future ....
+ *
+ * @return The exception that occurred during the creation of the
+ * registration or <code>null</code> if no exception occurred.
*/
- public ServiceReference getExportedService();
+ Throwable getException();
}
Modified: tuscany/java/sca/modules/node-impl-osgi/src/main/java/org/apache/tuscany/sca/osgi/service/remoteadmin/ImportRegistration.java
URL: http://svn.apache.org/viewvc/tuscany/java/sca/modules/node-impl-osgi/src/main/java/org/apache/tuscany/sca/osgi/service/remoteadmin/ImportRegistration.java?rev=805623&r1=805622&r2=805623&view=diff
==============================================================================
--- tuscany/java/sca/modules/node-impl-osgi/src/main/java/org/apache/tuscany/sca/osgi/service/remoteadmin/ImportRegistration.java (original)
+++ tuscany/java/sca/modules/node-impl-osgi/src/main/java/org/apache/tuscany/sca/osgi/service/remoteadmin/ImportRegistration.java Tue Aug 18 23:04:29 2009
@@ -1,70 +1,58 @@
-/*
- *
- * Licensed to the Apache Software Foundation (ASF) under one
- * or more contributor license agreements. See the NOTICE file
- * distributed with this work for additional information
- * regarding copyright ownership. The ASF licenses this file
- * to you 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.apache.tuscany.sca.osgi.service.remoteadmin;
-import org.osgi.framework.ServiceReference;
+import org.osgi.framework.*;
/**
* An Import Registration associates an active proxy service to a remote
- * endpoint. The Import Registration can be used to delete the proxy associated
- * with an endpoint. It is created with the RemoteAdmin.importService method.
+ * endpoint.
+ *
+ * The Import Registration can be used to delete the proxy associated with an
+ * endpoint. It is created with the{@link RemoteAdmin#importService}
+ * method.
*
* @ThreadSafe
*/
public interface ImportRegistration {
-
/**
- * Unregister this Import Registration. This must close the connection to
- * the end endpoint unregister the proxy. After this method returns, all
- * other methods must return null. This method has no effect when the
- * service is already unregistered or in the process off.
+ * Answer the associated Service Reference for the proxy to the endpoint.
+ *
+ * @return A Service Reference to the proxy for the endpoint.
+ * @throws IllegalStateException Thrown when this object was not properly initialized, see {@link #getException()}
*/
- public void close();
+ ServiceReference getImportedService();
/**
- * Exception for any error during the import process. If the Remote Admin
- * for some reasons is unable to create a registration, then it must return
- * a Throwable from this method. In this case, all other methods must return
- * on this interface must thrown an Illegal State Exception. If no error
- * occurred, this method must return null. The error must be set before this
- * Import Registration is returned. Asynchronously occurring errors must be
- * reported to the log.
+ * Answer the associated remote Endpoint Description.
*
- * @return The exception that occurred during the creation of the
- * registration or null if no exception occurred.
+ * @return A Endpoint Description for the remote endpoint.
+ * @throws IllegalStateException Thrown when this object was not properly initialized, see {@link #getException()}
*/
- public Throwable getException();
+ EndpointDescription getImportedEndpointDescription();
/**
- * Answer the associated remote Endpoint Description.
+ * Unregister this Import Registration. This must close the connection
+ * to the end endpoint unregister the proxy. After this method returns,
+ * all other methods must return null.
*
- * @return A Endpoint Description for the remote endpoint.
+ * This method has no effect when the service is already unregistered or in the process off.
*/
- public EndpointDescription getImportedEndpointDescription();
+ void close();
/**
- * Answer the associated Service Reference for the proxy to the endpoint.
+ * Exception for any error during the import process.
*
- * @return A Service Reference to the proxy for the endpoint.
+ * If the Remote Admin for some reasons is unable to create a registration,
+ * then it must return a <code>Throwable</code> from this method. In this
+ * case, all other methods must return on this interface must thrown an
+ * Illegal State Exception. If no error occurred, this method must return
+ * <code>null</code>.
+ *
+ * The error must be set before this Import Registration is returned.
+ * Asynchronously occurring errors must be reported to the log.
+ *
+ * @return The exception that occurred during the creation of the
+ * registration or <code>null</code> if no exception occurred.
*/
- public ServiceReference getImportedService();
+ Throwable getException();
}