newton
Newton
 

Newton: CDS Protocol for External Clients

This How-To describes the steps necessary to interact with remote objects annotated by CDS from outside the Newton environment.

Intended Audience

Clients interacting with remote objects need to be familiar with the cds protocol in an environment comprising Newton containers since codebase annotations will be in this form.

Purpose

Prerequisites

Steps

Here is how to proceed.

Enable Server-side external CDS

For the time being this needs to be enabled manually. In a subsequent revision at least one container in the environment will fulfill this requirement automatically.

Assumption
You are in $Newton_HOME/install/Newton within the directory structure created by unzipping the download such that you were able to start the container by issuing bin/Newton.sh or bin/Newton.bat
> cds scan boot core/lib/components
> installer install file:core/instances/beacon-instance.xml      
> installer install file:core/instances/cds-external-instance.xml

Configure Server-side external CDS

Configurable properties include:

  • A multicast address and port used to allow clients to discover cds servers (mcast.addr and mcast.port)
  • A scoping name which allows re-use of multicast addresses and ports (mcast.scope)

Configuration can be applied in a number of ways with preferential overrides. In order of decreasing preference:

  1. The cds-external instance file located at $Newton_HOME/install/Newton/core/instances/cds-external-instance.xml (this is the expected source of server side configuration). 
    <?xml version="1.0"?>
<composite name="cds-external">
  <description>CDS External</description>
  <bundle.root bundle="cds-external" version="0.1"/>
  <include name="cds-external-template"/>
  <property name="mcast.port" value="2028" type="integer"/>
  <property name="mcast.addr" value="228.192.0.2" type="string"/>
  <property name="mcast.scope" value="${system#Newton.fabric.name:-${system#user.name}}" type="string"/>
</composite>
  2. mcast.scope is determined from the system property newton.fabric.name (in the absence of equivalent instance configuration)
  3. system properties:
    • org.cauldron.newton.net.channel.mcast.addr
    • org.cauldron.newton.net.channel.mcast.port
    • org.cauldron.newton.net.channel.mcast.scope
  4. mcast.scope is determined from the system property user.name
  • default mcast.addr is 228.192.0.2
  • default mcast.port is 2028

Enable Client-side external CDS

We provide a jar which contains a custom URLStreamHandler capable of handling cds URLs. The jar is located at $Newton_HOME/install/newton/core/lib/bundles/cds-external-client.jar and should be included in your classpath along with log4j.jar. The property java.protocol.handler.pkgs=org.cauldron.newton.net.protocol enables the URLStreamHandler.

Configure Client-side external CDS

In order of decreasing preference:

  1. mcast.scope is determined from the system property newton.fabric.name
  2. system properties:
    • org.cauldron.newton.net.channel.mcast.addr
    • org.cauldron.newton.net.channel.mcast.port
    • org.cauldron.newton.net.channel.mcast.scope
  3. mcast.scope is determined from the system property user.name
  • default mcast.addr is 228.192.0.2
  • default mcast.port is 2028

Example - The Jini Browser as an External CDS Client

Security Policy
A permissive policy named all.policy is required in the directory where this command is executed
Codebase Quotes on Unix / Linux
The codebase needs to be quoted as below to avoid it being interpreted as a series of commands

Additionally the Jini Lookup Service needs to be installed:

  > installer install file:core/instances/reggie-instance.xml
      
java -cp .:$JINI_HOME/lib/browser.jar:\
$LOG4J_HOME/lib/log4j.jar:$CONTAINER_HOME/core/lib/bundles/cds-external-client.jar:\
$CONTAINER_HOME/core/lib/app/if-jini-dl.jar:\
$CONTAINER_HOME/core/lib/app/if-jini-boot.jar \
-Djava.protocol.handler.pkgs=org.cauldron.newton.net.protocol \
-Djava.security.policy=all.policy \
-Djava.rmi.server.codebase="cds://jinitsk/browser-dl.jar?zone=boot&type=jini.codebase&bundle.symbolic.name=jinibrowser-bundle&version=2.1" \
com.sun.jini.example.browser.Browser
0.2