JAPC remoting extension documentation

1. General description

JAPC remoting extension is used to represent middle-tier servers as virtual devices and/or parameters. Each middle-tier server is known as a remote or virtual service.

All basic operations (GET/SET/SUBSCRIBE) are implemented in this extension and can use several remoting technologies. All RPC (GET, SET, START/STOP MONITROING calls) can be done through Java RMI (Spring), HTTP (Spring) and JMS (Lingo, not used anymore at the moment). The updates are sent to the clients through JMS topics.

JAPC remoting extension provides a number of configurable features for remote services to do the basic things without a lot of complexity but at the same time to be flexible enough to support complex systems. As for any JAPC service the configuration is stored in a JAPC registry (or CCDB).

2. Administrative mechanisms

After RPC START MONITORING came from the client the server (producer) starts to publish updates through JMS, so all the interested clients (consumers) receive them. In case of JAPC remoting extension the producers and the consumers are in different processes. Therefore the publishing server never knows if a single client is still running and interested in the published updates. Moreover after the server is rebooted it should somehow restart all the parameter update publications (subscriptions) which were active before the rebooting since the clients are still "subscribed" and expect to receive the updates. There are 2 ways to solve this problem:

3. Technical description and configuration parameters for remote services

There is a number of parameters which should be configured for the remote services. The configuration is stored in JAPC registry (or CCDB). Parameters affect all the aspects of behavior of a remote service. For example, as it is said above, the parameter updates are published to the clients through JMS topics. The topic names are build following certain rules and depending on the configuration parameter. The general format of a topic name used to publish updates is:

jmsTopicPrefix.serverId.deviceName[.SEL.selector]

The different parts of a topic name are described below.

Some of the parameters are optional and have a default value. Others are required and must be specified either in the service configuration or at run-time. Some parameters can be overwritten or set at run-time but some can't.

serviceName
First of all each remote service (as well as any JAPC service) has a name. This parameter is required and can not be set or overwritten at run-time.

protocol
The protocol which is not so important for local JAPC services becomes quite important for remote services: it specifies a technology which is used for RPC. This parameter is required and can not be overwritten. JAPC supports the following remoting protocols:

serverId
Each service has its identifier to be easily distinguished from other services. If this parameter is defined in the configuration it can not be overwritten at run-time. However if it is not defined in the configuration it can be set on both client and server side with VM argument "serverId".

jmsBrokerList
Remote services can publish the updates through different JMS brokers. jmsBrokerList specifies the URL of a JMS broker to work with. If this parameter is defined in the configuration it can not be overwritten at run-time. However if it is not defined in the configuration it can be set on both client and server side with VM argument "japc.remote.jms.brokerlist". If this parameter is not specified neither in configuration nor with VM argument then the default JMS broker will be used.

topicPrefix
Each service publishes the parameter updates into topics with the names built according to some rules. One of the rules is that each topic for a remote service is prefixed with some common beginning (ex. "CERN.CNGS.PROD"), to easily separate messages of different remote services. If this parameter is defined in the configuration it can not be overwritten at run-time. However if it is not defined in the configuration it can be set on both client and server side with VM argument "japc.remote.jms.topic.prefix". If this parameter is not specified neither in configuration nor with VM argument then the default JMS topic prefix will be used ("CERN.DEFAULT_JMS_TOPIC_PREFIX").

administrationEnabled
This parameter specifies if the service is using administrative mechanisms (see above) or not. This parameter is optional and the default value is "false".

selectorAware
If a service is selectorAware then the selector name is also included to a topic name used to publish updates. This is used to split updates coming for different cycles/users. This parameter is optional and the default value is "false". In case when this option is enabled the selector is normally taken from the JAPC value header (in case of a parameter update) or from ParameterException (in case of problems). The servers (publishers) can also use RemoteServerFactory.getPublisherPvl(Selector) or RemoteServerFactory.getPublisher(String, Selector) to create a publisher with particular selector which then will be used. A client just subscribes to a selector it needs.

firstUpdate
A service can be configured to use different first-update policy.

This parameter is optional and the default value is "no".