Update to the latest OSGi remoteserviceadmin apis

git-svn-id: http://svn.us.apache.org/repos/asf/tuscany@885958 13f79535-47bb-0310-9956-ffa450edef68

1 files changed, 144 insertions, 76 deletions

diff --git a/sca-java-2.x/trunk/modules/node-impl-osgi/src/main/java/org/apache/tuscany/sca/osgi/remoteserviceadmin/EndpointDescription.java b/sca-java-2.x/trunk/modules/node-impl-osgi/src/main/java/org/osgi/service/remoteserviceadmin/EndpointDescription.java
index 9fda882738..c83a79337f 100644
--- a/sca-java-2.x/trunk/modules/node-impl-osgi/src/main/java/org/apache/tuscany/sca/osgi/remoteserviceadmin/EndpointDescription.java
+++ b/sca-java-2.x/trunk/modules/node-impl-osgi/src/main/java/org/osgi/service/remoteserviceadmin/EndpointDescription.java
@@ -13,7 +13,15 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-package org.apache.tuscany.sca.osgi.remoteserviceadmin;
+
+package org.osgi.service.remoteserviceadmin;
+
+import static org.osgi.service.remoteserviceadmin.RemoteConstants.ENDPOINT_FRAMEWORK_UUID;
+import static org.osgi.service.remoteserviceadmin.RemoteConstants.ENDPOINT_ID;
+import static org.osgi.service.remoteserviceadmin.RemoteConstants.ENDPOINT_INTERACE_VERSION_;
+import static org.osgi.service.remoteserviceadmin.RemoteConstants.ENDPOINT_URI;
+import static org.osgi.service.remoteserviceadmin.RemoteConstants.SERVICE_IMPORTED_CONFIGS;
+import static org.osgi.service.remoteserviceadmin.RemoteConstants.SERVICE_INTENTS;
 
 import java.util.ArrayList;
 import java.util.Arrays;
@@ -55,11 +63,11 @@ import org.osgi.framework.Version;
  */
 
 public class EndpointDescription {
-    private final Map<String, Object> properties;
-    private final List<String> interfaces;
-    private final long remoteServiceId;
-    private final String remoteFrameworkUUID;
-    private final String remoteUri;
+    private final Map<String, Object>   properties;
+    private final List<String>          interfaces;
+    private final long                  remoteServiceId;
+    private final String                remoteFrameworkUUID;
+    private final String                remoteUri;
 
     /**
      * Create an Endpoint Description based on a Map.
@@ -71,6 +79,9 @@ public class EndpointDescription {
 
     public EndpointDescription(Map<String, Object> properties) {
         this(properties, null);
+        if (properties == null) {
+            throw new NullPointerException("properties must not be null");
+        }
     }
 
     /**
@@ -83,26 +94,32 @@ public class EndpointDescription {
      * @throws IllegalArgumentException When the properties are not proper for
      *         an Endpoint Description
      */
-    public EndpointDescription(ServiceReference reference, Map<String, Object> properties) {
+    public EndpointDescription(ServiceReference reference,
+            Map<String, Object> properties) {
         this(properties, reference);
         if (reference == null) {
             throw new NullPointerException("reference must not be null");
         }
     }
 
-    private EndpointDescription(Map<String, Object> map, ServiceReference reference) {
-        Map<String, Object> props = new TreeMap<String, Object>(String.CASE_INSENSITIVE_ORDER);
+    private EndpointDescription(Map<String, Object> map,
+            ServiceReference reference) {
+        Map<String, Object> props = new TreeMap<String, Object>(
+                String.CASE_INSENSITIVE_ORDER);
 
         if (map != null) {
             try {
                 props.putAll(map);
-            } catch (ClassCastException e) {
-                IllegalArgumentException iae = new IllegalArgumentException("non-String key in properties");
+            }
+            catch (ClassCastException e) {
+                IllegalArgumentException iae = new IllegalArgumentException(
+                        "non-String key in properties");
                 iae.initCause(e);
                 throw iae;
             }
             if (props.size() < map.size()) {
-                throw new IllegalArgumentException("duplicate keys with different cases in properties");
+                throw new IllegalArgumentException(
+                        "duplicate keys with different cases in properties");
             }
         }
 
@@ -116,10 +133,10 @@ public class EndpointDescription {
 
         properties = Collections.unmodifiableMap(props);
         /* properties must be initialized before calling the following methods */
-        interfaces = verifyInterfacesProperty();
-        remoteServiceId = verifyLongProperty(RemoteConstants.SERVICE_REMOTE_ID);
-        remoteFrameworkUUID = verifyStringProperty(RemoteConstants.SERVICE_REMOTE_FRAMEWORK_UUID);
-        remoteUri = verifyStringProperty(RemoteConstants.SERVICE_REMOTE_URI);
+        interfaces = verifyObjectClassProperty();
+        remoteServiceId = verifyLongProperty(ENDPOINT_ID);
+        remoteFrameworkUUID = verifyStringProperty(ENDPOINT_FRAMEWORK_UUID);
+        remoteUri = verifyStringProperty(ENDPOINT_URI);
     }
 
     /**
@@ -130,20 +147,23 @@ public class EndpointDescription {
      *         right values for and interface list.
      * 
      */
-    private List<String> verifyInterfacesProperty() {
+    private List<String> verifyObjectClassProperty() {
         Object o = properties.get(Constants.OBJECTCLASS);
         if (o == null) {
             return Collections.EMPTY_LIST;
         }
         if (!(o instanceof String[])) {
-            throw new IllegalArgumentException("objectClass must be a String[]");
+            throw new IllegalArgumentException(
+                    "objectClass must be of type String[]");
         }
-        String[] objectClass = (String[])o;
+        String[] objectClass = (String[]) o;
         for (String interf : objectClass) {
             try {
                 getInterfaceVersion(interf);
-            } catch (IllegalArgumentException e) {
-                IllegalArgumentException iae = new IllegalArgumentException("Improper version for interface " + interf);
+            }
+            catch (IllegalArgumentException e) {
+                IllegalArgumentException iae = new IllegalArgumentException(
+                        "Improper version for interface " + interf);
                 iae.initCause(e);
                 throw iae;
             }
@@ -162,12 +182,14 @@ public class EndpointDescription {
     private String verifyStringProperty(String propName) {
         Object r = properties.get(propName);
         if (r == null) {
-            throw new IllegalArgumentException("Required property not set: " + propName);
+            throw new IllegalArgumentException("Required property not set: "
+                    + propName);
         }
         if (!(r instanceof String)) {
-            throw new IllegalArgumentException("Required property is not a String: " + propName);
+            throw new IllegalArgumentException(
+                    "Required property is not a String: " + propName);
         }
-        return (String)r;
+        return (String) r;
     }
 
     /**
@@ -181,16 +203,19 @@ public class EndpointDescription {
     private long verifyLongProperty(String propName) {
         Object r = properties.get(propName);
         if (r == null) {
-            throw new IllegalArgumentException("Required property not set: " + propName);
+            throw new IllegalArgumentException("Required property not set: "
+                    + propName);
         }
         if (!(r instanceof String)) {
-            throw new IllegalArgumentException("Required property is not a string: " + propName);
+            throw new IllegalArgumentException(
+                    "Required property is not a string: " + propName);
         }
         try {
-            return Long.parseLong((String)r);
-        } catch (NumberFormatException e) {
-            IllegalArgumentException iae =
-                new IllegalArgumentException("Required property cannot be parsed as a long: " + propName);
+            return Long.parseLong((String) r);
+        }
+        catch (NumberFormatException e) {
+            IllegalArgumentException iae = new IllegalArgumentException(
+                    "Required property cannot be parsed as a long: " + propName);
             iae.initCause(e);
             throw iae;
         }
@@ -204,7 +229,7 @@ public class EndpointDescription {
      * URI must represent the same endpoint.
      * 
      * The value of the URI is stored in the
-     * {@link RemoteConstants#SERVICE_REMOTE_URI} property.
+     * {@link RemoteConstants#ENDPOINT_URI} property.
      * 
      * @return The URI of the endpoint, never <code>null</code>.
      */
@@ -232,23 +257,35 @@ public class EndpointDescription {
      * Provide 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.
-     * For example:
+     * <code>endpoint.interface.version.</code>, and then using this as an
+     * endpoint property key. For example:
      * 
      * <pre>
-     * endpoint.version.com.acme.Foo
+     * endpoint.interface.version.com.acme.Foo
      * </pre>
      * 
      * The value of this property is in String format and will be converted to a
      * <code>Version</code> object by this method.
      * 
-     * @param name The name of the interface for which a version is requested
+     * @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
+     *         interface has no version in this Endpoint Description.
+     * @throws IllegalArgumentException If the version property value is not
+     *         String.
      */
     public Version getInterfaceVersion(String name) {
-        String version = (String)properties.get("endpoint.version." + name);
-        return Version.parseVersion(version);
+        String key = ENDPOINT_INTERACE_VERSION_ + name;
+        Object version = properties.get(key);
+        // [rfeng] Check for existence of the property
+        if (version == null) {
+            return null;
+        }
+        // [rfeng]
+        if (!(version instanceof String)) {
+            throw new IllegalArgumentException(key
+                    + " property is not a String");
+        }
+        return Version.parseVersion((String) version);
     }
 
     /**
@@ -258,6 +295,9 @@ public class EndpointDescription {
      * service. This field together with the Framework UUID is a globally unique
      * id for a service.
      * 
+     * The value of the remote service id is stored in the
+     * {@link RemoteConstants#ENDPOINT_ID} endpoint property.
+     * 
      * @return Service id of a service or 0 if this Endpoint Description does
      *         not relate to an OSGi service
      * 
@@ -277,14 +317,14 @@ public class EndpointDescription {
      * 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}
+     * This value of the configuration types is stored in the
+     * {@link RemoteConstants#SERVICE_IMPORTED_CONFIGS} service property.
      * 
      * @return An unmodifiable list of the configuration types used for the
      *         associated endpoint and optionally synonyms.
      */
     public List<String> getConfigurationTypes() {
-        return getStringPlusProperty(RemoteConstants.SERVICE_IMPORTED_CONFIGS);
+        return getStringPlusProperty(SERVICE_IMPORTED_CONFIGS);
     }
 
     /**
@@ -294,14 +334,14 @@ public class EndpointDescription {
      * 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}
+     * This value of the intents is stored in the
+     * {@link RemoteConstants#SERVICE_INTENTS} service property.
      * 
      * @return An unmodifiable list of expanded intents that are provided by
      *         this endpoint.
      */
     public List<String> getIntents() {
-        return getStringPlusProperty(RemoteConstants.SERVICE_INTENTS);
+        return getStringPlusProperty(SERVICE_INTENTS);
     }
 
     /**
@@ -311,7 +351,6 @@ public class EndpointDescription {
      * 
      * @param key The property
      * @return An unmodifiable list
-     * @throws Illegal
      */
     private List<String> getStringPlusProperty(String key) {
         Object value = properties.get(key);
@@ -320,30 +359,30 @@ public class EndpointDescription {
         }
 
         if (value instanceof String) {
-            return Collections.singletonList((String)value);
+            return Collections.singletonList((String) value);
         }
 
         if (value instanceof String[]) {
-            String[] values = (String[])value;
+            String[] values = (String[]) value;
             List<String> result = new ArrayList<String>(values.length);
             for (String v : values) {
                 if (v != null) {
                     result.add(v);
                 }
             }
-            return result;
+            return Collections.unmodifiableList(result);
         }
 
-        if (value instanceof Collection<?>) {
-            Collection<?> values = (Collection<?>)value;
+        if (value instanceof Collection< ? >) {
+            Collection< ? > values = (Collection< ? >) value;
             List<String> result = new ArrayList<String>(values.size());
-            for (Iterator<?> iter = values.iterator(); iter.hasNext();) {
+            for (Iterator< ? > iter = values.iterator(); iter.hasNext();) {
                 Object v = iter.next();
                 if ((v != null) && (v instanceof String)) {
-                    result.add((String)v);
+                    result.add((String) v);
                 }
             }
-            return result;
+            return Collections.unmodifiableList(result);
         }
 
         return Collections.EMPTY_LIST;
@@ -352,8 +391,8 @@ public class EndpointDescription {
     /**
      * Return the framework UUID for the remote service, if present.
      * 
-     * The property the framework UUID comes from is
-     * {@link RemoteConstants#SERVICE_REMOTE_FRAMEWORK_UUID}
+     * The value of the remote framework uuid is stored in the
+     * {@link RemoteConstants#ENDPOINT_FRAMEWORK_UUID} endpoint property.
      * 
      * @return Remote Framework UUID, or null if this endpoint is not associated
      *         with an OSGi service
@@ -384,29 +423,39 @@ public class EndpointDescription {
      *         the other
      */
     public boolean isSameService(EndpointDescription other) {
-        if (remoteUri.equals(other.remoteUri))
+        if (this.equals(other)) {
             return true;
+        }
 
-        if (remoteFrameworkUUID == null)
+        if (getRemoteFrameworkUUID() == null) {
             return false;
+        }
 
-        return remoteServiceId == other.remoteServiceId && remoteFrameworkUUID.equals(other.remoteFrameworkUUID);
+        return (this.getRemoteServiceID() == other.getRemoteServiceID())
+                && this.getRemoteFrameworkUUID().equals(
+                        other.getRemoteFrameworkUUID());
     }
 
     /**
-     * Two endpoints are equal if their URIs are equal, the hash code is
-     * therefore derived from the URI.
+     * Returns a hash code value for the object.
      * 
-     * @return The hashcode of this endpoint.
+     * @return An integer which is a hash code value for this object.
      */
     public int hashCode() {
         return getRemoteURI().hashCode();
     }
 
     /**
-     * Two endpoints are equal if their URIs are equal.
+     * Compares this <code>EndpointDescription</code> object to another object.
+     * 
+     * <p>
+     * An Endpoint Description is considered to be <b>equal to</b> another
+     * Endpoint Description if their URIs are equal.
      * 
-     * @return
+     * @param other The <code>EndpointDescription</code> object to be compared.
+     * @return <code>true</code> if <code>object</code> is a
+     *         <code>EndpointDescription</code> and is equal to this object;
+     *         <code>false</code> otherwise.
      */
     public boolean equals(Object other) {
         if (this == other) {
@@ -415,19 +464,38 @@ public class EndpointDescription {
         if (!(other instanceof EndpointDescription)) {
             return false;
         }
-        return getRemoteURI().equals(((EndpointDescription)other).getRemoteURI());
+        return getRemoteURI().equals(
+                ((EndpointDescription) other).getRemoteURI());
     }
 
     /**
-     * TODO
-     * 
-     * @param filter
-     * @return
-     * @throws InvalidSyntaxException
+     * Tests the properties of this <code>EndpointDescription</code> against the
+     * given filter using a case insensitive match.
+     * 
+     * @param filter The filter to test.
+     * @return <code>true</code> If the properties of this
+     *         <code>EndpointDescription</code> match the filter,
+     *         <code>false</code> otherwise.
+     * @throws IllegalArgumentException If <code>filter</code> contains an
+     *         invalid filter string that cannot be parsed.
      */
-    public boolean match(String filter) throws InvalidSyntaxException {
-        Filter f = FrameworkUtil.createFilter(filter);
-        Dictionary<String, Object> d = new UnmodifiableDictionary<String, Object>(properties);
+    public boolean matches(String filter) {
+        Filter f;
+        try {
+            f = FrameworkUtil.createFilter(filter);
+        }
+        catch (InvalidSyntaxException e) {
+            IllegalArgumentException iae = new IllegalArgumentException(e
+                    .getMessage());
+            iae.initCause(e);
+            throw iae;
+        }
+        Dictionary<String, Object> d = new UnmodifiableDictionary<String, Object>(
+                properties);
+        /*
+         * we can use matchCase here since properties already supports case
+         * insensitive key lookup.
+         */
         return f.matchCase(d);
     }
 
@@ -435,14 +503,14 @@ public class EndpointDescription {
      * Unmodifiable wrapper for Dictionary.
      */
     private static class UnmodifiableDictionary<K, V> extends Dictionary<K, V> {
-        private final Map<? extends K, ? extends V> wrapped;
+        private final Map<K, V> wrapped;
 
-        UnmodifiableDictionary(Map<? extends K, ? extends V> wrapped) {
+        UnmodifiableDictionary(Map<K, V> wrapped) {
             this.wrapped = wrapped;
         }
 
         public Enumeration<V> elements() {
-            return (Enumeration<V>)Collections.enumeration(wrapped.values());
+            return Collections.enumeration(wrapped.values());
         }
 
         public V get(Object key) {
@@ -454,7 +522,7 @@ public class EndpointDescription {
         }
 
         public Enumeration<K> keys() {
-            return (Enumeration<K>)Collections.enumeration(wrapped.keySet());
+            return Collections.enumeration(wrapped.keySet());
         }
 
         public V put(K key, V value) {