File-based Discovery

ECF 3.1 makes available a contribution from Siemens, called File-Based Discovery. File-based discovery allows those using the ECF remote services implementation to trigger remote service discovery by publishing endpoints in a service description xml file.

The four pieces of information to describe a remote service with the ECF remote services endpoint are

1. The service interface (i.e. the fully-qualified classname of the service interface class. Example: org.eclipse.ecf.examples.remoteservices.hello.IHello
2. The ECF connect ID (also known as URI of the endpoint). Example (ECF generic provider): ecftcp://localhost:3282/server
3. The connect ID namespace name. Example (ECF generic provider): org.eclipse.ecf.core.identity.StringID.
4. The ECF remote service config type of the remote service host. Example (ECF generic provider): ecf.generic.server

<?xml version="1.0" encoding="UTF-8"?>
  <service-descriptions xmlns="http://www.osgi.org/xmlns/sd/v1.0.0">
    <service-description>
      <provide
interface="org.eclipse.ecf.examples.remoteservices.hello.IHello"/>
      <property
name="ecf.sp.cid">ecftcp://localhost:3787/server</property>
      <property name="ecf.sp.cns">org.eclipse.ecf.core.identity.StringID</property>
      <property name="ecf.sp.ect">ecf.generic.server</property>
   </service-description>
</service-descriptions>

Here, for another example, is a service description file that publishes the same service interface org.eclipse.ecf.examples.remoteservices.hello.IHello with the r-OSGi provider.

<?xml version="1.0" encoding="UTF-8"?>
  <service-descriptions xmlns="http://www.osgi.org/xmlns/sd/v1.0.0">
    <service-description>
      <provide
interface="org.eclipse.ecf.examples.remoteservices.hello.IHello"/>
      <property
name="ecf.sp.cid">r-osgi://localhost</property>
      <property name="ecf.sp.cns">ecf.namespace.r_osgi</property>
      <property name="ecf.sp.ect">ecf.r_osgi.peer</property>
   </service-description>
</service-descriptions>

==Initiating File-Based Discovery==

To read the service description in the xml file, and have it trigger discovery of the given service description the following must occur:

# This bundle: '''org.eclipse.ecf.osgi.services.discovery.local''' must be started
# A file with an xml file name suffix must be in '''either''' a directory named '''OSGI-INF/remote-services''' OR at a path given by the the '''Remote-Service''' header in the META-INF/MANIFEST.MF file.  

For example, the file named servicedescriptions.xml will be read and processed by the file-based discovery when the bundle is started if the servicedescriptions.xml is present in the following location within your bundle.

<pre>
[bundle root]/OSGI-INF/remote-services/servicedescriptions.xml

Or, if the manifest of your bundle has the following in it

...<other manifest headers>
Remote-Service: foo/bar.xml

Then the file bar.xml will be read for service descriptions and used to publish discovered remote services when the containing bundle is started.

As another way to introduce service descriptions into a running Equinox instance, once the org.eclipse.ecf.osgi.services.discovery.local bundle is started, the OSGi console will allow service description xml files to be published via the OSGi console

osgi>help
...other OSGi console help
---Remote Services and Discovery Commands---
publish <URL of ServiceEndpointDescriptor XML> -- publish the given Service Endpoint Descriptor 
unpublish <URL of ServiceEndpointDescriptor XML> -- unpublish the given Service ndpoint Descriptor
osgi> publish file:/c:/temp/myremoteservicedescriptions.xml
<read the myremoteservicedescriptions.xml file and publish given services and connect ids/namespaces.