EndpointDescription
Date: 2016-06-25

org.osgi.service.remoteserviceadmin

## Class EndpointDescription

- java.lang.Object
- - org.osgi.service.remoteserviceadmin.EndpointDescription

-     public class EndpointDescription
      extends java.lang.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.

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `EndpointDescription(java.util.Map<java.lang.String,?> properties)` Create an Endpoint Description from a Map.
    `EndpointDescription(org.osgi.framework.ServiceReference<?> reference, java.util.Map<java.lang.String,?> 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(java.lang.Object other)` Compares this `EndpointDescription` object to another object.
    `java.util.List<java.lang.String>` | `getConfigurationTypes()` Returns the configuration types.
    `java.lang.String` | `getFrameworkUUID()` Return the framework UUID for the remote service, if present.
    `java.lang.String` | `getId()` Returns the endpoint's id.
    `java.util.List<java.lang.String>` | `getIntents()` Return the list of intents implemented by this endpoint.
    `java.util.List<java.lang.String>` | `getInterfaces()` Provide the list of interfaces implemented by the exported service.
    `org.osgi.framework.Version` | `getPackageVersion(java.lang.String packageName)` Provide the version of the given package name.
    `java.util.Map<java.lang.String,java.lang.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(java.lang.String filter)` Tests the properties of this `EndpointDescription` against the given filter using a case insensitive match.
    `java.lang.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(java.util.Map<java.lang.String,?> 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:
        `java.lang.IllegalArgumentException` - When the properties are not proper for an Endpoint Description.

    - #### EndpointDescription

          public EndpointDescription(org.osgi.framework.ServiceReference<?> reference,
                             java.util.Map<java.lang.String,?> 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:
        `java.lang.IllegalArgumentException` - When the properties are not proper for an Endpoint Description

  - ### Method Detail

    - #### getId

          public java.lang.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 java.util.List<java.lang.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 org.osgi.framework.Version getPackageVersion(java.lang.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:
        `java.lang.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 java.util.List<java.lang.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 java.util.List<java.lang.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 java.lang.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 java.util.Map<java.lang.String,java.lang.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 `java.lang.Object`
      Returns:
        An integer which is a hash code value for this object.

    - #### equals

          public boolean equals(java.lang.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 `java.lang.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(java.lang.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:
        `java.lang.IllegalArgumentException` - If `filter` contains an invalid filter string that cannot be parsed.

    - #### toString

          public java.lang.String toString()

      Returns the string representation of this EndpointDescription.
      Overrides:
        `toString` in class `java.lang.Object`
      Returns:
        String form of this EndpointDescription.