org.osgi.service.remoteserviceadmin

Class EndpointDescription

java.lang.Object

org.osgi.service.remoteserviceadmin.EndpointDescription

public class EndpointDescription
extends Object

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 because it is property based where the property keys are strings and the values are simple types. 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. Therefore the map must not contain any service.exported.* property and must contain the corresponding service.imported.* ones. The service.intents property must contain the intents provided by the service itself combined with the intents added by the exporting distribution provider. Qualified intents appear fully expanded on this property.

Version:

$Revision$

Constructor Summary

Constructors

Constructor and Description
EndpointDescription(Map<String,Object> properties) Create an Endpoint Description from a Map.
EndpointDescription(ServiceReference reference, Map<String,Object> properties) Create an Endpoint Description based on a Service Reference and a Map of properties.

Method Summary

Methods

Modifier and Type	Method and Description
boolean	equals(Object other) Compares this EndpointDescription object to another object.
List<String>	getConfigurationTypes() Returns the configuration types.
String	getFrameworkUUID() Return the framework UUID for the remote service, if present.
String	getId() Returns the endpoint's id.
List<String>	getIntents() Return the list of intents implemented by this endpoint.
List<String>	getInterfaces() Provide the list of interfaces implemented by the exported service.
Version	getPackageVersion(String packageName) Provide the version of the given package name.
Map<String,Object>	getProperties() Returns all endpoint properties.
long	getServiceId() Returns the service id for the service exported through this endpoint.
int	hashCode() Returns a hash code value for the object.
boolean	isSameService(EndpointDescription other) Answers if this Endpoint Description refers to the same service instance as the given Endpoint Description.
boolean	matches(String filter) Tests the properties of this EndpointDescription against the given filter using a case insensitive match.
String	toString() Returns the string representation of this EndpointDescription.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

EndpointDescription

public EndpointDescription(Map<String,Object> properties)

Create an Endpoint Description from a Map.

The endpoint.id, service.imported.configs and objectClass properties must be set.

Parameters:

properties - The map from which to create the Endpoint Description. The keys in the map must be type String and, since the keys are case insensitive, there must be no duplicates with case variation.

Throws:

IllegalArgumentException - When the properties are not proper for an Endpoint Description.

EndpointDescription

public EndpointDescription(ServiceReference reference,
                   Map<String,Object> properties)

Create an Endpoint Description based on a Service Reference and a Map of properties. The properties in the map take precedence over the properties in the Service Reference.

This method will automatically set the endpoint.framework.uuid and endpoint.service.id properties based on the specified Service Reference as well as the service.imported property if they are not specified as properties.

The endpoint.id, service.imported.configs and objectClass properties must be set.

Parameters:

reference - A service reference that can be exported.

properties - Map of properties. This argument can be null. The keys in the map must be type String and, since the keys are case insensitive, there must be no duplicates with case variation.

Throws:

IllegalArgumentException - When the properties are not proper for an Endpoint Description

Method Detail

getId

public String getId()

Returns the endpoint's id. The id is an opaque id for an endpoint. No two different endpoints must have the same id. Two Endpoint Descriptions with the same id must represent the same endpoint. The value of the id is stored in the RemoteConstants.ENDPOINT_ID property.

Returns:

The id of the endpoint, never null. The returned value has leading and trailing whitespace removed.

getInterfaces

public List<String> getInterfaces()

Provide the list of interfaces implemented by the exported service. The value of the interfaces is derived from the objectClass property.

Returns:

An unmodifiable list of Java interface names implemented by this endpoint.

getPackageVersion

public Version getPackageVersion(String packageName)

Provide the version of the given package name. The version is encoded by prefixing the given package name with endpoint.package.version., and then using this as an endpoint property key. For example:

 endpoint.package.version.com.acme
 

The value of this property is in String format and will be converted to a Version object by this method.

Parameters:

packageName - The name of the package for which a version is requested.

Returns:

The version of the specified package or Version.emptyVersion if the package has no version in this Endpoint Description.

Throws:

IllegalArgumentException - If the version property value is not String.

getServiceId

public long getServiceId()

Returns the service id for the service exported through this endpoint. This is the service id under which the framework has registered the 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 RemoteConstants.ENDPOINT_SERVICE_ID endpoint property.

Returns:

Service id of a service or 0 if this Endpoint Description does not relate to an OSGi service.

getConfigurationTypes

public List<String> getConfigurationTypes()

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 distribution provider can create a connection to this endpoint. This value of the configuration types is stored in the RemoteConstants.SERVICE_IMPORTED_CONFIGS service property.

Returns:

An unmodifiable list of the configuration types used for the associated endpoint and optionally synonyms.

getIntents

public List<String> getIntents()

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. This value of the intents is stored in the RemoteConstants.SERVICE_INTENTS service property.

Returns:

An unmodifiable list of expanded intents that are provided by this endpoint.

getFrameworkUUID

public String getFrameworkUUID()

Return the framework UUID for the remote service, if present. The value of the remote framework uuid is stored in the RemoteConstants.ENDPOINT_FRAMEWORK_UUID endpoint property.

Returns:

Remote Framework UUID, or null if this endpoint is not associated with an OSGi framework having a framework uuid.

getProperties

public Map<String,Object> getProperties()

Returns all endpoint properties.

Returns:

An unmodifiable map referring to the properties of this Endpoint Description.

isSameService

public boolean isSameService(EndpointDescription other)

Answers if this Endpoint Description refers to the same service instance as the given Endpoint Description. Two Endpoint Descriptions point to the same service if they have the same id or their framework UUIDs and remote service ids are equal.

Parameters:

other - The Endpoint Description to look at

Returns:

True if this endpoint description points to the same service as the other

hashCode

public int hashCode()

Returns a hash code value for the object.

Overrides:

hashCode in class Object

Returns:

An integer which is a hash code value for this object.

equals

public boolean equals(Object other)

Compares this EndpointDescription object to another object.

An Endpoint Description is considered to be equal to another Endpoint Description if their ids are equal.

Overrides:

equals in class Object

Parameters:

other - The EndpointDescription object to be compared.

Returns:

true if object is a EndpointDescription and is equal to this object; false otherwise.

matches

public boolean matches(String filter)

Tests the properties of this EndpointDescription against the given filter using a case insensitive match.

Parameters:

filter - The filter to test.

Returns:

true If the properties of this EndpointDescription match the filter, false otherwise.

Throws:

IllegalArgumentException - If filter contains an invalid filter string that cannot be parsed.

toString

public String toString()

Returns the string representation of this EndpointDescription.

Overrides:

toString in class Object

Returns:

String form of this EndpointDescription.