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"
Line 151: | Line 151: | ||
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. | 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. | ||
+ | |||
+ | == EDEF Property Profiles == | ||
+ | |||
+ | Endpoint definitions often need to vary based on some runtime configuration. For example, you may have a different endpoint URL for various environments. | ||
+ | |||
+ | <pre> | ||
+ | Development environment - http://dev.myserver.com/rservices/rs1 | ||
+ | Test environment - http://test.myserver.com/rservices/rs1 | ||
+ | Production environment - http://prod.myserver.com/rservices/rs1 | ||
+ | </pre> | ||
+ | |||
+ | ECF Remote Services endpoints now support this type of configuration using a profile name and matching properties files. The profile name itself is specified as a command line argument: | ||
+ | |||
+ | <pre> | ||
+ | -Dorg.eclipse.ecf.osgi.services.remoteserviceadmin.EndpointDescriptionLocator.localPropertiesProfile=dev | ||
+ | </pre> | ||
+ | |||
+ | The framework will attempt to locate a properties file (again, in the same directory as the EDEF XML file) that has the profile name attached to the base file name: basename-{profile}.properties. | ||
+ | |||
+ | Given this argument set to ''dev'', the framework will be looking for a matching properties file named: | ||
+ | |||
+ | <pre>studentserviceEDEF-dev.properties.</pre> | ||
== EDEF Properties for Importing JaxRS Remote Services into an Eclipse RCP Application == | == EDEF Properties for Importing JaxRS Remote Services into an Eclipse RCP Application == | ||
Patrick Paulin has blogged about using EDEF properties for [https://modumind.com/2020/11/05/ecf-and-rest-improved-support-for-properties-and-profiles/ importing JaxRS Remote Services into an Eclipse RCP Application]. | Patrick Paulin has blogged about using EDEF properties for [https://modumind.com/2020/11/05/ecf-and-rest-improved-support-for-properties-and-profiles/ importing JaxRS Remote Services into an Eclipse RCP Application]. |
Revision as of 16:50, 13 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.
Contents
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.
EDEF Property Profiles
Endpoint definitions often need to vary based on some runtime configuration. For example, you may have a different endpoint URL for various environments.
Development environment - http://dev.myserver.com/rservices/rs1 Test environment - http://test.myserver.com/rservices/rs1 Production environment - http://prod.myserver.com/rservices/rs1
ECF Remote Services endpoints now support this type of configuration using a profile name and matching properties files. The profile name itself is specified as a command line argument:
-Dorg.eclipse.ecf.osgi.services.remoteserviceadmin.EndpointDescriptionLocator.localPropertiesProfile=dev
The framework will attempt to locate a properties file (again, in the same directory as the EDEF XML file) that has the profile name attached to the base file name: basename-{profile}.properties.
Given this argument set to dev, the framework will be looking for a matching properties file named:
studentserviceEDEF-dev.properties.
EDEF Properties for Importing JaxRS Remote Services into an Eclipse RCP Application
Patrick Paulin has blogged about using EDEF properties for importing JaxRS Remote Services into an Eclipse RCP Application.