Using Properties to Import Endpoint Descriptions

OSGi Remote Services can be imported by service consumers via several methods. One method is to have a network-based discovery provider, that uses some communications protocol to publish, discover and import remote services over some network.

Here is the current list of ECF-supported discovery providers

Another method is to have File-Based Remote Services Discovery. The OSGI Remote Services and Remote Service Admin specifications define an xml-formatted document called the the Endpoint Description Extender Format (EDEF).

According to the RSA specification, EDEF files can be provided in the bundle MANIFEST.MF after the 'Remote-Service header, and when this bundle is started, all given EDEF files will be read by ECF RSA implementation, and all endpoint descriptions will be imported. For example, in this manifest...which is part of the ECF Timeservice Example...there is this header:

Remote-Service: timeserviceendpointdescription.xml

In the timeserviceendpointdescription.xml file is the TimeService EDEF. When this bundle is started, the ECF RSA implementation will read and parse this file, and import the given endpoint description as a remote service proxy.

Although EDEF is general, it's not as easy-to-use as it could be under some circumstances. For example, both RSA as specified, and ECF's implementation require that some properties be set, while other properties in the EDEF are optional. It's often a lot to ask that the EDEF creator know the required vs. optional properties.

1. 1. Solution: EDEF Properties Files

ECF has recently introduced a mechanism to make it easier to create and import Endpoint Descriptions in EDEF format. If a properties file of the same name but with extension '.properties' rather than '.xml' is provided all of the properties and their values will be read and the given values replaced or added to the EDEF file.

For example, here is an example project with the Remote-Service header in the manifest.mf:

Remote-Service: edef/studentserviceEDEF.xml

Also, there is the edef/studentserviceEDEF.xml

<?xml version="1.0" encoding="UTF-8"?>
<endpoint-descriptions xmlns="http://www.osgi.org/xmlns/rsa/v1.0.0">
  <endpoint-description>
    <property name="ecf.endpoint.id.ns" value-type="String" value="ecf.namespace.jaxrs"/>
    <property name="ecf.rsvc.id" value-type="Long" value="1"/>
    <property name="endpoint.framework.uuid" value-type="String" value="f838e874-d17d-4328-806e-a9cd869b3f35"/>
    <property name="endpoint.id" value-type="String" value="fabcb5ab-6937-4f31-9f97-c10bb9660bb8"/>
    <property name="endpoint.package.version.com.mycorp.examples.student" value-type="String" value="1.0.0"/>
    <property name="endpoint.service.id" value-type="Long" value="94"/>
    <property name="objectClass" value-type="String">
      <array>
        <value>com.mycorp.examples.student.StudentService</value>
      </array>
    </property>
    <property name="osgi.basic.timeout" value-type="String" value="5000000"/>
    <property name="remote.configs.supported" value-type="String">
      <array>
        <value>ecf.jaxrs.jersey.server</value>
      </array>
    </property>
    <property name="remote.intents.supported" value-type="String">
      <array>
        <value>passByValue</value>
        <value>exactlyOnce</value>
        <value>ordered</value>
        <value>osgi.async</value>
        <value>osgi.private</value>
        <value>osgi.confidential</value>
        <value>jaxrs</value>
      </array>
    </property>
    <property name="service.imported" value-type="String" value="true"/>
    <property name="service.imported.configs" value-type="String">
      <array>
        <value>ecf.jaxrs.jersey.server</value>
      </array>
    </property>
    <property name="service.intents" value-type="String">
      <array>
        <value>osgi.async</value>
        <value>jaxrs</value>
      </array>
    </property>
  </endpoint-description>
</endpoint-descriptions>

and the https://github.com/ECF/JaxRSProviders/blob/master/examples/com.mycorp.examples.student.client.filediscovery/edef/studentserviceEDEF.properties studentserviceEDEF.properties file] with content

ecf.endpoint.id=http://localhost:8080/rservices/rs1

in the same /edef/ directory location as the xml file.

When this bundle is started, ECF's RSA impl will read the studentServiceEDEF.xml file, parse it, and then read and substitute the all name=value pairs in the studentserviceEDEF.properties file into the EndpointDescription used to import the remote service. As many properties as desired may be put into the properties file, and all such properties will all be either added (if not already present in parsed EDEF) or values replaced (if already present in parsed EDEF). For example, if the studentserviceEDEF.properties files had these properties:

ecf.endpoint.id=http://localhost:8080/rservices/rs1
endpoint.id=myendpointid
endpoint.framework.uuid=ffffffff-dddd-4444-8888-aaaaaaaaa

Then the resulting EndpointDescription would be:

<?xml version="1.0" encoding="UTF-8"?>
<endpoint-descriptions xmlns="http://www.osgi.org/xmlns/rsa/v1.0.0">
  <endpoint-description>
    <property name="ecf.endpoint.id" value-type="String" value="http://localhost:8080/rservices/rs1"/>
    <property name="ecf.endpoint.id.ns" value-type="String" value="ecf.namespace.jaxrs"/>
    <property name="ecf.rsvc.id" value-type="Long" value="1"/>
    <property name="endpoint.framework.uuid" value-type="String" value="ffffffff-dddd-4444-8888-aaaaaaaaa"/>
    <property name="endpoint.id" value-type="String" value="myendpointid"/>
    <property name="endpoint.package.version.com.mycorp.examples.student" value-type="String" value="1.0.0"/>
    <property name="endpoint.service.id" value-type="Long" value="94"/>
    <property name="objectClass" value-type="String">
      <array>
        <value>com.mycorp.examples.student.StudentService</value>
      </array>
    </property>
    <property name="osgi.basic.timeout" value-type="String" value="5000000"/>
    <property name="remote.configs.supported" value-type="String">
      <array>
        <value>ecf.jaxrs.jersey.server</value>
      </array>
    </property>
    <property name="remote.intents.supported" value-type="String">
      <array>
        <value>passByValue</value>
        <value>exactlyOnce</value>
        <value>ordered</value>
        <value>osgi.async</value>
        <value>osgi.private</value>
        <value>osgi.confidential</value>
        <value>jaxrs</value>
      </array>
    </property>
    <property name="service.imported" value-type="String" value="true"/>
    <property name="service.imported.configs" value-type="String">
      <array>
        <value>ecf.jaxrs.jersey.server</value>
      </array>
    </property>
    <property name="service.intents" value-type="String">
      <array>
        <value>osgi.async</value>
        <value>jaxrs</value>
      </array>
    </property>
  </endpoint-description>
</endpoint-descriptions>

• • EDEF Templates

The properties mechanism allows EDEF files to be used as templates, with any/all property values that are required for importing a given remote service automatically substituted into the EDEF before remote service import.