RSA Console Commands

In version 3.14.0, ECF has introduced a number of Gogo console commands for monitoring and controlling Remote Services by using the OSGi Remote Service Admin (RSA) service. RSA is specified by chapter 122 of the OSGi Compendium specification, and provides the means to examine, export (make available to remote processes) and import (use/consume) remote services.

Gogo Command Scope - The gogo command scope for the following commands is ecf

Toggling RSA Debug Output

By default, RSA output (remote service export registrations, import registrations, unexport registrations, and unimport registrations, along with the associated Endpoint Description (EDEF) are output to the console. To turn the rsa debug output on/off:

Command: rsadebug

Example

osgi> rsadebug
RSA debugging OFF
osgi> rsadebug
RSA debugging ON

Listing Exports

Command: listexports | lexps

Argument:

   endpoint.id -  Optional.  If present, details are presented about the endpoint with the given endpoint.id.  If endpoint.id argument not present, a table is presented with endpoint.id, Exporting Container ID, and Exported Service Id.

Example

osgi> listexports
endpoint.id                          |Exporting Container ID                       |Exported Service Id
58176215-e890-4107-aa8b-1055510186da |ecftcp://localhost:3288/server               |83

osgi> lexps 58176215-e890-4107-aa8b-1055510186da
<endpoint-descriptions xmlns="http://www.osgi.org/xmlns/rsa/v1.0.0">
  <endpoint-description>
    <property name="ecf.endpoint.id" value-type="String" value="ecftcp://localhost:3288/server"/>
    <property name="ecf.endpoint.id.ns" value-type="String" value="org.eclipse.ecf.core.identity.StringID"/>
    <property name="ecf.endpoint.ts" value-type="Long" value="1520450143497"/>
    <property name="ecf.exported.async.interfaces" value-type="String" value="*"/>
    <property name="ecf.generic.server.hostname" value-type="String" value="localhost"/>
    <property name="ecf.generic.server.port" value-type="String" value="3288"/>
    <property name="ecf.rsvc.id" value-type="Long" value="1"/>
    <property name="endpoint.framework.uuid" value-type="String" value="74747fb9-e9db-4b29-8e4c-882b68a2b03b"/>
    <property name="endpoint.id" value-type="String" value="58176215-e890-4107-aa8b-1055510186da"/>
    <property name="endpoint.package.version.com.mycorp.examples.timeservice" value-type="String" value="2.0.0"/>
    <property name="endpoint.service.id" value-type="Long" value="83"/>
    <property name="objectClass" value-type="String">
      <array>
        <value>com.mycorp.examples.timeservice.ITimeService</value>
      </array>
    </property>
    <property name="remote.configs.supported" value-type="String">
      <array>
        <value>ecf.generic.server</value>
      </array>
    </property>
    <property name="remote.intents.supported" value-type="String">
      <array>
        <value>passByValue</value>
        <value>exactlyOnce</value>
        <value>ordered</value>
      </array>
    </property>
    <property name="service.imported" value-type="String" value="true"/>
    <property name="service.imported.configs" value-type="String">
      <array>
        <value>ecf.generic.server</value>
      </array>
    </property>
  </endpoint-description>
</endpoint-descriptions>

Listing Imports

Command: listimports | limps

Arguments:

   endpoint.id -  Optional.  If present, details are presented about the endpoint with the given endpoint.id.  If not present, a table is presented with endpoint.id, Importing Container ID, and Imported Service Id.

Example:

osgi> limps
endpoint.id                          |Importing Container ID                       |Imported Service Id
58176215-e890-4107-aa8b-1055510186da |dXJ7UaozuFB+sWL22joWHpsf+RQ=                 |84

osgi> listimports 58176215-e890-4107-aa8b-1055510186da
<endpoint-descriptions xmlns="http://www.osgi.org/xmlns/rsa/v1.0.0">
  <endpoint-description>
    <property name="ecf.endpoint.id" value-type="String" value="ecftcp://localhost:3288/server"/>
    <property name="ecf.endpoint.id.ns" value-type="String" value="org.eclipse.ecf.core.identity.StringID"/>
    <property name="ecf.endpoint.ts" value-type="Long" value="1520450143497"/>
    <property name="ecf.exported.async.interfaces" value-type="String" value="*"/>
    <property name="ecf.generic.server.hostname" value-type="String" value="localhost"/>
    <property name="ecf.generic.server.port" value-type="String" value="3288"/>
    <property name="ecf.rsvc.id" value-type="Long" value="1"/>
    <property name="endpoint.framework.uuid" value-type="String" value="74747fb9-e9db-4b29-8e4c-882b68a2b03b"/>
    <property name="endpoint.id" value-type="String" value="58176215-e890-4107-aa8b-1055510186da"/>
    <property name="endpoint.package.version.com.mycorp.examples.timeservice" value-type="String" value="2.0.0"/>
    <property name="endpoint.service.id" value-type="Long" value="83"/>
    <property name="objectClass" value-type="String">
      <array>
        <value>com.mycorp.examples.timeservice.ITimeService</value>
      </array>
    </property>
    <property name="remote.configs.supported" value-type="String">
      <array>
        <value>ecf.generic.server</value>
      </array>
    </property>
    <property name="remote.intents.supported" value-type="String">
      <array>
        <value>passByValue</value>
        <value>exactlyOnce</value>
        <value>ordered</value>
      </array>
    </property>
    <property name="service.imported.configs" value-type="String">
      <array>
        <value>ecf.generic.client</value>
      </array>
    </property>
  </endpoint-description>
</endpoint-descriptions>

Remote Service Export

RSA allows the exporting of a given OSGi service. Exporting results in the creation/setup/use of a remote service distribution provider, and typically the publish of an Endpoint Description for discovery by remote consumers.

Command: exportservice | expsvc

Arguments:

   service.id - Required.   This is the id of a OSGi service reference to export.
   [overridingproperties] - Optional.  This is a map of service properties provided for overriding the values specific when the OSGi service was registered.

Example (rsadebug off)

osgi> expsvc 83 [ service.exported.interfaces=* service.exported.configs=ecf.generic.server foo=bar ]
Service.id=83 successfully exported with endpoint description:
<endpoint-descriptions xmlns="http://www.osgi.org/xmlns/rsa/v1.0.0">
  <endpoint-description>
    <property name="ecf.endpoint.id" value-type="String" value="ecftcp://localhost:3288/server"/>
    <property name="ecf.endpoint.id.ns" value-type="String" value="org.eclipse.ecf.core.identity.StringID"/>
    <property name="ecf.endpoint.ts" value-type="Long" value="1520453500490"/>
    <property name="ecf.exported.async.interfaces" value-type="String" value="*"/>
    <property name="ecf.generic.server.hostname" value-type="String" value="localhost"/>
    <property name="ecf.generic.server.port" value-type="String" value="3288"/>
    <property name="ecf.rsvc.id" value-type="Long" value="4"/>
    <property name="endpoint.framework.uuid" value-type="String" value="5248d7d2-ad5e-4441-ba68-b695778bc5b8"/>
    <property name="endpoint.id" value-type="String" value="f0a509ad-103c-4fae-a22e-d2f625e4c838"/>
    <property name="endpoint.package.version.com.mycorp.examples.timeservice" value-type="String" value="2.0.0"/>
    <property name="endpoint.service.id" value-type="Long" value="83"/>
    <property name="foo" value-type="String" value="bar"/>
    <property name="objectClass" value-type="String">
      <array>
        <value>com.mycorp.examples.timeservice.ITimeService</value>
      </array>
    </property>
    <property name="remote.configs.supported" value-type="String">
      <array>
        <value>ecf.generic.server</value>
      </array>
    </property>
    <property name="remote.intents.supported" value-type="String">
      <array>
        <value>passByValue</value>
        <value>exactlyOnce</value>
        <value>ordered</value>
      </array>
    </property>
    <property name="service.imported" value-type="String" value="true"/>
    <property name="service.imported.configs" value-type="String">
      <array>
        <value>ecf.generic.server</value>
      </array>
    </property>
  </endpoint-description>
</endpoint-descriptions>

Remote Service Import

RSA allows the importing of an Endpoint Description. Importing results in the creation of a local proxy, and publication of the proxy into the local OSGi service registry.

Command: importservice | impsvc

Arguments:

   endpointurl - Optional.  This is a URL pointing at a file in EDEF format, describing the endpoint to be imported.  If no endpointurl is given, then the EDEF contents will be read from the console and terminated by an empty line.

Example (rsadebug on)

osgi> importservice -e file:///c:\\Users\\slewis\\ep.xml
Discovered ITimeServiceAsync via DS
13:59:04.490;IMPORT_REGISTRATION;importedSR={com.mycorp.examples.timeservice.ITimeService, com.mycorp.examples.timeservice.ITimeServiceAsync}={ecf.generic.server.port=3288, ecf.exported.async.interfaces=*, service.id=85, service.bundleid=5, service.scope=bundle, foo=bar, ecf.generic.server.hostname=localhost, service.imported.configs=[ecf.generic.client], endpoint.id=f0a509ad-103c-4fae-a22e-d2f625e4c838, service.imported=org.eclipse.ecf.provider.remoteservice.generic.RemoteServiceImpl@3c85a245};cID=StringID[ecftcp://localhost:3288/server];rsId=4
--Endpoint Description---
<endpoint-descriptions xmlns="http://www.osgi.org/xmlns/rsa/v1.0.0">
  <endpoint-description>
    <property name="ecf.endpoint.id" value-type="String" value="ecftcp://localhost:3288/server"/>
    <property name="ecf.endpoint.id.ns" value-type="String" value="org.eclipse.ecf.core.identity.StringID"/>
    <property name="ecf.endpoint.ts" value-type="Long" value="1520453500490"/>
    <property name="ecf.exported.async.interfaces" value-type="String" value="*"/>
    <property name="ecf.generic.server.hostname" value-type="String" value="localhost"/>
    <property name="ecf.generic.server.port" value-type="String" value="3288"/>
    <property name="ecf.rsvc.id" value-type="Long" value="4"/>
    <property name="endpoint.framework.uuid" value-type="String" value="5248d7d2-ad5e-4441-ba68-b695778bc5b8"/>
    <property name="endpoint.id" value-type="String" value="f0a509ad-103c-4fae-a22e-d2f625e4c838"/>
    <property name="endpoint.package.version.com.mycorp.examples.timeservice" value-type="String" value="2.0.0"/>
    <property name="endpoint.service.id" value-type="Long" value="83"/>
    <property name="foo" value-type="String" value="bar"/>
    <property name="objectClass" value-type="String">
      <array>
        <value>com.mycorp.examples.timeservice.ITimeService</value>
      </array>
    </property>
    <property name="remote.configs.supported" value-type="String">
      <array>
        <value>ecf.generic.server</value>
      </array>
    </property>
    <property name="remote.intents.supported" value-type="String">
      <array>
        <value>passByValue</value>
        <value>exactlyOnce</value>
        <value>ordered</value>
      </array>
    </property>
    <property name="service.imported.configs" value-type="String">
      <array>
        <value>ecf.generic.client</value>
      </array>
    </property>
  </endpoint-description>
</endpoint-descriptions>
---End Endpoint Description
Endpoint id=f0a509ad-103c-4fae-a22e-d2f625e4c838 with service.id=85 successfully imported:
<endpoint-descriptions xmlns="http://www.osgi.org/xmlns/rsa/v1.0.0">
  <endpoint-description>
    <property name="ecf.endpoint.id" value-type="String" value="ecftcp://localhost:3288/server"/>
    <property name="ecf.endpoint.id.ns" value-type="String" value="org.eclipse.ecf.core.identity.StringID"/>
    <property name="ecf.endpoint.ts" value-type="Long" value="1520453500490"/>
    <property name="ecf.exported.async.interfaces" value-type="String" value="*"/>
    <property name="ecf.generic.server.hostname" value-type="String" value="localhost"/>
    <property name="ecf.generic.server.port" value-type="String" value="3288"/>
    <property name="ecf.rsvc.id" value-type="Long" value="4"/>
    <property name="endpoint.framework.uuid" value-type="String" value="5248d7d2-ad5e-4441-ba68-b695778bc5b8"/>
    <property name="endpoint.id" value-type="String" value="f0a509ad-103c-4fae-a22e-d2f625e4c838"/>
    <property name="endpoint.package.version.com.mycorp.examples.timeservice" value-type="String" value="2.0.0"/>
    <property name="endpoint.service.id" value-type="Long" value="83"/>
    <property name="foo" value-type="String" value="bar"/>
    <property name="objectClass" value-type="String">
      <array>
        <value>com.mycorp.examples.timeservice.ITimeService</value>
      </array>
    </property>
    <property name="remote.configs.supported" value-type="String">
      <array>
        <value>ecf.generic.server</value>
      </array>
    </property>
    <property name="remote.intents.supported" value-type="String">
      <array>
        <value>passByValue</value>
        <value>exactlyOnce</value>
        <value>ordered</value>
      </array>
    </property>
    <property name="service.imported.configs" value-type="String">
      <array>
        <value>ecf.generic.client</value>
      </array>
    </property>
  </endpoint-description>
</endpoint-descriptions>

osgi> Remote time is: 1520459944495

Example (console input, rsadebug off):

osgi> importservice
Waiting for console input.   To complete enter an empty line...
<<pasted into console>>
<endpoint-descriptions xmlns="http://www.osgi.org/xmlns/rsa/v1.0.0">
  <endpoint-description>
    <property name="ecf.endpoint.id" value-type="String" value="ecftcp://localhost:3288/server"/>
    <property name="ecf.endpoint.id.ns" value-type="String" value="org.eclipse.ecf.core.identity.StringID"/>
    <property name="ecf.endpoint.ts" value-type="Long" value="1520453500490"/>
    <property name="ecf.exported.async.interfaces" value-type="String" value="*"/>
    <property name="ecf.generic.server.hostname" value-type="String" value="localhost"/>
    <property name="ecf.generic.server.port" value-type="String" value="3288"/>
    <property name="ecf.rsvc.id" value-type="Long" value="4"/>
    <property name="endpoint.framework.uuid" value-type="String" value="5248d7d2-ad5e-4441-ba68-b695778bc5b8"/>
    <property name="endpoint.id" value-type="String" value="f0a509ad-103c-4fae-a22e-d2f625e4c838"/>
    <property name="endpoint.package.version.com.mycorp.examples.timeservice" value-type="String" value="2.0.0"/>
    <property name="endpoint.service.id" value-type="Long" value="83"/>
    <property name="foo" value-type="String" value="bar"/>
    <property name="objectClass" value-type="String">
      <array>
        <value>com.mycorp.examples.timeservice.ITimeService</value>
      </array>
    </property>
    <property name="remote.configs.supported" value-type="String">
      <array>
        <value>ecf.generic.server</value>
      </array>
    </property>
    <property name="remote.intents.supported" value-type="String">
      <array>
        <value>passByValue</value>
        <value>exactlyOnce</value>
        <value>ordered</value>
      </array>
    </property>
    <property name="service.imported" value-type="String" value="true"/>
    <property name="service.imported.configs" value-type="String">
      <array>
        <value>ecf.generic.server</value>
      </array>
    </property>
  </endpoint-description>
</endpoint-descriptions>

<<end pasted into console>>

Discovered ITimeServiceAsync via DS
Endpoint id=f0a509ad-103c-4fae-a22e-d2f625e4c838 with service.id=86 successfully imported:
<endpoint-descriptions xmlns="http://www.osgi.org/xmlns/rsa/v1.0.0">
  <endpoint-description>
    <property name="ecf.endpoint.id" value-type="String" value="ecftcp://localhost:3288/server"/>
    <property name="ecf.endpoint.id.ns" value-type="String" value="org.eclipse.ecf.core.identity.StringID"/>
    <property name="ecf.endpoint.ts" value-type="Long" value="1520453500490"/>
    <property name="ecf.exported.async.interfaces" value-type="String" value="*"/>
    <property name="ecf.generic.server.hostname" value-type="String" value="localhost"/>
    <property name="ecf.generic.server.port" value-type="String" value="3288"/>
    <property name="ecf.rsvc.id" value-type="Long" value="4"/>
    <property name="endpoint.framework.uuid" value-type="String" value="5248d7d2-ad5e-4441-ba68-b695778bc5b8"/>
    <property name="endpoint.id" value-type="String" value="f0a509ad-103c-4fae-a22e-d2f625e4c838"/>
    <property name="endpoint.package.version.com.mycorp.examples.timeservice" value-type="String" value="2.0.0"/>
    <property name="endpoint.service.id" value-type="Long" value="83"/>
    <property name="foo" value-type="String" value="bar"/>
    <property name="objectClass" value-type="String">
      <array>
        <value>com.mycorp.examples.timeservice.ITimeService</value>
      </array>
    </property>
    <property name="remote.configs.supported" value-type="String">
      <array>
        <value>ecf.generic.server</value>
      </array>
    </property>
    <property name="remote.intents.supported" value-type="String">
      <array>
        <value>passByValue</value>
        <value>exactlyOnce</value>
        <value>ordered</value>
      </array>
    </property>
    <property name="service.imported.configs" value-type="String">
      <array>
        <value>ecf.generic.client</value>
      </array>
    </property>
  </endpoint-description>
</endpoint-descriptions>

osgi> Remote time is: 1520460125236

Remote Service Properties Update

RSA allows the updating of exported service endpoint description properties. Updating the properties allows new prop names and values to be updated on both the exporter and the importer of a remote service.

Command: updateservice | updsvc

Arguments:

   endpoint.id - Required.   This is the id of a Endpoint Description previously exported.
   newproperties - Required.  This is a map of service properties provided for updating the endpoint description properties.

Example (rsadebug off)

osgi> updsvc f0a509ad-103c-4fae-a22e-d2f625e4c838 [ foo=bar ]
<endpoint-descriptions xmlns="http://www.osgi.org/xmlns/rsa/v1.0.0">
  <endpoint-description>
    <property name="ecf.endpoint.id" value-type="String" value="ecftcp://localhost:3288/server"/>
    <property name="ecf.endpoint.id.ns" value-type="String" value="org.eclipse.ecf.core.identity.StringID"/>
    <property name="ecf.endpoint.ts" value-type="Long" value="1520460634669"/>
    <property name="ecf.exported.async.interfaces" value-type="String" value="*"/>
    <property name="ecf.generic.server.hostname" value-type="String" value="localhost"/>
    <property name="ecf.generic.server.port" value-type="String" value="3288"/>
    <property name="ecf.rsvc.id" value-type="Long" value="4"/>
    <property name="endpoint.framework.uuid" value-type="String" value="5248d7d2-ad5e-4441-ba68-b695778bc5b8"/>
    <property name="endpoint.id" value-type="String" value="f0a509ad-103c-4fae-a22e-d2f625e4c838"/>
    <property name="endpoint.package.version.com.mycorp.examples.timeservice" value-type="String" value="2.0.0"/>
    <property name="endpoint.service.id" value-type="Long" value="83"/>
    <property name="foo" value-type="String" value="bar"/>
    <property name="objectClass" value-type="String">
      <array>
        <value>com.mycorp.examples.timeservice.ITimeService</value>
      </array>
    </property>
    <property name="remote.configs.supported" value-type="String">
      <array>
        <value>ecf.generic.server</value>
      </array>
    </property>
    <property name="remote.intents.supported" value-type="String">
      <array>
        <value>passByValue</value>
        <value>exactlyOnce</value>
        <value>ordered</value>
      </array>
    </property>
    <property name="service.bundleid" value-type="Long" value="31"/>
    <property name="service.imported" value-type="String" value="true"/>
    <property name="service.imported.configs" value-type="String">
      <array>
        <value>ecf.generic.server</value>
      </array>
    </property>
    <property name="service.scope" value-type="String" value="singleton"/>
  </endpoint-description>
</endpoint-descriptions>

Note the present of the foo=bar value in the updated endpoint description.