[jboss-cvs] JBoss Messaging SVN: r8051 - projects/enterprise/EAP/trunk/5.x/en-US.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Mon May 31 03:26:13 EDT 2010
Author: jaredmorgs
Date: 2010-05-31 03:26:12 -0400 (Mon, 31 May 2010)
New Revision: 8051
Modified:
projects/enterprise/EAP/trunk/5.x/en-US/Configuration.xml
projects/enterprise/EAP/trunk/5.x/en-US/JBoss_Messaging_User_Guide.xml
Log:
Started to change Chapter 6 and chunk it down a bit better. Removed a lot of sections and converted them to varlists
Modified: projects/enterprise/EAP/trunk/5.x/en-US/Configuration.xml
===================================================================
--- projects/enterprise/EAP/trunk/5.x/en-US/Configuration.xml 2010-05-31 06:19:14 UTC (rev 8050)
+++ projects/enterprise/EAP/trunk/5.x/en-US/Configuration.xml 2010-05-31 07:26:12 UTC (rev 8051)
@@ -138,328 +138,338 @@
</mbean>
]]></programlisting>
- <section id="conf.serverpeer.attributes">
- <title>ServerPeer attributes</title>
- <para>
+ </section>
+ <section id="conf.serverpeer.attributes">
+ <title>ServerPeer attributes</title>
+ <para>
This section discusses the <literal>ServerPeer</literal> managed bean attributes.
</para>
- <variablelist>
- <varlistentry>
- <term>ServerPeerID</term>
- <listitem>
- <para>
+ <variablelist>
+ <varlistentry>
+ <term>ServerPeerID</term>
+ <listitem>
+ <para>
The unique identifier of the <literal>ServerPeer</literal>. Each node deployed must have a unique identifier, whether the nodes form a cluster or are linked by a message bridge. The identifier must be a valid integer.
</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>DefaultQueueJNDIContext</term>
- <listitem>
- <para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>DefaultQueueJNDIContext</term>
+ <listitem>
+ <para>
The default JNDI context to be used when binding queues. The default value is <literal>/queue</literal>.
</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>DefaultTopicJNDIContext</term>
- <listitem>
- <para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>DefaultTopicJNDIContext</term>
+ <listitem>
+ <para>
The default JNDI context to be used when binding topics. The default value is <literal>/topic</literal>.
</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>PostOffice</term>
- <listitem>
- <para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PostOffice</term>
+ <listitem>
+ <para>
The post office used by the <literal>ServerPeer</literal>. You will not normally need to edit this attribute. The post office routes messages to queues and maintains the mapping between queues and addresses.
</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>DefaultDLQ</term>
- <listitem>
- <para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>DefaultDLQ</term>
+ <listitem>
+ <para>
The default DLQ (Dead Letter Queue) that the server uses for destinations. You can override the DLQ on a per-destination basis. (For more information, see the configuration information for the destination managed bean.) A DLQ is a destination for messages that the server has failed to deliver more than a certain number of times. If the DLQ is not specified, the message will be removed after the maximum number of delivery attempts. You can specify a global default for the maximum number of delivery attempts with the <varname>DefaultMaxDeliveryAttempts</varname> attribute, or set the maximum individually on a per-destination basis.
</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>DefaultMaxDeliveryAttempts</term>
- <listitem>
- <para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>DefaultMaxDeliveryAttempts</term>
+ <listitem>
+ <para>
The global default for the maximum number of times delivery will be attempted for a message before the message is removed or sent to the DLQ, if configured. The default value is <literal>10</literal>. You can override this value on a per-destination basis.
</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>DefaultExpiryQueue</term>
- <listitem>
- <para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>DefaultExpiryQueue</term>
+ <listitem>
+ <para>
The default expiry queue that the <literal>ServerPeer</literal> will use for destinations. You can override this value on a per-destination basis, as seen in the section on destination managed bean configuration. An expiry queue holds messages that have expired. Message expiry is determined by the value of <literal>Message::getJMSExpiration()</literal>. If the expiry queue is not specified, the message will be deleted when it expires.
</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>DefaultRedeliveryDelay</term>
- <listitem>
- <para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>DefaultRedeliveryDelay</term>
+ <listitem>
+ <para>
This attribute lets you delay a redelivery attempt, which helps to prevent thrashing delivery-failure. The default value is <literal>0</literal> (that is, no delay). You can override this value on a per-destination basis.
</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>MessageCounterSamplePeriod</term>
- <listitem>
- <para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>MessageCounterSamplePeriod</term>
+ <listitem>
+ <para>
This attribute defines the period of time between the server's queries to the queue for queue statistics. The default value is <literal>10000</literal> milliseconds.
</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>FailoverStartTimeout</term>
- <listitem>
- <para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>FailoverStartTimeout</term>
+ <listitem>
+ <para>
The longest period (in milliseconds) that the client will wait for failover to begin on the server side when a problem is detected. The default value is <literal>60000</literal> (one minute).
</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>FailoverCompleteTimeout</term>
- <listitem>
- <para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>FailoverCompleteTimeout</term>
+ <listitem>
+ <para>
The longest period (in milliseconds) that the client will wait for failover to complete on the server side once failover has been initiated. The default value is <literal>300000</literal> (five minutes).
</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>DefaultMessageCounterHistoryDayLimit</term>
- <listitem>
- <para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>DefaultMessageCounterHistoryDayLimit</term>
+ <listitem>
+ <para>
JBoss Messaging provides a message counter history, which shows the number of messages arriving on each queue over a certain number of days. This attribute represents the maximum number of days for which to store message counter history. You can override this value on a per-destination.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>ClusterPullConnectionFactory</term>
- <listitem>
- <para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>ClusterPullConnectionFactory</term>
+ <listitem>
+ <para>
The connection factory used to pull, or suck, messages between queues. You can omit this attribute to disable message sucking while retaining failover.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>DefaultPreserveOrdering</term>
- <listitem>
- <para>When <literal>true</literal>, JMS ordering is preserved in the cluster. See the Cluster Configuration section for more detail. The default value is <literal>false</literal>.
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>DefaultPreserveOrdering</term>
+ <listitem>
+ <para>When <literal>true</literal>, JMS ordering is preserved in the cluster. See the Cluster Configuration section for more detail. The default value is <literal>false</literal>.
</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>RecoverDeliveriesTimeout</term>
- <listitem>
- <para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>RecoverDeliveriesTimeout</term>
+ <listitem>
+ <para>
When failover occurs, messages that have been delivered will be stored while the clients reconnect. If the clients do not reconnect (for example, if the client is dead), these messages will eventually time out and be added to the queue. This attribute sets the period before timeout in milliseconds. The default value is <literal>300000</literal> (five minutes).
</para>
- </listitem>
- </varlistentry>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>EnableMessageCounters</term>
+ <listitem>
+ <para>
+ When set to <literal>true</literal>, enables message counters upon server start.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>SuckerPassword</term>
+ <listitem>
+ <para>
+ JBoss Messaging internally creates connections between nodes to redistribute messages between clustered destinations. These connections are created with a special, reserved username. This attribute defines the password to use when creating these connections.
+ </para>
+ <para>
+ For versions of JBoss Messaging later than 1.4.1.GA, you must define the <varname>SuckerPassword</varname> on the <literal>SecurityMetadataStore</literal>.
+ </para>
+ <warning>
+ <para>
+ The <varname>SuckerPassword</varname> must be changed at install time, or the default password will be used, giving any user who knows the default password access to any destination on the server.
+ </para>
+ </warning>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>SuckerConnectionRetryTimes</term>
+ <listitem>
+ <para>
+ This is the maximum number of times a sucker's connection is permitted to retry in the event of a failure. The default value is <literal>-1</literal> which represents "retry indefinitely".</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>SuckerConnectionRetryInterval</term>
+ <listitem>
+ <para>This is the interval in milliseconds between each retry of the failed sucker's
+ connection. The default value is <literal>5000</literal>.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>StrictTCK</term>
+ <listitem>
+ <para>
+ To enable strict JMS Technology Compatibility Kit (TCK) semantics, set this attribute to <literal>true</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Destinations</term>
+ <listitem>
+ <para>
+ Returns a list of the destinations (queues and topics) currently deployed.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>MessageCounters</term>
+ <listitem>
+ <para>
+ A message counter for a particular queue.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>MessageStatistics</term>
+ <listitem>
+ <para>
+ Statistics about each message counter for each queue.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>SupportsFailover</term>
+ <listitem>
+ <para>
+ When this attribute is <literal>false</literal>, server-side failover does not occur when a node crashes in a cluster.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PersistenceManager</term>
+ <listitem>
+ <para>
+ The persistence manager used by the <literal>ServerPeer</literal>. (You will not normally need to change this attribute.)
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>JMSUserManager</term>
+ <listitem>
+ <para>
+ The JMS user manager used by the <literal>ServerPeer</literal>. (You will not normally need to change this attribute.)
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>SecurityStore</term>
+ <listitem>
+ <para>
+ The pluggable <literal>SecurityStore</literal>. If you redefine this attribute, remember that you will need to authenticate the <literal>MessageSucker</literal> user (<literal>JBM.SUCKER</literal>) with all special permissions required by clustering.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <section id="conf.serverpeer.operations">
+ <title>Managed Beans in the ServerPeer</title>
+ <para>The following managed beans are available for the ServerPeer managed bean:</para>
+ <variablelist>
<varlistentry>
- <term>EnableMessageCounters</term>
+ <term>DeployQueue</term>
<listitem>
+ <para>Used to programmatically deploy a queue. If the queue exists but is undeployed, it will be deployed. Otherwise, it is created and deployed.
+ </para>
<para>
- When set to <literal>true</literal>, enables message counters upon server start.</para>
+ The <varname>name</varname> parameter matches a destination to deploy.
+ </para>
+ <para>The optional <varname>jndiName</varname> parameter represents the full JNDI name of the location to which a destination will be bound. If this is not specified, the destination will be bound in <literal><DefaultQueueJNDIContext>/<name></literal>.
+ </para>
+ <para>There are two overloaded versions of this operation. The first deploys the destination with default paging parameters. The second deploys the destination with the paging parameters specified. For more information about paging parameters, see the section on Configuring Destinations.
+ </para>
</listitem>
</varlistentry>
<varlistentry>
- <term>SuckerPassword</term>
+ <term>UndeployQueue</term>
<listitem>
- <para>
- JBoss Messaging internally creates connections between nodes to redistribute messages between clustered destinations. These connections are created with a special, reserved username. This attribute defines the password to use when creating these connections.
- </para>
- <para>
- For versions of JBoss Messaging later than 1.4.1.GA, you must define the <varname>SuckerPassword</varname> on the <literal>SecurityMetadataStore</literal>.
- </para>
- <warning>
- <para>
- The <varname>SuckerPassword</varname> must be changed at install time, or the default password will be used, giving any user who knows the default password access to any destination on the server.
+ <para>Used to programmatically undeploy a queue. Queues are not removed from persistent storage. This operation returns <literal>true</literal> if the queue is successfully undeployed. Otherwise, it returns <literal>false</literal>.
</para>
- </warning>
</listitem>
</varlistentry>
<varlistentry>
- <term>SuckerConnectionRetryTimes</term>
+ <term>DestroyQueue</term>
<listitem>
- <para>
- This is the maximum number of times a sucker's connection is permitted to retry in the event of a failure. The default value is <literal>-1</literal> which represents "retry indefinitely".</para>
+ <para>Used to programmatically destroy a queue. Queues are undeployed and all of their data is removed from the database and destroyed.
+ </para>
+ <warning>
+ <para>Exercise caution when using this method, since it will delete all data for the queue.
+ </para>
+ </warning>
+ <para>This operation returns <literal>true</literal> if the queue was destroyed successfully. Otherwise, it returns <literal>false</literal>.
+ </para>
</listitem>
</varlistentry>
<varlistentry>
- <term>SuckerConnectionRetryInterval</term>
+ <term>DeployTopic</term>
<listitem>
- <para>This is the interval in milliseconds between each retry of the failed sucker's
- connection. The default value is <literal>5000</literal>.</para>
+ <para>Used to programmatically deploy a topic. There are two overloaded versions of this operation. The first deploys already existing topics with the default paging parameters. The second creates and deploys topics with specified paging parameters. See the section on Configuring Destinations for more information.
+ </para>
+ <para>The <varname>name</varname> parameter represents the name of the destination to deploy.
+ </para>
+ <para>The <varname>jndiName</varname> represents the full JNDI name of the location to which the destination will be bound. If this is not specified, the destination will be bound in <literal><DefaultTopicJNDIContext>/<name></literal>.
+ </para>
</listitem>
</varlistentry>
<varlistentry>
- <term>StrictTCK</term>
+ <term>UndeployTopic</term>
<listitem>
- <para>
- To enable strict JMS Technology Compatibility Kit (TCK) semantics, set this attribute to <literal>true</literal>.
- </para>
+ <para>Used to programmatically undeploy a topic. Topics are undeployed, but not removed from persistent storage. This operation returns <literal>true</literal> if the topic is undeployed successfully. Otherwise, <literal>false</literal> is returned.
+ </para>
</listitem>
</varlistentry>
<varlistentry>
- <term>Destinations</term>
+ <term>DestroyTopic</term>
<listitem>
- <para>
- Returns a list of the destinations (queues and topics) currently deployed.
- </para>
+ <para>Used to programmatically destroy a topic. Topics are undeployed and all data is removed from the database and destroyed. This operation returns <literal>true</literal> if the topic is successfully destroyed. Otherwise, it returns <literal>false</literal>.
+ </para>
+ <warning>
+ <para>
+ Exercise caution when using this method, since it will delete all data for the topic.
+ </para>
+ </warning>
</listitem>
</varlistentry>
<varlistentry>
- <term>MessageCounters</term>
+ <term>ListMessageCountersHTML</term>
<listitem>
- <para>
- A message counter for a particular queue.
- </para>
+ <para>Returns message counters in a simply-displayed HTML format.
+ </para>
</listitem>
</varlistentry>
<varlistentry>
- <term>MessageStatistics</term>
+ <term>ResetAllMesageCounters</term>
<listitem>
- <para>
- Statistics about each message counter for each queue.
- </para>
+ <para>Resets all message counters to zero.</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>SupportsFailover</term>
+ <term>EnableMessageCounters</term>
<listitem>
- <para>
- When this attribute is <literal>false</literal>, server-side failover does not occur when a node crashes in a cluster.
- </para>
+ <para>Enables all message counters for all destinations. Message counters are disabled by default.</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>PersistenceManager</term>
+ <term>DisableMessageCounters</term>
<listitem>
- <para>
- The persistence manager used by the <literal>ServerPeer</literal>. (You will not normally need to change this attribute.)
- </para>
+ <para>Disables all message counters for all destinations. Message counters are disabled by default.</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>JMSUserManager</term>
+ <term>RetrievePreparedTransactions</term>
<listitem>
- <para>
- The JMS user manager used by the <literal>ServerPeer</literal>. (You will not normally need to change this attribute.)
- </para>
+ <para>Retrieves a list of the XIDs for all transactions currently in a prepared state on the node.</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>SecurityStore</term>
+ <term>ShowPreparedTransactions</term>
<listitem>
- <para>
- The pluggable <literal>SecurityStore</literal>. If you redefine this attribute, remember that you will need to authenticate the <literal>MessageSucker</literal> user (<literal>JBM.SUCKER</literal>) with all special permissions required by clustering.
- </para>
+ <para>Retrieves a list of the XIDs for all transactions currently in a prepared state on the node in an easily-displayed HTML format.</para>
</listitem>
</varlistentry>
</variablelist>
- <section id="conf.serverpeer.operations">
- <title>Managed Beans in the ServerPeer</title>
- <section id="conf.serverpeer.operations.deployQueue">
- <title>DeployQueue</title>
- <para>
- Used to programmatically deploy a queue. If the queue exists but is undeployed, it will be deployed. Otherwise, it is created and deployed.
- </para>
- <para>
- The <varname>name</varname> parameter matches a destination to deploy.
- </para>
- <para>
- The optional <varname>jndiName</varname> parameter represents the full JNDI name of the location to which a destination will be bound. If this is not specified, the destination will be bound in <literal><DefaultQueueJNDIContext>/<name></literal>.
- </para>
- <para>
- There are two overloaded versions of this operation. The first deploys the destination with default paging parameters. The second deploys the destination with the paging parameters specified. For more information about paging parameters, see the section on Configuring Destinations.
- </para>
- </section>
- <section id="conf.serverpeer.operations.undeployQueue">
- <title>UndeployQueue</title>
- <para>
- Used to programmatically undeploy a queue. Queues are not removed from persistent storage. This operation returns <literal>true</literal> if the queue is successfully undeployed. Otherwise, it returns <literal>false</literal>.
- </para>
- </section>
- <section id="conf.serverpeer.operations.destroyQueue">
- <title>DestroyQueue</title>
- <para>
- Used to programmatically destroy a queue. Queues are undeployed and all of their data is removed from the database and destroyed.
- </para>
- <warning>
- <para>
- Exercise caution when using this method, since it will delete all data for the queue.
- </para>
- </warning>
- <para>
- This operation returns <literal>true</literal> if the queue was destroyed successfully. Otherwise, it returns <literal>false</literal>.
- </para>
- </section>
- <section id="conf.serverpeer.operations.deployTopic">
- <title>DeployTopic</title>
- <para>
- Used to programmatically deploy a topic. There are two overloaded versions of this operation. The first deploys already existing topics with the default paging parameters. The second creates and deploys topics with specified paging parameters. See the section on Configuring Destinations for more information.
- </para>
- <para>
- The <varname>name</varname> parameter represents the name of the destination to deploy.
- </para>
- <para>
- The <varname>jndiName</varname> represents the full JNDI name of the location to which the destination will be bound. If this is not specified, the destination will be bound in <literal><DefaultTopicJNDIContext>/<name></literal>.
- </para>
- </section>
- <section id="conf.serverpeer.operations.undeployTopic">
- <title>UndeployTopic</title>
- <para>
- Used to programmatically undeploy a topic. Topics are undeployed, but not removed from persistent storage. This operation returns <literal>true</literal> if the topic is undeployed successfully. Otherwise, <literal>false</literal> is returned.
- </para>
- </section>
- <section id="conf.serverpeer.operations.destroyTopic">
- <title>DestroyTopic</title>
- <para>
- Used to programmatically destroy a topic. Topics are undeployed and all data is removed from the database and destroyed. This operation returns <literal>true</literal> if the topic is successfully destroyed. Otherwise, it returns <literal>false</literal>.
- </para>
- <warning>
- <para>
- Exercise caution when using this method, since it will delete all data for the topic.
- </para>
- </warning>
- </section>
- <section id="conf.serverpeer.operations.listmessagecountersashtml">
- <title>ListMessageCountersHTML</title>
- <para>
- Returns message counters in a simply-displayed HTML format.
- </para>
- </section>
- <section id="conf.serverpeer.operations.resetallmessagecounters">
- <title>ResetAllMesageCounters</title>
- <para>Resets all message counters to zero.</para>
- </section>
- <section id="conf.serverpeer.operations.resetallmessagecounterhistories">
- <title>ResetAllMesageCounters</title>
- <para>Resets all message counter histories to zero.</para>
- </section>
- <section id="conf.serverpeer.operations.enablemessagecounters">
- <title>EnableMessageCounters</title>
- <para>Enables all message counters for all destinations. Message counters are disabled by default.</para>
- </section>
- <section id="conf.serverpeer.operations.disablemessagecounters">
- <title>DisableMessageCounters</title>
- <para>Disables all message counters for all destinations. Message counters are disabled by default.</para>
- </section>
- <section id="conf.serverpeer.operations.retrievepreparedtransactions">
- <title>RetrievePreparedTransactions</title>
- <para>Retrieves a list of the XIDs for all transactions currently in a prepared state on the node.</para>
- </section>
- <section id="conf.serverpeer.operations.showpreparedtransactions">
- <title>ShowPreparedTransactions</title>
- <para>Retrieves a list of the XIDs for all transactions currently in a prepared state on the node in an easily-displayed HTML format.</para>
- </section>
- </section>
</section>
</section>
<section id="conf.changingds">
@@ -478,18 +488,18 @@
</para>
</section>
<section id="conf.postoffice">
- <title>Configuring the Post office</title>
+ <title>Configuring the Post Office</title>
<para>
The post office routes messages to their destination or destinations. It maintains the mappings between the addresses to which a message can be sent, and the final queue. For example, when sending a message with an address that represents a JMS queue, the post office routes the message to that JMS queue. When sending a message with an address that represents a JMS topic, the post office routes the message to a set of queues — one for each JMS subscription.
</para>
<para>The post office also handles the persistence for address mapping.</para>
<para>
- JBoss Messaging post offices are cluster-aware. In a cluster, they automatically route and pull messages between nodes in order to provide fully-distributed JMS queues and topics.
+ JBoss Messaging post offices are cluster-aware. In a cluster, they automatically route (push) and pull messages between nodes in order to provide fully-distributed JMS queues and topics.
</para>
<para>
You can configure the post office in your <filename><your database type>-persistence-service.xml</filename> file. For example:
</para>
-<!-- Added here --> <programlisting><![CDATA[
+ <programlisting><![CDATA[
<mbean code="org.jboss.messaging.core.jmx.MessagingPostOfficeService"
name="jboss.messaging:service=PostOffice"
xmbean-dd="xmdesc/MessagingPostOffice-xmbean.xml">
@@ -685,125 +695,151 @@
</mbean>
]]></programlisting>
-<!-- End Added --> <section id="conf.postoffice.attributes">
- <title>Post office attributes</title>
- <para>
- In this section, we outline the attributes of the post office.
- </para>
- <section id="conf.postoffice.attributes.datasource">
- <title>DataSource</title>
- <para>
- The data source used to persist post office mapping data.
+ <section id="conf.postoffice.attributes">
+ <title>Post Office Attributes</title>
+ <para>The following attributes are available to configure the Messaging Post Office:</para>
+ <variablelist>
+ <varlistentry>
+ <term>DataSource</term>
+ <listitem>
+ <para>Specifies
+ the data source used to persist post office mapping data.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>SQLProperties</term>
+ <listitem>
+ <para>Specifies the DDL and DML for a particular database. If this attribute is not overridden, the default Hypersonic configuration will be used.</para>
+ <important>
+ <para>Hypersonic is not recommended for production environments. You should strongly consider changing the values for this attribute.</para>
+ </important>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>CreateTablesOnStartup</term>
+ <listitem>
+ <para>Specifies whether tables and index are created when the post office service is started. When set to <literal>true</literal>, the post office will create tables and indexes on startup. If tables or indexes already exist, a <exceptionname>SQLException</exceptionname> is thrown by the JDBC driver, but this is ignored by the Persistence Manager and the operation continues unhindered. The default value is <literal>true</literal>.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>DetectDuplicates</term>
+ <listitem>
+ <para>Specifies whether the post office will detect duplicate messages sent when delivery is restricted on a new node after server failure.
+ When set to <literal>true</literal>, the post office detects duplicate messages . The default value is <literal>true</literal>.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>IDCacheSize</term>
+ <listitem>
+ <para>Specifies the number of messages IDs the ID Cache should hold. If server failover occurs, the ID Cache is accessed as part of the process to prevent duplicate messages being sent after failover occurs.
+ The default value is <literal>500</literal> (messages). </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PostOfficeName</term>
+ <listitem>
+ <para>Specifies the name of the post office.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>NodeIDView</term>
+ <listitem>
+ <para>Returns the node IDs of all nodes in a cluster as a set.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>GroupName</term>
+ <listitem>
+ <para>Specifies the post office name to link with other identically named post offices.
</para>
- </section>
- <section id="conf.postoffice.attributes.sqlproperties">
- <title>SQLProperties</title>
- <para>
- Specifies the DDL and DML for a particular database. If this attribute is not overridden, the default Hypersonic configuration will be used.
+ <note>
+ <para>Post offices with the same group name will form a cluster together. Match post office group names to form a cluster with particular post offices.</para>
+ </note>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Clustered</term>
+ <listitem>
+ <para>Specifies whether the post office will join a cluster to form distributed queues and topics. If set to <literal>false</literal>, all cluster-related attributes will be ignored.
</para>
- </section>
- <section id="conf.postoffice.attributes.createtables">
- <title>CreateTablesOnStartup</title>
- <para>
- When set to <literal>true</literal>, the post office will create tables and indexes on startup. If tables or indexes already exist, a <exceptionname>SQLException</exceptionname> is thrown by the JDBC driver, but this is ignored by the Persistence Manager and the operation continues unhindered. The default value is <literal>true</literal>.
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>StateTimeout</term>
+ <listitem>
+ <para>Specifies
+ the maximum period of time the post office will wait to receive group state when a node joins a pre-existing cluster. The default value is <literal>5000</literal> milliseconds.
</para>
- </section>
- <section id="conf.postoffice.attributes.detectdups">
- <title>DetectDuplicates</title>
- <para>
- When set to <literal>true</literal>, the post office detects duplicate messages that may be sent when delivery is retried on a new node after server failure. The default value of this attribute is <literal>true</literal>.
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>CastTimeout</term>
+ <listitem>
+ <para>Specifies the maximum time the post office will wait for a reply casting message synchronously. The default value is <literal>5000</literal> milliseconds.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>FailoverOnNodeLeave</term>
+ <listitem>
+ <para>Specifies how connections are handled when a server node shuts down.
+ If set to <literal>true</literal>, connections associated with the cleanly-terminated server node will failover onto another node. The default value is <literal>false</literal>.
+</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>MaxConcurrentReplications</term>
+ <listitem>
+ <para>Specifies
+ the maximum number of concurrent replication reply requests to return before requests are blocked . This prevents JGroups overloading. The default value is <literal>50</literal>.
</para>
- </section>
- <section id="conf.postoffice.attributes.idcachesize">
- <title>IDCacheSize</title>
- <para>
- If duplicate detection is enabled, the server remembers the last <literal>n</literal> message IDs sent, to prevent duplicate messages being sent after failover occurs. <varname>IDCacheSize</varname> determines the value of <literal>n</literal>. Its default value is <literal>500</literal>.</para>
- </section>
- <section id="conf.postoffice.attributes.postofficename">
- <title>PostOfficeName</title>
- <para>The name of the post office.</para>
- </section>
- <section id="conf.postoffice.attributes.nodeidview">
- <title>NodeIDView</title>
- <para>Returns the node IDs of all nodes in a cluster as a set.</para>
- </section>
- <section id="conf.postoffice.attributes.groupname">
- <title>GroupName</title>
- <para>
- Post offices with the same group name will form a cluster together. Match post office group names to form a cluster with particular post offices.
+ <note>
+ <para>You should not alter the defalut value for MaxConcurrentReplications. The defalut value is the optimal setting.</para>
+ </note>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>ControlChannelConfig</term>
+ <listitem>
+ <para>Specifies JGroups stack configuration for the control channel. The control channel sends requests to and receives responses from other nodes in the cluster.</para>
+ <note>
+ <para>JBoss Messaging uses JGroups for all group management. Standard JGroups configuration is used. For more information, see the JGroups release documentation or visit <ulink url="http://www.jgroups.org">the JGroups home page</ulink> or <ulink url="http://wiki.jboss.org/wiki/Wiki.jsp?page=JGroups">the JGroups Wiki Documentation Pages</ulink>.</para>
+ </note>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>DataChannelConfig</term>
+ <listitem>
+ <para>Specifies JGroups stack configuration for the data channel. The data channel sends and receives messages to and from other nodes in the cluster, and replicates session data.
</para>
- </section>
- <section id="conf.postoffice.attributes.clustered">
- <title>Clustered</title>
- <para>
- If set to <literal>true</literal>, the post office will join a cluster to form distributed queues and topics. If set to <literal>false</literal>, all cluster-related attributes will be ignored.
- </para>
- </section>
- <section id="conf.postoffice.attributes.statetimeout">
- <title>StateTimeout</title>
- <para>
- The maximum period of time the post office will wait to receive group state when a node joins a pre-existing cluster. The default value is <literal>5000</literal> milliseconds.
- </para>
- </section>
- <section id="conf.postoffice.attributes.casttimeout">
- <title>CastTimeout</title>
- <para>
- The maximum time that the post office will wait for a reply casting message synchronously. The default value is <literal>5000</literal>.
- </para>
- </section>
- <section id="conf.postoffice.attributes.failoveronnodeleave">
- <title>FailoverOnNodeLeave</title>
- <para>
- If set to <literal>true</literal>, when a server node is shut down cleanly, any connections on that node will failover onto another node. The default value is <literal>false</literal>.
- </para>
- </section>
- <section id="conf.postoffice.attributes.maxconcurrentreplications">
- <title>MaxConcurrentReplications</title>
- <para>
- The maximum number of concurrent replication requests to make before blocking to allow replies to return. This prevents JGroups overloading. There is rarely a good reason to alter this. The default value is <literal>50</literal>
- </para>
- </section>
- <section id="conf.postoffice.attributes.controlchannelconfig">
- <title>ControlChannelConfig</title>
- <para>
- JBoss Messaging uses JGroups for all group management. This attribute contains JGroups stack configuration for the control channel, which sends requests to and receives responses from other nodes in the cluster.</para>
- <para>
- Standard JGroups configuration is used. For more information, see the JGroups release documentation or visit <ulink url="http://www.jgroups.org">http://www.jgroups.org</ulink> or <ulink url="http://wiki.jboss.org/wiki/Wiki.jsp?page=JGroups">http://wiki.jboss.org/wiki/Wiki.jsp?page=JGroups</ulink>.</para>
- </section>
- <section id="conf.postoffice.attributes.datachannelconfig">
- <title>DataChannelConfig</title>
- <para>
- JBoss Messaging uses JGroups for all group management. This attribute contains JGroups stack configuration for the data channel, which sends and receives messages to and from other nodes in the cluster, and replicates session data.
- </para>
- <para>
- Standard JGroups configuration is used. For more information, see the JGroups release documentation or visit <ulink url="http://www.jgroups.org">http://www.jgroups.org</ulink> or <ulink url="http://wiki.jboss.org/wiki/Wiki.jsp?page=JGroups">http://wiki.jboss.org/wiki/Wiki.jsp?page=JGroups</ulink>.</para>
- </section>
+ <note>
+ <para>JBoss Messaging uses JGroups for all group management. Standard JGroups configuration is used. For more information, see the JGroups release documentation or visit <ulink url="http://www.jgroups.org">the JGroups home page</ulink> or <ulink url="http://wiki.jboss.org/wiki/Wiki.jsp?page=JGroups">the JGroups Wiki Documentation Pages</ulink>.</para>
+ </note>
+ </listitem>
+ </varlistentry>
+ </variablelist>
</section>
</section>
<section id="conf.persistencemanager">
<title>Configuring the Persistence Manager</title>
- <para>
- The Persistence Manager manages all message-related persistence. JBoss Messaging ships with a JDBC Persistence Manager, which handles message data persistence in a relational database accessed via JDBC. The Persistence Manager can be plugged into the Messaging server, which lets you provide additional implementations to persist message data in non-relational stores, file stores, etc.
+ <para>The Persistence Manager manages all message-related persistence. JBoss Messaging ships with a JDBC Persistence Manager, which handles message data persistence in a relational database accessed via JDBC. The Persistence Manager can be plugged into the Messaging server, which allows additional implementations to persist message data in non-relational stores, and file stores.
</para>
<para>
- Persistent service configuration details are grouped in <filename><your database type>-persistence-service.xml</filename>. By default, JBoss Messaging ships with the <filename>hsqldb-persistence-service.xml</filename> file, which configures the Messaging server to use the Hypersonic database instance included by default with any JBoss Application Server instance.
+ Persistent service configuration details are grouped in <filename><your database type>-persistence-service.xml</filename>. JBoss Messaging ships with the <filename>hsqldb-persistence-service.xml</filename> file by default, which configures the Messaging server to use the Hypersonic database instance included by default with any JBoss Application Server instance.
</para>
<warning>
- <para>
- Hypersonic should not be used in a production environment, since it has limited support for transaction isolation and tends to behave erratically when under high loads.
+ <para>Hypersonic should not be used in a production environment. It has limited support for transaction isolation and does not handle production messaging loads.
</para>
<!--<para>The <ulink
url="http://wiki.jboss.org/wiki/Wiki.jsp?page=ConfigJBossMQDB">Critique
of Hypersonic</ulink> wiki page outlines some of the well-known issues
occuring when using this database.</para>--> </warning>
- <para>
- JBoss Messaging also ships with Persistence Manager configurations for MySQL, Oracle, PostgreSQL, Sybase, Microsoft SQL Server, and DB2. The example configuration files (<filename>mysql-persistence-service.xml</filename>, <filename>ndb-persistence-service.xml</filename>, etc.) are available from the <filename>jboss-as/docs/examples/jms</filename> directory of the release bundle.
+ <para>JBoss Messaging also ships with Persistence Manager configurations for MySQL, Oracle, PostgreSQL, Sybase, Microsoft SQL Server, and DB2. The example configuration files (such as <filename>mysql-persistence-service.xml</filename> and <filename>ndb-persistence-service.xml</filename>) are available from the <filename>jboss-as/docs/examples/jms</filename> directory of the release bundle.
</para>
- <para>
- We encourage users to contribute their own configuration files for thorough testing and certification for use with JBoss Messaging. The JDBC Persistence Manager uses standard SQL as its Data Manipulation Language (DML), so writing a Persistence Manager configuration for another database type is a matter of changing the configuration's Data Definition Language (DDL), which usually differs on a per-database basis.
+ <para><!--Don't think this is appropriate to include in enterprise docs:
+ We encourage users to contribute their own configuration files for thorough testing and certification for use with JBoss Messaging. -->The JDBC Persistence Manager uses standard SQL as its Data Manipulation Language (DML), so writing a Persistence Manager configuration for another database type is a matter of changing the configuration's Data Definition Language (DDL), which usually differs on a per-database basis.
</para>
<para>
- JBoss Messaging also ships with a Null Persistence Manager configuration option, which can be used when you do not want persistence.
+ JBoss Messaging also ships with a Null Persistence Manager configuration option, which can be used when persistence is not required.
</para>
<para>
The following code is the default Hypersonic persistence configuration file:
@@ -993,77 +1029,92 @@
</mbean>
]]></programlisting>
<important>
- <para>
- When a database is created in Sybase, the maximum size of text and image datatypes is set to the default page size of <literal>2 kilobytes</literal>. Any message that exceeds this limit is truncated without any information or warning. To avoid this, edit the database parameters to set <varname>@@TEXTSIZE</varname> to a greater value.
+ <para>The maximum size of Sybase database text and image datatypes is set to <literal>2 kilobytes</literal> by default. Any message that exceeds this limit is truncated, without any information or warning. Set the <varname>@@TEXTSIZE</varname> database parameter to a higher value to prevent potential truncation. </para>
+ <para>Truncation may also occur in the Microsoft SQL Server if <varname>@@TEXTSIZE</varname> value is set to a lesser value than the default value. For further information, see <ulink url="http://jira.jboss.com/jira/browse/SOA-554"/>.
</para>
- <para>
- Truncation may also occur in the Microsoft SQL Server if <varname>@@TEXTSIZE</varname> value is set to a lesser value than the default value. For further information, see <ulink url="http://jira.jboss.com/jira/browse/SOA-554"/>.
- </para>
</important>
<important>
- <para>
- Microsoft SQL Server does not automatically un-allocate the hard drive space occupied by data in a database when that data is deleted. This means that, when the space is used as a data store for a service that temporarily stores many records (such as a messaging service), the disk space will quickly become much greater than the amount of data actually being stored.
+ <para>Microsoft SQL Server does not automatically un-allocate hard drive space when data is deleted from a database. When the hard drive database space is used as a data store for a service that temporarily stores many records (such as a messaging service), the disk space will quickly become much greater than the amount of data actually being stored.
</para>
- <para>
- Database administrators should implement database maintenance plans to ensure that the unused space is reclaimed. Refer to your Microsoft SQL Server documentation for the DBCC commands <command>ShrinkDatabase</command> and <command>UpdateUsage</command> for guidance reclaiming the unused space. For further information about this issue, see <ulink url="https://jira.jboss.org/jira/browse/SOA-629"/>
+ <para>Database administrators must implement database maintenance plans to ensure that the unused space is reclaimed. Refer to your Microsoft SQL Server documentation for the DBCC commands <command>ShrinkDatabase</command> and <command>UpdateUsage</command> for guidance reclaiming the unused space. For further information about this issue, see <ulink url="https://jira.jboss.org/jira/browse/SOA-629"/>
</para>
</important>
<section id="conf.persistencemanager.attributes">
- <title>We now discuss the MBean attributes of the PersistenceManager MBean</title>
- <section id="conf.persistencemanager.attributes.createtables">
- <title>CreateTablesOnStartup</title>
- <para>
- When <literal>true</literal>, the persistence manager will attempt to create tables (and indexes) on startup. If tables or indexes already exist, a <exceptionname>SQLException</exceptionname> will be thrown by the JDBC driver and ignored by the persistence manager, allowing it to continue unhindered.
+ <title> PersistenceManager MBean Attributes</title>
+ <para>The following attributes are available to configure the Persistence Manager MBean:</para>
+ <variablelist>
+ <varlistentry>
+ <term>CreateTablesOnStartup</term>
+ <listitem>
+ <para>Specifies whether tables and index creation is attempted when the Persistence Manager is started.
+ When set to <literal>true</literal> (default), the persistence manager will attempt to create tables (and indexes) on startup. If tables or indexes already exist, a <exceptionname>SQLException</exceptionname> will be thrown by the JDBC driver and ignored by the persistence manager, allowing it to continue unhindered.
</para>
- <para>
- By default, this parameter is set to <literal>true</literal>.
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>UsingBatchUpdates</term>
+ <listitem>
+ <para>Specifies whether multiple database updates are grouped in batches to improve performance.
+ Set this value to <literal>true</literal> if your database supports JDBC batch updates.. The default value is <literal>false</literal>.
</para>
- </section>
- <section id="conf.persistencemanager.attributes.batchupdates">
- <title>UsingBatchUpdates</title>
- <para>
- If your database supports JDBC batch updates, setting this to <literal>true</literal> will group multiple database updates in batches to improve performance. The default value is <literal>false</literal>.
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>UsingBinaryStream</term>
+ <listitem>
+ <para>Specifies whether messages are stored and read with a JDBC binary stream, instead of via <literal>getBytes()</literal> and <literal>setBytes()</literal>.
+ Set this value to <literal>false</literal> if your database must use <literal>getBytes()</literal> and <literal>setBytes()</literal>. The default value is <literal>true</literal>.
</para>
- </section>
- <section id="conf.persistencemanager.attributes.binarystream">
- <title>UsingBinaryStream</title>
- <para>
- When <literal>true</literal>, messages will be stored and read with a JDBC binary stream instead of via <literal>getBytes()</literal> and <literal>setBytes()</literal>, which, in some databases, can only get or set a certain number of bytes. The default value is <literal>true</literal>.
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>UsingTrailingByte</term>
+ <listitem>
+ <para>Specifies how Sybase database BLOBs containing trailing zeroes are handled. When set to <literal>true</literal> , a trailing non-zero byte is added to each BLOB before persistence, and removed from the BLOB following persistence, preventing truncation by the database. The default value is <literal>false</literal><note>
+ <para>Certain versions of Sybase truncate a BLOB with trailing zeros. This attribute is only required if you are running a Sybase database.</para>
+ </note></para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>SupportsBlobOnSelect</term>
+ <listitem>
+ <para>
+ Specifies how BLOBs are inserted into certain database types. When set to <literal>false</literal>, two-stage insertion will be used. The default value is <literal>true</literal>.
</para>
- </section>
- <section id="conf.persistencemanager.attributes.trailingbyte">
- <title>UsingTrailingByte</title>
- <para>
- Some versions of Sybase will truncate a BLOB with trailing zeros. When <varname>UseTrailingByte</varname> is set to <literal>true</literal>, a trailing non-zero byte will be added to each BLOB before persistence, and removed from the BLOB following persistence, preventing truncation by the database. This is only known to be necessary for Sybase databases. By default, the value is set to <literal>false</literal>.
+ <note>
+ <para>Certain databases, specifically Oracle, do not allow BLOB insertion via an <code>INSERT INTO ... SELECT FROM</code> statement, and require two-stage conditional message insertion. Set this attribute to <literal>false</literal> if you are running an Oracle database, or other database with this requirement.</para>
+ </note>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>SQLProperties</term>
+ <listitem>
+ <para>Specifies the DDL and DML for a particular database. If a particular DDL or DML statement is not overridden, the default Hypersonic configuration will be used for that statement.
</para>
- </section>
- <section id="conf.persistencemanager.attributes.supportsblobonselect">
- <title>SupportsBlobOnSelect</title>
- <para>
- Some databases, specifically Oracle, do not allow BLOB insertion via an <code>INSERT INTO ... SELECT FROM</code> statement, and require two-stage conditional message insertion. When <varname>SupportsBlobOnSelect</varname> is set to <literal>false</literal>, two-stage insertion will be used. The default value is <literal>true</literal>.
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>MaxParams</term>
+ <listitem>
+ <para>Specifies the maximum number of parameters allowed per prepared statement while loading messages. The default value is <literal>100</literal>.
</para>
- </section>
- <section id="conf.persistencemanager.attributes.sqlproperties">
- <title>SQLProperties</title>
- <para>
- Specifies the DDL and DML for a particular database. If a particular DDL or DML statement is not overridden, the default Hypersonic configuration will be used for that statement.
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>UseNDBFailoverStrategy</term>
+ <listitem>
+ <para>Specifies whether a SQL statement is re-executed in the event a database transation commit fails in a clustered environment.
+ If set to <literal>true</literal>, the SQL statement is re-executed in the event that the commit fails. If a further error occurs, the persistence manager assumes the error is due to the previous transaction having committed successfully, and ignores the error. By default, this attribute is set to <literal>false</literal>.
</para>
- </section>
- <section id="conf.persistencemanager.attributes.maxparams">
- <title>MaxParams</title>
- <para>
- While loading messages, the persistence manager generates prepared statements with numerous parameters. This attribute defines the maximum number of parameters allowed per prepared statement. The default value is <literal>100</literal>.
- </para>
- </section>
- <section id="conf.persistencemanager.attributes.usendbfailoverstrategy">
- <title>UseNDBFailoverStrategy</title>
- <para>
- When some databases, such as MySQL, run in clustered environments, they can fail during database transaction commits. This can happen when the database node dies during the commit, so that the final transaction state is unknown. If <varname>UseNDBFailoverStrategy</varname> is set to <literal>true</literal>, the SQL statement will be re-executed in the event that the commit fails. If a further error occurs, the persistence manager assumes the error is due to the previous transaction having committed successfully, and ignores the error. By default, this attribute is set to <literal>false</literal>.
- </para>
- </section>
+ <note>
+ <para>When some databases, such as MySQL, run in clustered environments, they can fail during database transaction commits. This can happen when the database node dies during the commit, so that the final transaction state is unknown. </para>
+ </note>
+ </listitem>
+ </varlistentry>
+ </variablelist>
</section>
-<!-- end conf.persistencemanager.attributes --> </section>
-<!-- end conf.persistencemanager --> <section id="conf.jmsusermanager">
+ </section>
+ <section id="conf.jmsusermanager">
<title>Configuring the JMS user manager</title>
<para>
The JMS User Manager maps preconfigured client IDs to users. It also manages user and role tables, depending on the configured login module.
@@ -1099,27 +1150,35 @@
]]></programlisting>
<section id="conf.jmsusermanager.attributes">
<title>JMSUserManager Managed Bean Attributes</title>
- <section id="conf.jmsusermanager.attributes.createtables">
- <title>CreateTablesOnStartup</title>
- <para>
- When set to <literal>true</literal>, the JMS User Manager attempts to create tables (and indexes) upon startup. If the tables or indexes already exist, a <exceptionname>SQLException</exceptionname> is thrown and ignored, allowing the operation to continue. The default value is <literal>true</literal>.
+ <variablelist>
+ <varlistentry>
+ <term>CreateTablesOnStartup</term>
+ <listitem>
+ <para>Specifies whether tables and index creation is attempted when the JMSUserManager MBean is started.
+ When set to <literal>true</literal> (default), the JMSUserManager will attempt to create tables (and indexes) on startup. If tables or indexes already exist, a <exceptionname>SQLException</exceptionname> will be thrown by the JDBC driver and ignored by the persistence manager, allowing it to continue unhindered.
</para>
- </section>
- <section id="conf.jmsusermanager.attributes.batchupdates">
- <title>UsingBatchUpdates</title>
- <para>
- If your database supports JDBC batch updates, set this to <literal>true</literal> to have the persistence manager group database updates into batches to improve performance. The default value is <literal>false</literal>.
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>UsingBatchUpdates</term>
+ <listitem>
+ <para>Specifies whether multiple database updates are grouped in batches to improve performance.
+ Set this value to <literal>true</literal> if your database supports JDBC batch updates.. The default value is <literal>false</literal>.
</para>
- </section>
- <section id="conf.jmsusermanager.attributes.sqlproperties">
- <title>SQLProperties</title>
- <para>
- Specifies the DDL and DML for the database. If this is not overridden, the default Hypersonic configuration will be used. You can also specify default user and role data. Specify any data to be inserted with property names prefixed with <literal>POPULATE.TABLES</literal>, as in the previous example.
- </para>
- </section>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>SQLProperties</term>
+ <listitem>
+ <para>Specifies the DDL and DML for a particular database. If a particular DDL or DML statement is not overridden, the default Hypersonic configuration will be used for that statement.
+ </para>
+ <para>You can also insert default user and role property data by prefixing the data with <literal>POPULATE.TABLES</literal>.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
</section>
-<!-- end conf.jmsusermanager.attributes --> </section>
-<!-- end.conf.jmsusermanager --> <section id="conf.destination">
+ </section>
+ <section id="conf.destination">
<title>Configuring Destinations</title>
<section id="conf.preconf.destinations">
<title>Pre-configured destinations</title>
@@ -1151,99 +1210,67 @@
]]></programlisting>
</section>
<!-- end conf.preconf.destinations --> <section id="conf.destination.queue">
- <title>Configuring Queues</title>
- <section id="conf.destination.queue.attributes">
- <title>Queue MBean Attributes</title>
- <section id="conf.destination.queue.attributes.name">
- <title>Name</title>
- <para>Defines the queue name.</para>
- </section>
- <section id="conf.destination.queue.attributes.jndiName">
- <title>JNDIName</title>
- <para>Defines the JNDI name that binds the queue.</para>
- </section>
- <section id="conf.destination.queue.attributes.dlq">
- <title>DLQ</title>
- <para>Defines the DLQ (Dead Letter Queue) for this queue and overrides any value set in the Server Peer configuration file.</para>
- </section>
- <section id="conf.destination.queue.attributes.expiryqueue">
- <title>ExpiryQueue</title>
- <para>Defines the expiry queue and overrides any value set in the Server Peer configuration file.</para>
- </section>
- <section id="conf.destination.queue.attributes.redeliverydelay">
- <title>RedeliveryDelay</title>
- <para>Defines the redelivery delay to be applied to this queue and overrides any value set in the Server Peer configuration file.</para>
- </section>
- <section id="conf.destination.queue.attributes.maxdeliveryattempts">
- <title>MaxDeliveryAttempts</title>
- <para>
+ <title>Queue MBean Attributes</title>
+ <variablelist>
+ <varlistentry>
+ <term>Name</term>
+ <listitem>
+ <para>Defines the queue name.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>JNDIName</term>
+ <listitem>
+ <para>Defines the JNDI name that binds the queue.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>DLQ</term>
+ <listitem>
+ <para>Defines the DLQ (Dead Letter Queue) for this queue and overrides any value set in the Server Peer configuration file.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>ExpiryQueue</term>
+ <listitem>
+ <para>Defines the expiry queue and overrides any value set in the Server Peer configuration file.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>RedeliveryDelay</term>
+ <listitem>
+ <para>Defines the redelivery delay to be applied to this queue and overrides any value set in the Server Peer configuration file.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>MaxDeliveryAttempts</term>
+ <listitem>
+ <para>
Defines the maximum number of times message delivery is attempted before the message is sent to the DLQ, if configured. The default value, <literal>-1</literal>, means that the value from the Server Peer configuration file is used. Any other setting will override the value set in the Server Peer configuration file.
</para>
- </section>
- <section id="conf.destination.queue.attributes.security">
- <title>Destination Security Configuration</title>
- <para>
- <literal>SecurityConfig</literal> determines which roles can read, write and create upon the destination. It uses the same syntax and semantics as JBossMQ destination security configuration.
- </para>
- <para>
- The <literal>SecurityConfig</literal> element should contain one <literal><security></literal> element, which can contain multiple <literal><role></literal> elements. A <literal><role></literal> element defines the access type for that particular role.
- </para>
- <para>
- If the <varname>read</varname> attribute is set to <literal>true</literal>, then that role will be able to <emphasis>read</emphasis> (create consumers, receive messages, and browse) this destination.
- </para>
- <para>
- If the <varname>write</varname> attribute is set to <literal>true</literal>, then that role will be able to <emphasis>write</emphasis> (create producers or send messages) to this destination.
- </para>
- <para>
- If the <varname>create</varname> attribute is set to <literal>true</literal>, then that role will be able to create durable subscriptions on this destination.
- </para>
- <para>
- Configuring security for a destination is optional. If a <literal>SecurityConfig</literal> element is not specified, then the default security configuration from the Server Peer will be used instead.
- </para>
- </section>
- <section id="conf.destination.queue.attributes.paging">
- <title>Destination paging parameters</title>
- <para>
- <emphasis>Pageable Channels</emphasis> is a new feature available in JBoss Messaging.
- </para>
- <para>
- Previously, for an application to support a queue or subscription, the queue needed to be stored entirely in memory. This was not always possible for very large queues or subscriptions.
- </para>
- <para>
- <emphasis>Pageable Channels</emphasis> is a new JBoss Messaging feature that lets you specify a maximum number of messages to be stored in memory at one time, on a queue-by-queue or topic-by-topic basis. JBoss Messaging then pages messages to and from storage transparently in blocks. This allows queues and subscriptions to grow to very large sizes without any degradation in performance as channel size increases. It has been tested with queues in excess of ten million 2 kilobyte messages on very basic hardware, and has the potential to scale to much greater message numbers.
- </para>
- <para>
- The individual parameters associated with pageable channels are as follows:
- </para>
- <para>
- <literal>FullSize</literal> defines the maximum number of messages held by the queue or topic subscription in memory at any one time. The actual queue can hold more messages, but these are paged to and from storage as messages are added or consumed. If no value is specified, the default is <literal>75000</literal>.
- </para>
- <para>
- <literal>PageSize</literal> defines the maximum number of messages that are pre-loaded per operation when loading messages from the queue or subscription. If no value is specified, the default is <literal>2000</literal>.
- </para>
- <para>
- <literal>DownCacheSize</literal> — when messages are paged to storage from the queue, they enter a <emphasis>Down Cache</emphasis> before being written to storage. This enables the write to occur as a single operation, which aids performance. This attribute determines the maximum number of messages that the Down Cache will hold before the messages are flushed to storage. If no value is specified, the default is <literal>2000</literal>.
- </para>
- <para>
- Paging parameters for temporary queues must be specified on the appropriate connection factory. See the section on Connection Factory Configuration for details.
- </para>
- </section>
- <section id="conf.destination.queue.attributes.createdprogrammatically">
- <title>CreatedProgrammatically</title>
- <para>Returns <literal>true</literal> if the queue was created
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>CreatedProgrammatically</term>
+ <listitem>
+ <para>Returns <literal>true</literal> if the queue was created
programmatically.</para>
- </section>
- <section id="conf.destination.queue.attributes.messagecount">
- <title>MessageCount</title>
- <para>Returns the total number of messages in the queue. That is, the number of messages being scheduled plus the number being delivered, plus the number not being delivered.</para>
- </section>
- <section id="conf.destination.queue.attributes.scheduledmessagecount">
- <title>ScheduledMessageCount</title>
- <para>Returns the number of <emphasis>scheduled messages</emphasis> in the queue. This is the number of messages scheduled to be delivered at a later date.</para>
- <para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>MessageCount</term>
+ <listitem>
+ <para>Returns the total number of messages in the queue. That is, the number of messages being scheduled plus the number being delivered, plus the number not being delivered.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>ScheduledMessageCount</term>
+ <listitem>
+ <para>Returns the number of <emphasis>scheduled messages</emphasis> in the queue. This is the number of messages scheduled to be delivered at a later date.</para>
+ <para>
Scheduled delivery lets you specify the earliest time at which a particular message will be delivered. For example, you can send a message now, and specify that it will not be delivered for two hours. To do so, you would set the following in the message header:
</para>
- <programlisting>
+ <programlisting>
long now = System.currentTimeMillis();
@@ -1255,81 +1282,182 @@
prod.send(msg);
</programlisting>
- </section>
- <section id="conf.destination.queue.attributes.maxsize">
- <title>MaxSize</title>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>MaxSize</term>
+ <listitem>
+ <para>
+ Specifies the maximum number of messages that can be held in a queue. Any excess messages will be dropped. The default value is <literal>-1</literal>, which is unbounded.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Clustered</term>
+ <listitem>
+ <para>
+ This attribute must be set to <literal>true</literal> if the destination is clustered.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>MessageCounter</term>
+ <listitem>
+ <para>Each queue maintains a message counter.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>MessageCounterStatistics</term>
+ <listitem>
+ <para>The statistics for the message counter.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>MessageCounterHistoryDayLimit</term>
+ <listitem>
+ <para>The maximum number of days for which to hold message counter history. Overrides any value set in the Server Peer configuration file.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>ConsumerCount</term>
+ <listitem>
+ <para>The number of consumers currently consuming from the queue.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <section id="conf.destination.queue.attributes.security">
+ <title>Destination Security Configuration</title>
+ <para>
+ <markup><SecurityConfig></markup> determines which roles can read, write and create upon the destination. It uses the same syntax and semantics as JBossMQ destination security configuration.
+ </para>
+ <para>
+ The <markup><SecurityConfig></markup> element must contain one <markup><security></markup> element, which can contain multiple <markup><role></markup> elements. A <markup><role></markup> element defines the access type for that particular role using the following attributes:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term>read</term>
+ <listitem>
+ <para>Specifies the role can create consumers, receive messages, and browse the destination.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>write</term>
+ <listitem>
+ <para>Specifies the role can create producers, or send messages to the destination.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>create</term>
+ <listitem>
+ <para>Specifies the role can create durable subscriptions on this destination.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <note>
<para>
- Specifies the maximum number of messages that can be held in a queue. Any excess messages will be dropped. The default value is <literal>-1</literal>, which is unbounded.
+ Configuring security for a destination is optional. If a <literal>SecurityConfig</literal> element is not specified, then the default security configuration from the Server Peer will be used instead.
</para>
- </section>
- <section id="conf.destination.queue.attributes.clustered">
- <title>Clustered</title>
- <para>This attribute must be set to <literal>true</literal> if the destination is clustered.
+ </note>
+ </section>
+ <section id="conf.destination.queue.attributes.paging">
+ <title>Destination paging parameters</title>
+ <para>
+ Previously, for an application to support a queue or subscription, the queue needed to be stored entirely in memory. This was not always possible for very large queues or subscriptions.
</para>
- </section>
- <section id="conf.destination.queue.attributes.messagecounter">
- <title>MessageCounter</title>
- <para>Each queue maintains a message counter.</para>
- </section>
- <section id="conf.destination.queue.attributes.messagecounterstats">
- <title>MessageCounterStatistics</title>
- <para>The statistics for the message counter.</para>
- </section>
- <section id="conf.destination.queue.attributes.messagecounterhistorydaylimit">
- <title>MessageCounterHistoryDayLimit</title>
- <para>The maximum number of days for which to hold message counter history. Overrides any value set in the Server Peer configuration file.</para>
- </section>
- <section id="conf.destination.queue.attributes.consumercount">
- <title>ConsumerCount</title>
- <para>The number of consumers currently consuming from the queue.</para>
- </section>
+ <para><emphasis>Pageable Channels</emphasis> is a new JBoss Messaging feature that lets you specify a maximum number of messages to be stored in memory at one time, on a queue-by-queue or topic-by-topic basis. JBoss Messaging then pages messages to and from storage transparently in blocks. This allows queues and subscriptions to grow to very large sizes without any degradation in performance as channel size increases. It has been tested with queues in excess of ten million 2 kilobyte messages on very basic hardware, and has the potential to scale to much greater message numbers.
+ </para>
+ <para>
+ The individual parameters associated with pageable channels are as follows:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term>FullSize</term>
+ <listitem>
+ <para>Specifies the maximum number of messages held by the queue or topic subscription in memory at any one time. The actual queue can hold more messages, but these are paged to and from storage as messages are added or consumed. If no value is specified, the default is <literal>75000</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PageSize</term>
+ <listitem>
+ <para> Defines the maximum number of messages that are pre-loaded per operation when loading messages from the queue or subscription. If no value is specified, the default is <literal>2000</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>DownCacheSize</term>
+ <listitem>
+ <para>Specifies the maximum number of messages the Down Cache holds before the messages are flushed to storage. The default value is <literal>2000</literal> messages. </para>
+ <para>When messages are paged to storage from the queue, they enter a <emphasis>Down Cache</emphasis> before being written to storage. This enables the write to occur as a single operation, which aids performance.
+ </para>
+ <note>
+ <para>
+ Paging parameters for temporary queues must be specified on the appropriate connection factory. See the section on Connection Factory Configuration for details.</para>
+ </note>
+ <para>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
</section>
<section id="conf.destination.queue.operations">
<title>Queue Managed Bean Operations</title>
- <section id="conf.destination.queue.operations.removeallmessages">
- <title>RemoveAllMessages</title>
- <para>
+ <variablelist>
+ <varlistentry>
+ <term>RemoveAllMessages</term>
+ <listitem>
+ <para>
Removes (and deletes) all messages from the queue. <emphasis>Use with caution, as this will permanently delete all messages from the queue.</emphasis>
</para>
- </section>
- <section id="conf.destination.queue.operations.listallmessages">
- <title>ListAllMessages</title>
- <para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>ListAllMessages</term>
+ <listitem>
+ <para>
Lists all messages currently in the queue. Using a JMS selector as an argument in this operation lets you retrieve a subset of the messages in the queue that match the given criteria.
</para>
- </section>
- <section id="conf.destination.queue.operations.listdurablemessages">
- <title>ListDurableMessages</title>
- <para>
- Lists all <emphasis>durable</emphasis> messages in the queue. Using a JMS selector as an argument in this operation lets you retrieve a subset of messages in the queue that match the given criteria.
- </para>
- </section>
- <section id="conf.destination.queue.operations.listnondurablemessages">
- <title>ListNonDurableMessages</title>
- <para>
- Lists all <emphasis>non-durable</emphasis> messages in a queue. Using a JMS selector as an argument in this operation lets you retrieve a subset of messages in the queue that match the given criteria.
- </para>
- </section>
- <section id="conf.destination.queue.operations.resetmessagecounter">
- <title>ResetMessageCounter</title>
- <para>Resets the message counter to zero.</para>
- </section>
- <section id="conf.destination.queue.operations.resetmessagecounterhistory">
- <title>ResetMessageCounterHistory</title>
- <para>Resets the message counter history.</para>
- </section>
- <section id="conf.destination.queue.operations.listmessagecounterashtml">
- <title>ListMessageCounterAsHTML</title>
- <para>Lists the message counter in an easily-displayed HTML format.</para>
- </section>
- <section id="conf.destination.queue.operations.listmessagecounterhistoryashtml">
- <title>ListMessageCounterHistoryAsHTML</title>
- <para>Lists the message counter history in an easily-displayed HTML format.</para>
- </section>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>ListDurableMessages</term>
+ <listitem>
+ <para>
+ Lists all <emphasis>durable</emphasis> messages in the queue. Using a JMS selector as an argument in this operation lets you retrieve a subset of messages in the queue that match the given criteria.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>ListNonDurableMessages</term>
+ <listitem>
+ <para>
+ Lists all <emphasis>non-durable</emphasis> messages in a queue. Using a JMS selector as an argument in this operation lets you retrieve a subset of messages in the queue that match the given criteria.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>ResetMessageCounter</term>
+ <listitem>
+ <para>Resets the message counter to zero.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>ResetMessageCounterHistory</term>
+ <listitem>
+ <para>Resets the message counter history.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>ListMessageCounterAsHTML</term>
+ <listitem>
+ <para>Lists the message counter in an easily-displayed HTML format.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>ListMessageCounterHistoryAsHTML</term>
+ <listitem>
+ <para>Lists the message counter history in an easily-displayed HTML format.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
</section>
- </section>
- <section id="conf.destination.topics">
- <title>Configuring Topics</title>
<section id="conf.destination.topic.attributes">
<title>Topic Managed Bean Attributes</title>
<section id="conf.destination.topic.attributes.name">
@@ -1525,7 +1653,7 @@
</section>
</section>
</section>
-<!-- end of conf destination --> <section id="conf.connectionfactory">
+ <section id="conf.connectionfactory">
<title>Configuring Connection Factories</title>
<para>
By default, JBoss Messaging is configured to bind two connection factories in JNDI upon startup.
Modified: projects/enterprise/EAP/trunk/5.x/en-US/JBoss_Messaging_User_Guide.xml
===================================================================
--- projects/enterprise/EAP/trunk/5.x/en-US/JBoss_Messaging_User_Guide.xml 2010-05-31 06:19:14 UTC (rev 8050)
+++ projects/enterprise/EAP/trunk/5.x/en-US/JBoss_Messaging_User_Guide.xml 2010-05-31 07:26:12 UTC (rev 8051)
@@ -1,6 +1,5 @@
<?xml version='1.0' encoding='UTF-8'?>
-<!-- This document was created with Syntext Serna Free. -->
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!-- This document was created with Syntext Serna Free. --><!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>
<book id="JBoss_Messaging_User_Guide">
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Book_Info.xml"/>
More information about the jboss-cvs-commits
mailing list