IntroductionFeaturesThe 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:
Petals SE RMI overview
Recommended usageThis 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
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.
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:
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:
|
no |
MessageExchangeAcceptorRelativeDurations | The aggregated durations of the working message exchange acceptors on the last sample. | n-tuple value containing, in nanosecond:
|
no |
MessageExchangeProcessorAbsoluteDurations | The aggregated durations of the working message exchange processor since the last startup of the component. | n-tuple value containing, in milliseconds:
|
no |
MessageExchangeProcessorRelativeDurations | The aggregated durations of the working message exchange processor on the last sample. | n-tuple value containing, in milliseconds:
|
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:
|
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:
|
n-tuple value containing, in millisecond:
|
no |
ServiceProviderInvocationsResponseTimeRel | The aggregated response times of the service provider invocations on the last sample, grouped by:
|
n-tuple value containing, in millisecond:
|
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 |
|
No more thread is available in the message exchange acceptor thread pool |
|
No more thread is available to run a message exchange processor |
|
Dedicated alerts
No dedicated alert is available.