[jboss-cvs] JBossRemoting/docs/guide/en ...
Ron Sigal
ron_sigal at yahoo.com
Wed Aug 2 22:23:39 EDT 2006
User: rsigal
Date: 06/08/02 22:23:39
Modified: docs/guide/en chap5.xml
Log:
JBREM-559: Added a general discussion about configuration, both programmatic and declarative, on the client and server side, incorporating existing material about configuration by xml documents. Also, removed the section called "Programmatic configuration".
Revision Changes Path
1.8 +398 -128 JBossRemoting/docs/guide/en/chap5.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: chap5.xml
===================================================================
RCS file: /cvsroot/jboss/JBossRemoting/docs/guide/en/chap5.xml,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -b -r1.7 -r1.8
--- chap5.xml 2 Aug 2006 07:39:47 -0000 1.7
+++ chap5.xml 3 Aug 2006 02:23:39 -0000 1.8
@@ -11,12 +11,27 @@
configurations.</para>
<section>
- <title>General Connector and Invoker configuration</title>
+ <title>General transport configuration</title>
- <para>The server invoker and invocation handlers are configured via the
- Connector. Only one invoker can be declared per connector (multiple
- InvokerLocator attributes or invoker elements within the Configuration
- attribute is not permitted). Although declaring an invocation handler is
+ <para> Remoting offers a
+ variety of ways of configuring transports on the server side and client
+ side. This section presents an overview, and the rest of the chapter
+ elaborates the material presented here. For easy reference the
+ configuration parameters discussed throughout the chapter are gathered
+ together at the end of the chapter in section <xref
+ linkend="section-configuration"/></para>
+
+ <section>
+ <title>Server side configuration</title>
+
+ <para>The heart of the server side is the
+ <classname>Connector</classname>, and it is through the
+ <classname>Connector</classname> that
+ the server side of a transport is configured.
+ The central goals of configuration on the server side are to establish a
+ server invoker and supply it with a set of invocation handlers.
+ Only one invoker can be declared per <classname>Connector</classname>.
+ Although declaring an invocation handler is
not required, it should only be omitted in the case of declaring a
callback server that will not receive direct invocations, but only
callback messages. Otherwise client invocations can not be processed.
@@ -24,6 +39,171 @@
remoting framework for a user to implement and will be what the remoting
framework calls upon when receiving invocations.</para>
+ <para>There are two general approaches to server side configuration:
+ programmatic and declarative. A variety of programmatic techniques work
+ in any environment, including the JBoss Application Server (JBossAS).
+ Moreover, JBossAS adds the option of declarative configuration. In
+ particular, the SARDeployer (see The JBoss 4 Application Server Guide on
+ the labs.jboss.org web site) can read information from a *-service.xml
+ file and use it to configure MBeans such as
+ <classname>Connector</classname>s. </para>
+
+ <section>
+ <title>Programmatic configuration.</title>
+
+ <para>The simplest way to configure a <classname>Connector</classname>
+ is to pass an <classname>InvokerLocator</classname>
+ to a <classname>Connector</classname> constructor. For example, the
+ code fragment</para>
+
+ <programlisting>
+ String locatorURI = "socket://test.somedomain.com:8084";
+ String params = "/?clientLeasePeriod=10000&timeout=120000";
+ locatorURI += params;
+ InvokerLocator locator = new InvokerLocator(locatorURI);
+ Connector connector = new Connector(locator);
+ connector.create();
+ SampleInvocationHandler invocationHandler = new SampleInvocationHandler();
+ connector.addInvocationHandler("sample", invocationHandler);
+ connector.start();
+ </programlisting>
+
+ <para>creates a server invoker based on the socket transport, directs
+ it to listen for invocations on port 8084 of host test.somedomain.com,
+ and passes two configuration parameters, "clientLeasePeriod" and
+ "timeout". It also supplies the server invoker with an invocation
+ handler.
+ </para>
+
+ <para>One limitation of the <classname>InvokerLocator</classname> is
+ that it can only represent string values. An alternative that
+ overcomes this limitation is to pass some or all of the parameters to
+ the <classname>Connector</classname> by way of a configuration map.
+ The following code fragment accomplishes all that the
+ previous fragment does, but it passes one parameter by way of the
+ <classname>InvokerLocator</classname> and passes the other by way of a
+ configuration map. It also passes in a non-string object, a
+ <classname>ServerSocketFactory</classname>:</para>
+
+ <programlisting>
+ String locatorURI = "socket://test.somedomain.com:8084";
+ String params = "/?clientLeasePeriod=10000";
+ locatorURI += params;
+ InvokerLocator locator = new InvokerLocator(locatorURI);
+ HashMap config = new HashMap();
+ config.put(ServerInvoker.TIMEOUT, 120000);
+ config.put(ServerInvoker.SERVER_SOCKET_FACTORY, new MyServerSocketFactory());
+ Connector connector = new Connector(locator, config);
+ connector.create();
+ SampleInvocationHandler invocationHandler = new SampleInvocationHandler();
+ connector.addInvocationHandler("sample", invocationHandler);
+ connector.start();
+ </programlisting>
+
+ <para>Note that the value of <code>ServerInvoker.TIMEOUT</code> is
+ "timeout", and the value of
+ <code>ServerInvoker.SERVER_SOCKET_FACTORY</code> is
+ "serverSocketFactory". These configuration map keys are discussed
+ throughout the chapter and accumulated in section <xref
+ linkend="section-configuration"/>. Also, server socket factory
+ configuration is covered in
+ <xref linkend="section-socket-factories"/>.</para>
+
+ <para>A third programmatic option is available for those configuration
+ properties which happen to be server invoker MBean properties. In the
+ following fragment, the server invoker is obtained from the
+ <classname>Connector</classname> and a
+ <classname>ServerSocketFactory</classname> is passed to it by way of a
+ setter method:</para>
+
+ <programlisting>
+ String locatorURI = "socket://test.somedomain.com:8084";
+ String params = "/?clientLeasePeriod=10000";
+ locatorURI += params;
+ InvokerLocator locator = new InvokerLocator(locatorURI);
+ HashMap config = new HashMap();
+ config.put(ServerInvoker.TIMEOUT, 120000);
+ Connector connector = new Connector(locator, config);
+ connector.create();
+ ServerInvoker serverInvoker = connector.getServerInvoker();
+ ServerSocketFactory ssf = new MyServerSocketFactory();
+ serverInvoker.setServerSocketFactory(ssf);
+ SampleInvocationHandler invocationHandler = new SampleInvocationHandler();
+ connector.addInvocationHandler("sample", invocationHandler);
+ connector.start();
+ </programlisting>
+
+ <para><emphasis role="bold">Note.</emphasis> The
+ <classname>Connector</classname> creates the server invoker during the
+ call to <methodname>Connector.create()</methodname>, so this option
+ only works after that method has been called. Also, depending on the
+ parameter and the transport, this option may or may not be effective
+ after the call to <methodname>Connector.start()</methodname>, which
+ calls <methodname>start()</methodname> on the server invoker.
+ </para>
+
+ <para>A fourth option, which exists primarily to support the
+ declarative mode of configuration presented below, is to pass an XML
+ document to the <classname>Connector</classname>. The following
+ fragment duplicates the behavior of the first and second examples
+ above.</para>
+
+ <programlisting>
+ HashMap config = new HashMap();
+ config.put(ServerInvoker.TIMEOUT, 120000);
+ Connector connector = new Connector(config);
+
+ // Set xml configuration element.
+ StringBuffer buf = new StringBuffer();
+ buf.append("<?xml version=\"1.0\"?>\n");
+ buf.append("<config>");
+ buf.append(" <invoker transport=\"socket\">");
+ buf.append(" <attribute name=\"serverBindAddress\">test.somedomain.com</attribute>");
+ buf.append(" <attribute name=\"serverBindPort\">8084</attribute>");
+ buf.append(" <attribute name=\"clientLeasePeriod\">10000</attribute>");
+ buf.append(" </invoker>");
+ buf.append(" <handlers>");
+ buf.append(" <handler subsystem=\"mock\">");
+ buf.append(" org.jboss.remoting.transport.mock.SampleInvocationHandler");
+ buf.append(" </handler>");
+ buf.append(" </handlers>");
+ buf.append("</config>");
+ ByteArrayInputStream bais = new ByteArrayInputStream(buf.toString().getBytes());
+ Document xml = DocumentBuilderFactory.newInstance().newDocumentBuilder().parse(bais);
+ connector.setConfiguration(xml.getDocumentElement());
+
+ connector.create();
+ connector.start();
+ </programlisting>
+
+ <para>Note that there is no <classname>InvokerLocator</classname> in
+ this example. If the <classname>Connector</classname> gets an
+ <classname>InvokerLocator</classname>, it ignores the presence of the
+ xml document. Note also that this method only supports the use of
+ string values, so it is necessary to include the fully qualified name
+ of the invocation handler, from which the handler is created by
+ calling the default constructor.
+ </para>
+
+ <para>An example of this option in use can be found in
+ <classname>org.jboss.test.remoting.configuration.SocketClientConfigurationTestCase</classname>.
+ </para>
+ </section>
+
+ <section>
+ <title>Declarative configuration</title>
+
+ <para>The configuration option discussed at the end of the previous
+ section, passing an XML document to the
+ <classname>Connector</classname>, works in conjunction with the service
+ archive deployer (SARDeployer) inside the JBoss Application Server to
+ allow declarative configuration on the server side. In particular, the
+ SARDeployer reads XMl documents containing MBean descriptors from files
+ whose name has the form "*-service.xml". When it sees a descriptor for
+ a <classname>Connector</classname> MBean, it passes the
+ descriptor's <code><config></code> element to a newly created
+ <classname>Connector</classname>.</para>
+
<para>There are two ways in which to specify the server invoker
configuration via a service xml file. The first is to specify just the
InvokerLocator attribute as a sub-element of the Connector MBean. For
@@ -118,7 +298,7 @@
<programlisting> <attribute name="InvokerLocator"><![CDATA[socket://test.somedomain.com:8084/<emphasis
role="bold">foo/bar</emphasis>]]></attribute>
-</programlisting>
+ </programlisting>
<para>To include the path using the Configuration attribute, can include
a specific 'path' attribute. So the same InvokerLocator can be expressed
@@ -133,12 +313,101 @@
<emphasis role="bold"><attribute name="path">foo/bar</attribute></emphasis>
</invoker>
...
-</programlisting>
+ </programlisting>
<para>Note: The value for the 'path' attribute should NOT start or end
with a / (slash).</para>
</section>
+ </section>
+
+ <section>
+ <title>Client side configuration</title>
+
+ <para>Invoker configuration on the client side parallels configuration on
+ the server side, with the exception that (1) it operates in a simpler
+ environment (in particular, it does not assume the presence of an
+ MBeanServer) and (2) it does not support a declarative option. However,
+ it does support versions of the first three server side programmatic
+ options, with the <classname>Client</classname> class playing the central
+ role played by the <classname>Connector</classname> class on the server
+ side.</para>
+
+ <para>Again, the most straightforward form of configuration is to put the
+ configuration parameters on the <classname>InvokerLocator</classname>.
+ For example, the fragment
+ </para>
+
+ <programlisting>
+ String locatorURI = "socket://test.somedomain.com:8084";
+ String params = "/?clientMaxPoolSize=10&timeout=360000";
+ locatorURI += params;
+ InvokerLocator locator = new InvokerLocator(locatorURI);
+ Client client = new Client(locator);
+ client.connect();
+ </programlisting>
+
+ <para>creates a <classname>Client</classname> using the socket transport
+ to connect to a server on host test.somedomain.com, listening on port
+ 8084. It also passes in two parameters, "clientMaxPoolSize" and
+ "timeout", that will be used by the client invoker.
+ </para>
+
+ <para>It is also possible to use configuration maps on the client side.
+ The following code fragment accomplishes all that the previous fragment
+ does, but it passes one parameter by way of the
+ <classname>InvokerLocator</classname> and passes the other by way of a
+ configuration map. It also passes in a non-string object, a
+ <classname>SocketFactory</classname>: </para>
+
+ <programlisting>
+ String locatorURI = "socket://test.somedomain.com:8084";
+ String params = "/?clientMaxPoolSize=10";
+ locatorURI += params;
+ InvokerLocator locator = new InvokerLocator(locatorURI);
+ HashMap config = new HashMap();
+ config.put(ServerInvoker.TIMEOUT, 360000);
+ config.put(Remoting.CUSTOM_SOCKET_FACTORY, new MySocketFactory());
+ Client client = new Client(locator, config);
+ client.connect();
+ </programlisting>
+
+ <para>Note that the value of <code>ServerInvoker.TIMEOUT</code> is
+ "timeout", and the value of <code>Remoting.CUSTOM_SOCKET_FACTORY</code>
+ is "customSocketFactory". These configuration map keys are discussed
+ throughout the chapter and accumulated in section <xref
+ linkend="section-configuration"/>. Also, socket factory configuration is
+ covered in <xref linkend="section-socket-factories"/>.</para>
+
+ <para>Finally, a third programmatic option is available for those
+ configuration properties which happen to be client invoker MBean
+ properties. In the following fragment, the client invoker is obtained
+ from the <classname>Client</classname> and a
+ <classname>SocketFactory</classname> is passed to it by way of a setter
+ method:</para>
+
+ <programlisting>
+ String locatorURI = "socket://test.somedomain.com:8084";
+ String params = "/?clientMaxPoolSize=10";
+ locatorURI += params;
+ InvokerLocator locator = new InvokerLocator(locatorURI);
+ HashMap config = new HashMap();
+ config.put(ServerInvoker.TIMEOUT, 360000);
+ Client client = new Client(locator, config);
+ client.connect();
+ SocketFactory sf = new MySocketFactory();
+ ClientInvoker clientInvoker = client.getInvoker();
+ clientInvoker.setSocketFactory(sf);
+ </programlisting>
+
+ <para><emphasis role="bold">Note.</emphasis> The
+ <classname>Client</classname> creates the client invoker during the call
+ to <methodname>Client.connect()</methodname>, so this option only works
+ after that method has been called. </para>
+ </section>
+
+ </section>
+
<section>
<title>Handlers</title>
@@ -2633,6 +2902,7 @@
</section>
</section>
+ <!--
<section>
<title>Programmatic configuration</title>
@@ -2649,7 +2919,7 @@
from there with <code><invoker></code> sub-element and so on. An
example of this can be found in
org.jboss.test.remoting.configuration.SocketClientConfigurationTestCase.</para>
- </section>
+ </section> -->
<section id="section-socket-factories"
xreflabel="Socket factories and server socket factories">
@@ -4082,7 +4352,7 @@
</section>
</section>
- <section>
+ <section id="section-configuration" xreflabel="Configuration by properties">
<title>Configuration by properties</title>
<para>This section covers configuration properties by constant values
More information about the jboss-cvs-commits
mailing list