This version must be installed on Petals ESB 5.0.2+

Introduction

Features

The Petals RMI service engine aims to provide a direct access to the internal NMR of a Petals ESB container. So an external Java client can interact directly with the NMR:

to activate, deactivate or search endpoints,
to create, send or receive message exchanges.

The external Java client can act as a service consumer or a service consumer:

a Java client as service consumer will create message exchanges, send and receive them. Such a client is responsible to apply correctly message exchange patterns,
a Java Client as service provider will activate/deactivate endpoints receiving and replying to message exchanges.

Petals SE RMI overview

Recommended usage

This component should be used in test context, for example for integration tests of JBI components.

This component is distributed with the Petals Community Pack, and we discourage you from using it in a production environment.

Table of contents

1 Introduction

1.1 Features
1.2 Recommended usage

2 Usage
3 Implementing RMI client interacting with a Petals SE RMI

3.1 Accessing the RMI registry
3.2 Getting a remote component context
3.3 RMI client acting as a RMI client 'provider'
3.4 RMI client acting as a RMI client 'consumer'

4 Installation

4.1 Configuration
4.2 Using an external RMI registry

5 Monitoring the component

5.1 Using metrics

5.1.1 Common metrics
5.1.2 Dedicated metrics

5.2 Receiving alerts

5.2.1 Common alerts
5.2.2 Dedicated alerts

Contributors

No contributors found for: authors on selected page(s)

Usage

Once the RMI component is started, it binds a representation of its component context in the RMI registry. A client is thus able to access to this remote representation of the component context to create severals endpoints and communicate with others JBI services.

From this remote component context, the client can get the RMI representation of :

the delivery channel,
the message exchange factory.

The RMI client can also :

receive JBI messages,
send JBI messages.

To make easier these different actions, a client library is provided. The next section of this document defines how to use this library to create an RMI client.

The current version of the Petals SE RMI registers only one remote component context. So, just one client can be connected to this context on this component. This restriction will be deleted in a next version of the component. For now, if you want install several clients, you must install several Petals SE RMI components.

Implementing RMI client interacting with a Petals SE RMI

Your RMI client will depend on the following Maven artifacts as RMI client libraries:

org.ow2.petals:petals-rmi-proxyclient:1.2.0,
org.ow2.petals:petals-rmi-server:1.6.0,
org.ow2.petals:petals-rmi-common:1.4.1

that embed classes mentioned below.

Accessing the RMI registry

The client package of the RMI component contains only one class (the ComponentContextFactoryLocator). To instantiate an object of this class, three inputs parameters are required in the constructor:

the IP address of the RMI registry server,
the port to access to the RMI registry (the port used by the RMI registry to handle requests),
the reference name of the remote component context registered in the RMI registry.

The instantiation of object of this class is presented below:

ComponentContexFactoryLocator ccl = new ComponentContexFactoryLocator("192.168.1.150", 1099, "RMIComponentContext");

To avoid some errors, you must inserted this line code below at the beginning of the program

System.setProperty("com.sun.xml.namespace.QName.useCompatibleSerialVersionUID", "1.0");

If the Petals SE RMI component is not started when the ComponentContexFactoryLocator object is instantiated, a remote exception is raised.

Once the object is instantiated, it is possible to access to remote component context.

Getting a remote component context

Once you have an instance of ComponentContexFactoryLocator, you will retrieve a remote component context that is your entry point on the Petals SE RMI to access the NMR. Two different kinds of remote component context are available:

a remote component context for RMI client acting as a service 'provider', using ComponentContextLocator.getComponentClientContextFactory().createRemoteComponentContextProviderClient(),
and a remote component context for RMI client acting as a service 'consumer', using ComponentContextLocator.getComponentClientContextFactory().createRemoteComponentContextConsumerClient().

RMI client acting as a RMI client 'provider'

The code lines presented below allows a RMI client 'provider' to access to the remote component context to activate and deactivate an endpoint, to wait incoming message exchanges, to send message exchanges:

// Access to the remote component context 'provider' from the ComponentContextLocator
RemoteComponentContextClient rccc = ccl.getComponentClientContextFactory().createRemoteComponentContextProviderClient();

// Activation of an endpoint
ServiceEndpoint endpoint = rccc.activateEndpoint(new QName("http://petals.objectweb.org/", "RmiService"), "RmiEndpoint");

// Wait an incoming message exchange
MessageExchange exchange = rccc.getDeliveryChannel().accept();

// Send a message exchange
rccc.getDeliveryChannel().send(exchange);

// Deactivation of the endpoint
rcc.deactivateEndpoint(endpoint);

RMI client acting as a RMI client 'consumer'

The code lines presented below allows a RMI client 'consumer' to access to the remote component context to get the remote message exchange factory and create different kind of messages, to send message exchanges and wait replies:

// Access to the remote component context 'consumer' from the ComponentContextLocator
RemoteComponentContextClient rccc = ccl.getComponentClientContextFactory().createRemoteComponentContextConsumerClient();

// Create the remote message exchange factory from remote component context
RemoteMessageExchangeFactory rmef = rcc.getDeliveryChannel().createExchangeFactory();

// create an in only message exchange
MessageExchange msgInOnly = rmef.createInOnlyExchange();

// create an in out message exchange
MessageExchange msgInOut = rmef.createInOutExchange();

// create an in optional out message exchange
MessageExchange msgOptionalOut = rmef.createInOptionalOutExchange();

// create an robust in only message exchange
MessageExchange msgRobustInOnly = rmef.createRobustInOnlyExchange();

// Send a message exchange
rccc.getDeliveryChannel().send(msgInOut);

// Wait comeback of the message exchanges
MessageExchange exchange = rccc.getDeliveryChannel().accept();

The following code snippet shows an synchronous message exchange between the client and a provider:

RemoteDeliveryChannel rdc = rccc.getDeliveryChannel();

// Create the remote message exchange factory from remote component context
RemoteMessageExchangeFactory rmef = rdc.createExchangeFactory();

// create an in out message exchange
MessageExchange msgInOut = rmef.createInOutExchange();

// Send a synchronous message
msgInOut = rdc.sendSync(msgInOut);

if(msgInOut != null) {
      // Change the status 
      msgInOut.setStatus(ExchangeStatus.DONE);
            
      // Terminate the exchange
      rdc.send(msgInOut);
}

The method 'sendSync' is not JBI compliant. It is different of JBI interface because the message exchange in input parameter is not a remote object. So, it cannot be set in the method.

Installation

The installation of the RMI component is achieved in the same way as classical components, please refer to the user guide for more details.

Configuration

This component is not based on the Petals CDK, so all standard configuration parameters are not available.

Configuration of the SE RMI component

Parameter	Description	Default	Required	Scope
port	The port used by the RMI component to contact the RMI registry.	1099	No	Installation
host	The hostname where the RMI registry is running.	-	No	Installation
embeddedregistry	Defines if the internal RMI registry of the component must be activated. By default, the internal RMI registry is started on the port defined by the parameter '`port`'. If this parameter is set to `false`, the administrator of the Petals SE RMI component is in charge to manage and start his own RMI registry before starting the RMI component. The hostname of the RMI registry must be set using the parameter '`host`'	true	No	Installation
componentcontextname	Define the reference name registered in the RMI registry when the bind with the remote component context is realized. This remote component context is just a representation of the concrete component context of PEtALS. No direct access to a concrete component is provided to clients.	RMIComponentContext	No	Installation

Definition of the parameter 'scope':

Installation: The parameter can be set during the installation of the component, by using the installation MBean (see JBI specifications for details about the installation sequence). If the parameter is optional and has not been defined during the development of the component, it is not available at installation time.
Runtime: The parameter can be set during the installation of the component and during runtime. The runtime configuration can be changed using the CDK custom MBean named RuntimeConfiguration. If the parameter is optional and has not been defined during the development of the component, it is not available at installation and runtime times.

Using an external RMI registry

If the component is configured to have an external RMI registry (the parameter 'embeddedregistry' is set to false), this external registry must be started before installation:

Petals SE RMI overview

Monitoring the component

Using metrics

Several probes providing metrics are included in the component, and are available through the JMX MBean 'org.ow2.petals:type=custom,name=monitoring_<component-id>', where <component-id> is the unique JBI identifier of the component.

Common metrics

The following metrics are provided through the Petals CDK, and are common to all components:

Metrics, as MBean attribute	Description	Detail of the value	Configurable
MessageExchangeAcceptorThreadPoolMaxSize	The maximum number of threads of the message exchange acceptor thread pool	integer value, since the last startup of the component	yes, through `acceptor-pool-size`
MessageExchangeAcceptorThreadPoolCurrentSize	The current number of threads of the message exchange acceptor thread pool. Should be always equals to `MessageExchangeAcceptorThreadPoolMaxSize`.	instant integer value	no
MessageExchangeAcceptorCurrentWorking	The current number of working message exchange acceptors.	instant long value	no
MessageExchangeAcceptorMaxWorking	The max number of working message exchange acceptors.	long value, since the last startup of the component	no
MessageExchangeAcceptorAbsoluteDurations	The aggregated durations of the working message exchange acceptors since the last startup of the component.	n-tuple value containing, in nanosecond: the maximum duration, the average duration, the minimum duration.	no
MessageExchangeAcceptorRelativeDurations	The aggregated durations of the working message exchange acceptors on the last sample.	n-tuple value containing, in nanosecond: the maximum duration, the average duration, the minimum duration, the 10-percentile duration (10% of the durations are lesser than this value), the 50-percentile duration (50% of the durations are lesser than this value), the 90-percentile duration (90% of the durations are upper than this value).	no
MessageExchangeProcessorAbsoluteDurations	The aggregated durations of the working message exchange processor since the last startup of the component.	n-tuple value containing, in milliseconds: the maximum duration, the average duration, the minimum duration.	no
MessageExchangeProcessorRelativeDurations	The aggregated durations of the working message exchange processor on the last sample.	n-tuple value containing, in milliseconds: the maximum duration, the average duration, the minimum duration, the 10-percentile duration (10% of the durations are lesser than this value), the 50-percentile duration (50% of the durations are lesser than this value), the 90-percentile duration (90% of the durations are upper than this value).	no
MessageExchangeProcessorThreadPoolActiveThreadsCurrent	The current number of active threads of the message exchange processor thread pool	instant integer value	no
MessageExchangeProcessorThreadPoolActiveThreadsMax	The maximum number of threads of the message exchange processor thread pool that was active	integer value, since the last startup of the component	no
MessageExchangeProcessorThreadPoolIdleThreadsCurrent	The current number of idle threads of the message exchange processor thread pool	instant integer value	no
MessageExchangeProcessorThreadPoolIdleThreadsMax	The maximum number of threads of the message exchange processor thread pool that was idle	integer value, since the last startup of the component	no
MessageExchangeProcessorThreadPoolMaxSize	The maximum size, in threads, of the message exchange processor thread pool	instant integer value	yes, through `http-thread-pool-size-max`
MessageExchangeProcessorThreadPoolMinSize	The minimum size, in threads, of the message exchange processor thread pool	instant integer value	yes, through `http-thread-pool-size-min`
MessageExchangeProcessorThreadPoolQueuedRequestsCurrent	The current number of enqueued requests waiting to be processed by the message exchange processor thread pool	instant integer value	no
MessageExchangeProcessorThreadPoolQueuedRequestsMax	The maximum number of enqueued requests waiting to be processed by the message exchange processor thread pool since the last startup of the component	instant integer value	no
ServiceProviderInvocations	The number of service provider invocations grouped by: interface name, as `QName`, the invoked service provider, service name, as `QName`, the invoked service provider, invoked operation, as `QName`, message exchange pattern, and execution status (PENDING, ERROR, FAULT, SUCCEEDED).	integer counter value since the last startup of the component	no
ServiceProviderInvocationsResponseTimeAbs	The aggregated response times of the service provider invocations since the last startup of the component grouped by: interface name, as `QName`, the invoked service provider, service name, as `QName`, the invoked service provider, invoked operation, as `QName`, message exchange pattern, and execution status (PENDING, ERROR, FAULT, SUCCEEDED).	n-tuple value containing, in millisecond: the maximum response time, the average response time, the minimum response time.	no
ServiceProviderInvocationsResponseTimeRel	The aggregated response times of the service provider invocations on the last sample, grouped by: interface name, as `QName`, the invoked service provider, service name, as `QName`, the invoked service provider, invoked operation, as `QName`, message exchange pattern, and execution status (PENDING, ERROR, FAULT, SUCCEEDED).	n-tuple value containing, in millisecond: the maximum response time, the average response time, the minimum response time, the 10-percentile response time (10% of the response times are lesser than this value), the 50-percentile response time (50% of the response times are lesser than this value), the 90-percentile response time (90% of the response times are lesser than this value).	no

Dedicated metrics

No dedicated metric is available.

Receiving alerts

Several alerts are notified by the component through notification of the JMX MBean 'org.ow2.petals:type=custom,name=monitoring_<component-id>', where <component-id> is the unique JBI identifier of the component.

To integrate these alerts with Nagios, see Receiving Petals ESB defects in Nagios.

Common alerts

Defect	JMX Notification
A message exchange acceptor thread is dead	`type`: `org.ow2.petals.component.framework.process.message.acceptor.pool.thread.dead` no user data
No more thread is available in the message exchange acceptor thread pool	`type`: `org.ow2.petals.component.framework.process.message.acceptor.pool.exhausted` no user data
No more thread is available to run a message exchange processor	`type`: `org.ow2.petals.component.framework.process.message.processor.thread.pool.exhausted` no user data

Dedicated alerts

No dedicated alert is available.

Petals Components Wiki

All versions of Petals ESB

Helpful links

Petals-SE-RMI 1.7.1+