[jboss-cvs] JBossAS SVN: r93111 - projects/docs/enterprise/5.0/Administration_And_Configuration_Guide/en-US.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Tue Sep 1 22:38:16 EDT 2009
Author: irooskov at redhat.com
Date: 2009-09-01 22:38:16 -0400 (Tue, 01 Sep 2009)
New Revision: 93111
Modified:
projects/docs/enterprise/5.0/Administration_And_Configuration_Guide/en-US/Messaging.xml
projects/docs/enterprise/5.0/Administration_And_Configuration_Guide/en-US/Remoting.xml
Log:
some chapter reviews committed
Modified: projects/docs/enterprise/5.0/Administration_And_Configuration_Guide/en-US/Messaging.xml
===================================================================
--- projects/docs/enterprise/5.0/Administration_And_Configuration_Guide/en-US/Messaging.xml 2009-09-02 01:11:22 UTC (rev 93110)
+++ projects/docs/enterprise/5.0/Administration_And_Configuration_Guide/en-US/Messaging.xml 2009-09-02 02:38:16 UTC (rev 93111)
@@ -39,7 +39,7 @@
<para>JBoss Messaging provides an open source and standards-based messaging platform that brings enterprise-class messaging to the mass market. It also implements a high performance, robust messaging core that is designed to support the largest and most heavily utilized SOA, enterprise service buses (ESBs) and other integration needs ranging from the simplest to the highest network demands.</para>
<para>It allows you to smoothly distribute your application load across your cluster, intelligently balancing and utilizing each nodes CPU cycles, with no single point of failure. This provides a highly scalable and performance implementation for clustering.</para>
<para>JBoss Messaging includes a JMS front-end to deliver messaging in a standards-based format as well as being designed to be able to support other messaging protocols in the future.</para>
-<para>JBoss Messaging is committed to AMQP ( <ulink url="http://www.amqp.org/">AMQP</ulink>)- the new messaging standard from Red Hat and others. Later versions of JBoss Messaging will support AMQP, and JBoss Messaging is focused on becoming the premier AMQP Java broker.</para>
+<!--<para>JBoss Messaging is committed to AMQP ( <ulink url="http://www.amqp.org/">AMQP</ulink>)- the new messaging standard from Red Hat and others. Later versions of JBoss Messaging will support AMQP, and JBoss Messaging is focused on becoming the premier AMQP Java broker.</para>-->
<section><title>Configuring JBoss Messaging</title>
@@ -49,9 +49,9 @@
<section><title>Configuring the SecurityStore</title>
<para>
- SecurityStore is a pluggable object, and it has a default implementation in <filename>messaging-service.xml</filename>.
+ SecurityStore is a pluggable object, and it has a default implementation in <filename>messaging-service.xml</filename>:
</para>
-<programlisting role="XML"><server>
+<!--<programlisting role="XML"><server>
<mbean code="org.jboss.jms.server.security.SecurityMetadataStore"
name="jboss.messaging:service=SecurityStore">
@@ -67,11 +67,17 @@
</mbean>
...
...file truncated..
+</programlisting>-->
+<programlisting>
+<depends optional-attribute-name="SecurityStore" proxy-type="org.jboss.jms.server.SecurityStore">jboss.messaging:service=SecurityStore</depends>
</programlisting>
+<para>
+ This implementation points the ServerPeer to <code>jboss.messaging:service=SecurityStore</code>, which is defined in the <filename>messaging-jboss-beans.xml</filename> file.
+</para>
</section>
<section><title>SecurityStore Attributes</title>
-<para>The following are SecurityStore attributes from the <filename>messaging-service.xml</filename> file above.
+ <para>The following are SecurityStore attributes from the <filename>messaging-jboss-beans.xml</filename> file above.
</para>
<formalpara>
<title>DefaultSecurityConfig</title>
@@ -216,6 +222,11 @@
<para>
The <classname>ServerPeerID</classname> is the unique ID of the server peer that every node you deploy <emphasis>must</emphasis> have. This applies whether the different nodes form a cluster, or are only linked via a message bridge. The ID must be a valid integer.
</para>
+<note>
+ <para>
+ The scope of <classname>ServerPeerID</classname> is currently from 0 to 255. <!--Future releases will see this enlarged to 1023 -->
+ </para>
+</note>
</section>
<!--Up to here for editing EAP 5-->
@@ -307,10 +318,10 @@
</section>
<section><title>SuckerPassword</title>
<para>
- JBoss Messaging internally makes connections between nodes in order to redistribute messages between clustered destinations. These connections are made with the user name of a special reserved user. On this parameter you define the password used as these connections are made. After JBossMessaging 1.4.1.GA you will need to define the Sucker Password on the ServerPeer and on the SecurityMetadataStore.
+ JBoss Messaging internally makes connections between nodes in order to redistribute messages between clustered destinations. These connections are made with the user name of a special reserved user. On this parameter you define the password used as these connections are made. You will need to configure the Sucker password in the SecurityStore <literal>mbean</literal> configuration file (<filename>messaging-jboss-beans.xml</filename>), the ServerPeer Sucker password will be ignored.
</para>
<warning><title>Warning</title>
-<para>This must be specified at install time, or the default password will be used. Any one who then knows the default password will be able to gain access to any destinations on the server. This value MUST be changed at install time.</para>
+<para>This must be specified at install time, or the default password will be used. Any one who then knows the default password will be able to gain access to any destinations on the server. This value <emphasis>must</emphasis> be changed at install time.</para>
</warning>
</section>
<section><title>StrictTCK</title>
@@ -327,7 +338,7 @@
JBoss Messaging provides a message counter for each queue.
</para>
</section>
-<section><title>MessageCountersStatistics</title>
+<section><title>MessageStatistics</title>
<para>
JBoss Messaging provides statistics for each message counter for each queue.
</para>
@@ -431,7 +442,7 @@
This operation returns true if the topic was successfully destroyed. otherwise it returns false.
</para>
</section>
-<section><title>ListMessageCountersHTML</title>
+<section><title>ListMessageCountersAsHTML</title>
<para>
This operation returns message counters in an easy to display HTML format.
</para>
@@ -441,11 +452,6 @@
This operation resets all message counters to zero.
</para>
</section>
-<section><title>ResetAllMesageCounters</title>
- <para>
- This operation resets all message counter histories to zero.
- </para>
-</section>
<section><title>EnableMessageCounters</title>
<para>
This operation enables all message counters for all destinations. Message counters are disabled by default.
@@ -461,7 +467,7 @@
Retrieves a list of the Xids for all transactions currently in a prepared state on the node.
</para>
</section>
-<section><title>ShowPreparedTransactions</title>
+<section><title>ShowPreparedTransactionsAsHTML</title>
<para>
Retrieves a list of the Xids for all transactions currently in a prepared state on the node in an easy to display HTML format.
</para>
Modified: projects/docs/enterprise/5.0/Administration_And_Configuration_Guide/en-US/Remoting.xml
===================================================================
--- projects/docs/enterprise/5.0/Administration_And_Configuration_Guide/en-US/Remoting.xml 2009-09-02 01:11:22 UTC (rev 93110)
+++ projects/docs/enterprise/5.0/Administration_And_Configuration_Guide/en-US/Remoting.xml 2009-09-02 02:38:16 UTC (rev 93111)
@@ -5,160 +5,278 @@
<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 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>
- <para>
- JBoss Remoting can be run as a service within the container with this chapter discussing 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:</para>
- <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>: Uses different protocol transports but the same remoting API. The provided transports are:
- <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>: Uses different data marshallers and unmarshallers to convert the invocation payloads into desired data formats for wire transfer.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis>Pluggable serialization</emphasis>: Uses different serialization implementations for data streams. The provided serialization implementations are:
- <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>: Detects remoting servers as they come on and off line. Provided detection implementations are:
- <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 communication only occurs with servers within specified domains.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis>Callbacks</emphasis>: Receive server callbacks via push and pull models. The pull model specifically allows for persistent stores and memory management.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis>Asynchronous calls</emphasis>: Make asynchronous, or one way, calls to a server.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis>Local invocation</emphasis>: If you are 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 the client, to be loaded from server.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis>Sending of streams</emphasis>: Allows for clients to send input streams to the server, which can be read from the server on demand.
- </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>: Uses the compression marshaller and unmarshaller for the 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>
-<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 these in the issue tracking system at <ulink url="http://jira.jboss.com"/>.
- </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>
+ <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 in the JBoss Enterprise Application Platform</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>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>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