Difference between revisions of "Using Properties to Import Endpoint Descriptions"

Revision as of 01:43, 8 December 2020

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.

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.

@@ Line 10: / Line 10: @@
 Remote-Service: timeserviceendpointdescription.xml
 </pre>
 In the [https://git.eclipse.org/c/ecf/org.eclipse.ecf.git/tree/examples/bundles/com.mycorp.examples.timeservice.consumer.filediscovery/timeserviceendpointdescription.xml 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.
@@ Line 15: / Line 16: @@
 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.
-== EDEF Properties Files
+== 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.
@@ Line 24: / Line 25: @@
 Remote-Service: edef/studentserviceEDEF.xml
 </pre>
 Also, there is the [https://github.com/ECF/JaxRSProviders/blob/master/examples/com.mycorp.examples.student.client.filediscovery/edef/studentserviceEDEF.xml edef/studentserviceEDEF.xml]
@@ Line 74: / Line 76: @@
 </endpoint-descriptions>
 </source>
 and the https://github.com/ECF/JaxRSProviders/blob/master/examples/com.mycorp.examples.student.client.filediscovery/edef/studentserviceEDEF.properties studentserviceEDEF.properties file] with content
@@ Line 80: / Line 83: @@
 ecf.endpoint.id=http://localhost:8080/rservices/rs1
 </pre>
 in the same [https://github.com/ECF/JaxRSProviders/blob/master/examples/com.mycorp.examples.student.client.filediscovery/edef /edef/ directory location] as the xml file.
@@ Line 90: / Line 94: @@
 endpoint.framework.uuid=ffffffff-dddd-4444-8888-aaaaaaaaa
 </pre>
 Then the resulting EndpointDescription would be:
@@ Line 142: / Line 147: @@
 </source>
-== EDEF Templates
+== 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.

Breadcrumbs

Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Difference between revisions of "Using Properties to Import Endpoint Descriptions"

Revision as of 01:43, 8 December 2020

EDEF Properties Files

EDEF Templates