[exo-jcr-commits] exo-jcr SVN: r3254 - in jcr/trunk/exo.jcr.docs/exo.jcr.docs.developer/en/src/main/docbook/en-US/modules: kernel and 1 other directory.
do-not-reply at jboss.org
do-not-reply at jboss.org
Wed Oct 6 13:09:15 EDT 2010
Author: nfilotto
Date: 2010-10-06 13:09:15 -0400 (Wed, 06 Oct 2010)
New Revision: 3254
Added:
jcr/trunk/exo.jcr.docs/exo.jcr.docs.developer/en/src/main/docbook/en-US/modules/kernel/rpc-service.xml
Modified:
jcr/trunk/exo.jcr.docs/exo.jcr.docs.developer/en/src/main/docbook/en-US/modules/kernel.xml
Log:
EXOJCR-967: The doc
Added: jcr/trunk/exo.jcr.docs/exo.jcr.docs.developer/en/src/main/docbook/en-US/modules/kernel/rpc-service.xml
===================================================================
--- jcr/trunk/exo.jcr.docs/exo.jcr.docs.developer/en/src/main/docbook/en-US/modules/kernel/rpc-service.xml (rev 0)
+++ jcr/trunk/exo.jcr.docs/exo.jcr.docs.developer/en/src/main/docbook/en-US/modules/kernel/rpc-service.xml 2010-10-06 17:09:15 UTC (rev 3254)
@@ -0,0 +1,211 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<chapter id="Kernel.RPCService">
+ <?dbhtml filename="ch-rpc-service.html"?>
+
+ <title>RPC Service</title>
+
+ <section>
+ <title>Description</title>
+
+ <para>The <emphasis>RPCService</emphasis> is only needed in a cluser
+ environment, it is used to communicate with the other cluster nodes. It
+ allows to execute a command on all the cluster nodes or on the coordinator
+ i.e. the oldest node in the cluster. The <emphasis>RPCService</emphasis>
+ has been designed to rely on JGroups capabilites and should not be used
+ for heavy load. It can be used for example to notify other nodes that
+ something happened or to collect some information from the other
+ nodes.</para>
+
+ <para>The <emphasis>RPCService</emphasis> relies on 2 main interfaces
+ which are the <emphasis>org.exoplatform.services.rpc.RPCService</emphasis>
+ that defines the service itslef and the
+ <emphasis>org.exoplatform.services.rpc.RemoteCommand</emphasis> that
+ defines the command that we can execute on other nodes. The arguments that
+ will be given to the <emphasis>RemoteCommand</emphasis> must be
+ <emphasis>Serializable</emphasis> and its return type also in order to
+ prevent any issue due to the serialization. To prevent to execute any
+ <emphasis>RemoteCommand</emphasis> that could be malicious and to allow to
+ use non <emphasis>Serializable</emphasis> command, you need to register
+ the command first before using it. Since the service will keep only one
+ instance of <emphasis>RemoteCommand</emphasis> per command Id, the
+ implementation of the <emphasis>RemoteCommand</emphasis> must be thread
+ safe.</para>
+
+ <para>To be usable, all the <emphasis>RemoteCommand</emphasis>s must be
+ registered before being used on all the cluster nodes, which means that
+ the command registration must be done in the constructor of your component
+ in other words before that the <emphasis>RPCService</emphasis> is started.
+ If you try to launch a command that has been registered but the
+ <emphasis>RPCService</emphasis> is not yet launched, you will get an
+ <emphasis>RPCException</emphasis> due to an illegal state. This has for
+ consequences that you will be able to execute a command only once your
+ component will be started.</para>
+
+ <para>See an example below:</para>
+
+ <programlisting>public class MyService implements Startable
+{
+ private RPCService rpcService;
+ private RemoteCommand sayHelloCommand;
+
+ public MyService(RPCService rpcService)
+ {
+ this.rpcService = rpcService;
+ // Register the command before that the RPCService is started
+ sayHelloCommand = rpcService.registerCommand(new RemoteCommand()
+ {
+ public Serializable execute(Serializable[] args) throws Throwable
+ {
+ System.out.println("Hello !");
+ return null;
+ }
+
+ public String getId()
+ {
+ return "hello-world-command";
+ }
+ });
+ }
+
+ public void start()
+ {
+ // Since the RPCService is a dependency of RPCService, it will be started before
+ // so I can execute my command
+ try
+ {
+ // This will make all the nodes say "Hello !"
+ rpcService.executeCommandOnAllNodes(sayHelloCommand, false);
+ }
+ catch (SecurityException e)
+ {
+ e.printStackTrace();
+ }
+ catch (RPCException e)
+ {
+ e.printStackTrace();
+ }
+ }
+
+ public void stop()
+ {
+ }
+}</programlisting>
+
+ <para>In the previous example, We register the command
+ <emphasis>sayHelloCommand</emphasis> in the constructor of
+ <emphasis>MyService</emphasis> and we execute this command in the start
+ method.</para>
+
+ <note>
+ <para>We expect to have one <emphasis>RPCService</emphasis> instance per
+ <emphasis>PortalContainer</emphasis> in a portal mode and only one
+ <emphasis>RPCService</emphasis> instance in a standalone mode</para>
+ </note>
+ </section>
+
+ <section>
+ <title>Configuration</title>
+
+ <para>The configuration of the <emphasis>RPCService</emphasis> should be
+ added only in a cluster environment. See below an example of
+ configuration</para>
+
+ <programlisting><configuration>
+....
+ <component>
+ <key>org.exoplatform.services.rpc.RPCService</key>
+ <type>org.exoplatform.services.rpc.impl.RPCServiceImpl</type>
+ <init-params>
+ <value-param>
+ <name>jgroups-configuration</name>
+ <value>classpath:/udp.xml</value>
+ </value-param>
+ <value-param>
+ <name>jgroups-cluster-name</name>
+ <value>RPCService-Cluster</value>
+ </value-param>
+ <value-param>
+ <name>jgroups-default-timeout</name>
+ <value>0</value>
+ </value-param>
+ </init-params>
+ </component>
+...
+</configuration></programlisting>
+
+ <table>
+ <title>Fields description</title>
+
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry><emphasis>jgroups-configuration</emphasis></entry>
+
+ <entry>This is the location of the configuration of jgroups. This
+ parameter is mandatory.</entry>
+ </row>
+
+ <row>
+ <entry><emphasis>jgroups-cluster-name</emphasis></entry>
+
+ <entry>This is the name of the cluster. This parameter is optional
+ and its default value is <emphasis>RPCService-Cluster</emphasis>.
+ Since we could have several instances of the
+ <emphasis>RPCService</emphasis>, the final name will be
+ "${jgroups-cluster-name}-${container-name}"</entry>
+ </row>
+
+ <row>
+ <entry><emphasis>jgroups-default-timeout</emphasis></entry>
+
+ <entry>This is the default timeout to use if the timeout is not
+ given, if no response could be get after this timeout an exception
+ will be thrown. This parameter is optional and its default value
+ is 0 which means that we don't use any timeout by default.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </section>
+
+ <section>
+ <title>The SingleMethodCallCommand</title>
+
+ <para>Most of the time we only need to call a method on a given object,
+ this can be done thanks to the
+ <emphasis>org.exoplatform.services.rpc.SingleMethodCallCommand</emphasis>
+ which is the implementation of a <emphasis>RemoteCommand</emphasis>
+ proposed by default. This command will dynamically execute a method on a
+ given object.</para>
+
+ <programlisting>// Register the command first
+RemoteCommand commandGetName = rpcService.registerCommand(new SingleMethodCallCommand(myService, "getName"));
+// Execute the command on the coordinator
+String name = rpcService.executeCommandOnCoordinator(commandGetName, true);
+// Print the name
+System.out.println("Name : " + name);</programlisting>
+
+ <para>This example:</para>
+
+ <orderedlist>
+ <listitem>
+ <para>Register a <emphasis>SingleMethodCallCommand</emphasis> that
+ will call <emphasis>getName()</emphasis> on the Object
+ <emphasis>myService</emphasis> anytime the command will be
+ executed.</para>
+ </listitem>
+
+ <listitem>
+ <para>Execute the command synchronously on the coordinator, assuming
+ that the same command (with the same id) has already been registered
+ on the coordinator</para>
+ </listitem>
+
+ <listitem>
+ <para>Print the name got from the coordinator</para>
+ </listitem>
+ </orderedlist>
+ </section>
+</chapter>
Modified: jcr/trunk/exo.jcr.docs/exo.jcr.docs.developer/en/src/main/docbook/en-US/modules/kernel.xml
===================================================================
--- jcr/trunk/exo.jcr.docs/exo.jcr.docs.developer/en/src/main/docbook/en-US/modules/kernel.xml 2010-10-06 15:35:09 UTC (rev 3253)
+++ jcr/trunk/exo.jcr.docs/exo.jcr.docs.developer/en/src/main/docbook/en-US/modules/kernel.xml 2010-10-06 17:09:15 UTC (rev 3254)
@@ -56,5 +56,8 @@
<xi:include href="kernel/listener-service.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+ <xi:include href="kernel/rpc-service.xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
</part>
More information about the exo-jcr-commits
mailing list