{section}
{column}

h1. Introduction

{warning}This version must be installed on Petals ESB 5.0.0+{warning}

h2. Features

{multi-excerpt-include:Petals-SE-rmi|name=features|nopanel=true}

h2. Recommended usage

{multi-excerpt-include:Petals-SE-rmi|name=recommended-usage|nopanel=true}

{column}

{column:width=40%}
{panel:title=Table of contents}{toc:outline=true}{panel}
{panel:title=Contributors}{contributors:order=name|mode=list|showAnonymous=true|showCount=true|showLastTime=true}{panel}
{column}
{section}

h1. 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.

{note}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.{note}

h1. 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.

h2. 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:
{code:java}
ComponentContexFactoryLocator ccl = new ComponentContexFactoryLocator("192.168.1.150", 1099, "RMIComponentContext");
{code}

{note}To avoid some errors, you must inserted this line code below at the beginning of the program
{code:java}
System.setProperty("com.sun.xml.namespace.QName.useCompatibleSerialVersionUID", "1.0");
{code}
{note}

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

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

h2. 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()}}.

h2. 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:
{code:java}
// 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);
{code}

h2. 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:
{code:java}
// 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();
{code}

The following code snippet shows an synchronous message exchange between the client and a provider:
{code:java}
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);
}
{code}

{note}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.{note}

h1. 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.

h2. Configuration

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

{center}{*}Configuration of the SE RMI component*{center}
{table-plus}
|| {color:#333333}Parameter{color} || {color:#333333}Description{color} || {color:#333333}Default{color} || {color:#333333}Required{color} || Scope ||
| port | The port used by the RMI component to contact the RMI registry. | {center}1099{center} | {center}No{center} | {center}Installation{center} |
| host | The hostname where the RMI registry is running. | {center}-{center} | {center}No{center} | {center}Installation{center} |
| 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}}' | {center}true{center} | {center}No{center} | {center}Installation{center} |
| 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. | {center}RMIComponentContext{center} | {center}No{center} | {center}Installation{center} |
{table-plus}

*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.

h2. 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: