[jboss-cvs] JBossAS SVN: r94532 - projects/docs/community/5/Administration_And_Configuration_Guide/en-US.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Thu Oct 8 19:44:07 EDT 2009
Author: ron_sigal
Date: 2009-10-08 19:44:07 -0400 (Thu, 08 Oct 2009)
New Revision: 94532
Modified:
projects/docs/community/5/Administration_And_Configuration_Guide/en-US/Remoting.xml
Log:
JBAS-6378: Added some additional content about Remoting.
Modified: projects/docs/community/5/Administration_And_Configuration_Guide/en-US/Remoting.xml
===================================================================
--- projects/docs/community/5/Administration_And_Configuration_Guide/en-US/Remoting.xml 2009-10-08 23:41:52 UTC (rev 94531)
+++ projects/docs/community/5/Administration_And_Configuration_Guide/en-US/Remoting.xml 2009-10-08 23:44:07 UTC (rev 94532)
@@ -5,160 +5,281 @@
<chapter id="remoting"><title>Remoting</title>
<para>
- <indexterm><primary>Remoting</primary><secondary>about</secondary></indexterm>
- The main objective of JBoss Remoting is to provide a single API for most network based invocations and related service that uses pluggable transports and data marshallers. The JBoss Remoting API provides the ability for making synchronous and asynchronous remote calls, push and pull callbacks, and automatic discovery of remoting servers. The intention is to allow for the addition of different transports to fit different needs, yet still maintain the same API for making the remote invocations and only requiring configuration changes, not code changes, to fit these different needs.
- </para>
- <para>
- JBossRemoting is a standalone project but is included in the recent releases of the JBoss Application Server including AS5 and can be run as a service within the container as well. This chapter discusses the JBoss Remoting service configurations.
- </para>
+ <indexterm><primary>Remoting</primary><secondary>about</secondary></indexterm>
+ The main objective of JBoss Remoting is to provide a single API for most
+ network based invocations and related services that use pluggable transports
+ and data marshallers. The JBoss Remoting API provides the ability for making
+ synchronous and asynchronous remote calls, push and pull callbacks, and
+ automatic discovery of remoting servers. The intention is to allow for the
+ addition of different transports to fit different needs, yet still maintain
+ the same API for making the remote invocations and only requiring
+ configuration changes, not code changes, to fit these different needs. </para>
-<section><title>Summary of JBoss Remoting Features</title>
- <para>
- The features available with JBoss Remoting are:
- <itemizedlist>
- <listitem>
- <para>
- <emphasis>Server identification</emphasis> – a simple url based identifier which allows for remoting servers to be identified and called upon.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis>Pluggable transports</emphasis> – can use different protocol transports the same remoting API. Provided transports:
- <itemizedlist>
- <listitem>
- <para>
- Socket (SSL Socket)
- </para>
- </listitem>
- <listitem>
- <para>
- RMI (SSL RMI)
- </para>
- </listitem>
- <listitem>
- <para>
- HTTP(S)
- </para>
- </listitem>
- <listitem>
- <para>
- Multiplex (SSL Multiplex)
- </para>
- </listitem>
- <listitem>
- <para>
- Servlet (SSL Servlet)
- </para>
- </listitem>
- <listitem>
- <para>
- BiSocket (SSL BiSocket)
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis>Pluggable data marshallers</emphasis> – can use different data marshallers and unmarshallers to convert the invocation payloads into desired data format for wire transfer.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis>Pluggable serialization</emphasis> - can use different serialization implementations for data streams. Provided serialization implementations:
- <itemizedlist>
- <listitem>
- <para>
- Java serialization
- </para>
- </listitem>
-
- <listitem>
- <para>
- JBoss serialization
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </listitem>
+ <para>Out of the box, Remoting supplies multiple transports (bisocket, http,
+ rmi, socket, servlet, and their ssl enabled counterparts), standard and
+ compressing data marshallers, and a configurable facility for switching
+ between standard jdk serialization and JBoss Serializabion. It is also capable
+ of remote classloading, has extensive facilities for connection failure
+ notification, performs call by reference optimization for client/server
+ invocations collocated in a single JVM, and implements multihomed
+ servers.</para>
+
+ <para>In the Application Server, Remoting supplies the transport layer for the
+ EJB2, EJB3, and Messaging subsystems. In each case, the configuration of
+ Remoting is largely predetermined and fixed, but there are times when it is
+ useful to know how to alter a Remoting configuration. </para>
+
+<section><title>Background</title>
- <listitem>
- <para>
- <emphasis>Automatic discovery</emphasis> – can detect remoting servers as they come on and off line. Provided detection implementations:
- <itemizedlist>
- <listitem>
- <para>
- Multicast
- </para>
- </listitem>
- <listitem>
- <para>
- JNDI
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </listitem>
-
- <listitem>
- <para>
- <emphasis>Server grouping</emphasis> – ability to group servers by logical domains, so only communicate with servers within specified domains.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis>Callbacks</emphasis> – can receive server callbacks via push and pull models. Pull model allows for persistent stores and memory management.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis>Asynchronous calls</emphasis> – can make asynchronous, or one way, calls to server.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis>Local invocation</emphasis> – if making an invocation on a remoting server that is within the same process space, remoting will automatically make this call by reference, to improve performance.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis>Remote classloading</emphasis> – allows for classes, such as custom marshallers, that do not exist within client to be loaded from server.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis>Sending of streams</emphasis> – allows for clients to send input streams to server, which can be read on demand on the server.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis>Clustering</emphasis> - seamless client failover for remote invocations.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis>Connection failure notification</emphasis> - notification if client or server has failed
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis>Data Compression</emphasis> - can use compression marshaller and unmarshaller for compresssion of large payloads.
- </para>
- </listitem>
- </itemizedlist>
+ <para>A Remoting server consists of a Connector, which wraps and configures a
+ transport specific server invoker. A connector is represented by an
+ InvokerLocator string, such as</para>
+ <programlisting>
+ socket://bluemonkeydiamond.com:8888/?timeout=10000&serialization=jboss
+ </programlisting>
+
+ <para>which indicates that a server using the socket transport is accessible
+ at port 8888 of host bluemonkeydiamond.com, and that the server is configured
+ to use a socket timeout of 10000 and to use JBoss Serialization. A Remoting
+ client can use an InvokerLocator to connect to a given server. </para>
- All the features within JBoss Remoting were created with ease of use and extensibility in mind. If you have a suggestion for a new feature or an improvement to a current feature, please log in our issue tracking system at <ulink url="http://jira.jboss.com"/>.
- </para>
+<para>In the Application Server, Remoting servers and clients are created far
+ below the surface and are accessible only through configuration files.
+ Moreover, when a SLSB, for example, is downloaded from the JNDI directory, it
+ comes with a copy of the InvokerLocator, so that it knows how to contact the
+ appropriate Remoting server. <emphasis role="bold">The important fact to note
+ is that, since the server and its clients share the InvokerLocator, the
+ parameters in the InvokerLocator serve to configure both clients and
+ servers.</emphasis></para>
+</section>
+<section>
+ <title>JBoss Remoting Configuration</title>
+
+ <para>There are two kinds of XML files that can be used to create and
+ configure a Remoting Connector. A file with a name of the form *-service.xml
+ can be used to define a Connector as an MBean, and a file of the form
+ *-jboss-beans.xml can be used to define a Connector as a POJO.
+ </para>
+
+ <section>
+ <title>MBeans</title>
+
+ <para>In the HornetQ JMS subsystem, a Remoting server is
+ configured in the file remoting-bisocket-service.xml, which, in abbreviated
+ form, looks like </para>
+
+ <programlisting>
+ <mbean code="org.jboss.remoting.transport.Connector"
+ name="jboss.messaging:service=Connector,transport=bisocket"
+ display-name="Bisocket Transport Connector">
+ <attribute name="Configuration">
+ <config>
+ <invoker transport="bisocket">
+ <attribute name="marshaller" isParam="true">org.jboss.jms.wireformat.JMSWireFormat</attribute>
+ <attribute name="unmarshaller" isParam="true">org.jboss.jms.wireformat.JMSWireFormat</attribute>
+ <attribute name="serverBindAddress">${jboss.bind.address}</attribute>
+ <attribute name="serverBindPort">4457</attribute>
+ <attribute name="callbackTimeout">10000</attribute>
+ ...
+ </invoker>
+ ...
+ </config>
+ </attribute>
+ </mbean>
+ </programlisting>
+
+ <para>This configuration file tells us several facts, including
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>This server uses the bisocket transport;</para>
+ </listitem>
+ <listitem>
+ <para>it runs on port 4457 of host ${jboss.bind.address}; and</para>
+ </listitem>
+ <listitem>
+ <para>HornetQ uses its own marshalling algorithm.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>The InvokerLocator is derived from this file. <emphasis
+ role="bold">The important fact to note is that the attribute "isParam"
+ determines if a parameter is to be included in the
+ InvokerLocator.</emphasis> If "isParam" is omitted (or if it is set to
+ "false"), then the parameter applies only to the server and is not
+ communicated to the client. It follows that the InvokerLocator for this
+ Remoting server is (assuming the value of ${jboss.bind.address} is
+ bluemonkeydiamond.com)</para>
+
+ <programlisting>
+ bisocket://bluemonkeydiamond.com:4457/?marshaller=org.jboss.jms.wireformat.JMSWireFormat&unmarshaller=org.jboss.jms.wireformat.JMSWireFormat
+ </programlisting>
+
+ <para>Note that the parameter "callbackTimeout" is not included in the InvokerLocator.</para>
+
+ </section>
+
+ <section>
+ <title>POJOs</title>
+
+ <para>The same Connector could be configured by way of the
+ <classname>org.jboss.remoting.ServerConfiguration</classname>
+ POJO:</para>
+
+ <programlisting>
+ <bean name="HornetQConnector" class="org.jboss.remoting.transport.Connector">
+ <annotation>@org.jboss.aop.microcontainer.aspects.jmx.JMX(name="jboss.messaging:service=Connector,transport=bisocket",exposedInterface=org.jboss.remoting.transport.ConnectorMBean.class,registerDirectly=true)</annotation>
+ <property name="serverConfiguration"><inject bean="HornetQConfiguration"/></property>
+ </bean>
+
+ <!-- Remoting server configuration -->
+ <bean name="HornetQConfiguration" class="org.jboss.remoting.ServerConfiguration">
+ <constructor>
+ <parameter>bisocket</parameter>
+ </constructor>
+
+ <!-- Parameters visible to both client and server -->
+ <property name="invokerLocatorParameters">
+ <map keyClass="java.lang.String" valueClass="java.lang.String">
+ <entry>
+ <key>serverBindAddress</key>
+ <value>
+ <value-factory bean="ServiceBindingManager" method="getStringBinding">
+ <parameter>HornetQConnector</parameter>
+ <parameter>${host}</parameter>
+ </value-factory>
+ </value>
+ </entry>
+ <entry>
+ <key>serverBindPort</key>
+ <value>
+ <value-factory bean="ServiceBindingManager" method="getStringBinding">
+ <parameter>HornetQConnector</parameter>
+ <parameter>${port}</parameter>
+ </value-factory>
+ </value>
+ </entry>
+ ...
+ <entry><key>marshaller</key> <value>org.jboss.jms.wireformat.JMSWireFormat</value></entry>
+ <entry><key>unmarshaller</key> <value>org.jboss.jms.wireformat.JMSWireFormat</value></entry>
+ </map
+ </property>
+
+ <!-- Parameters visible only to server -->
+ <property name="serverParameters">
+ <map keyClass="java.lang.String" valueClass="java.lang.String">
+ <entry><key>callbackTimeout</key> <value>10000</value></entry>
+ </map>
+ </property>
+
+ ...
+ </bean>
+ </programlisting>
+
+ <para>In this version, the configuration information is expressed in the
+ HornetQConfiguration <classname>ServerConfiguration</classname> POJO, which
+ is then injected into the HornetQConnector
+ <classname>org.jboss.remoting.transport.Connector</classname> POJO. The
+ syntax is that of the Microcontainer, which is beyond the scope of this
+ chapter. One variation from the MBean version is the use of the
+ ServiceBindingManager, which is also beyond the scope of this chapter. Note
+ that the @org.jboss.aop.microcontainer.aspects.jmx.JMX annotation causes the
+ HornetQConnector to be visible as an MBean named
+ "jboss.messaging:service=Connector,transport=bisocket".</para>
+ </section>
+
</section>
+
+<section>
+ <title>Multihomed servers</title>
+
+ <para>Remoting can create servers bound to multiple interfaces. One
+ application of this facility would be binding a server to one interface that
+ faces the internet and another that faces a LAN. For example, the preceding
+ POJO example can be modified by (1) adding POJOs</para>
+
+ <programlisting>
+ <!-- Beans homes1 and homes2 are used to construct a multihome Remoting server. -->
+ <bean name="homes1" class="java.lang.StringBuffer">
+ <constructor>
+ <parameter class="java.lang.String">
+ <value-factory bean="ServiceBindingManager" method="getStringBinding">
+ <parameter>HornetQConnector:bindingHome1</parameter>
+ <parameter>${host}:${port}</parameter>
+ </value-factory>
+ </parameter>
+ </constructor>
+ </bean>
+
+ <bean name="homes2" class="java.lang.StringBuffer">
+ <constructor factoryMethod="append">
+ <factory bean="homes1"/>
+ <parameter>
+ <value-factory bean="ServiceBindingManager" method="getStringBinding">
+ <parameter>HornetQConnector:bindingHome2</parameter>
+ <parameter>!${host}:${port}</parameter>
+ </value-factory>
+ </parameter>
+ </constructor>
+ </bean>
+ </programlisting>
+
+ <para>which results in a StringBuffer with a value something like (according
+ to the ServiceBindingManager configuration values for HornetQConnector:bindingHome1 and HornetQConnector:bindingHome2)
+ "external.acme.com:5555!internal.acme.com:4444", and (2) replacing the
+ "serverBindAddress" and "serverBindPort" parameters with</para>
+
+ <programlisting>
+ <entry>
+ <key>homes</key>
+ <value><value-factory bean="homes2" method="toString"/></value>
+ </entry>
+ </programlisting>
+
+ <para>which transforms the StringBuffer into the String
+ "external.acme.com:5555!internal.acme.com:4444" and injects it into the
+ HornetQConnector. The resulting InvokerLocator will look like</para>
+
+ <programlisting>
+ bisocket://multihome/?homes=external.acme.com:5555!internal.acme.com:4444&marshaller=org.jboss.jms.wireformat.JMSWireFormat&unmarshaller=org.jboss.jms.wireformat.JMSWireFormat
+ </programlisting>
+</section>
<section>
- <title>JBoss Remoting Configuration in the JBoss Application Server</title>
- <para>
- As indicated earlier in this chapter, JBoss Remoting manages synchronous and asynchronous remote calls, push and pull callbacks, and automatic discovery of remoting servers. You can configure JBoss Remoting through the JBoss Messaging service configuration file <filename>JBOSS_HOME/server/<your_configuration>/deploy/messaging/remoting-service.xml</filename>.
- </para>
+ <title>Address translation</title>
+
+ <para>Sometimes a server must be accessed through an address translating
+ firewall, and a Remoting server can be configured with both a binding
+ address/port and an address/port to be used by a client. Two more parameters
+ are used: "clientConnectAddress" and "clientConnectPort". The
+ "serverBindAddress" and "serverBindPort" values are used to create the server,
+ and the values of "clientConnectAddress" and "clientConnectPort" are used in
+ the InvokerLocator, which tells the client where the server is. There is also
+ an analogous "connecthomes" parameter for multihome servers. In this case,
+ "homes" is used to configure the server, and "connecthomes" tells the client
+ where the server is.</para>
+</section>
+
+<section>
+ <title>Where are they now?</title>
+
+ <para>The actual Remoting configuration files for the supported subsystems are
+ as follows:</para>
+
+ <para>EJB2: ${JBOSS_HOME}/server/${CONFIG}/deploy/remoting-jboss-beans.xml</para>
+ <para>EJB3: ${JBOSS_HOME}/server/${CONFIG}/deploy/ejb3-connectors-jboss-beans.xml</para>
+ <para>HornetQ: ${JBOSS_HOME}/server/${CONFIG}/deploy/messaging/remoting-bisocket-service.xml</para>
+</section>
+<section>
+ <title>Further information.</title>
+
+ <para>Additional details may be found in the Remoting Guide at <ulink
+ url="http://www.jboss.org/jbossremoting/docs/guide/2.5/html/index.html">
+ http://www.jboss.org/jbossremoting/docs/guide/2.5/html/index.html</ulink>.</para>
+
</section>
-
</chapter>
More information about the jboss-cvs-commits
mailing list