<!DOCTYPE REFENTRY PUBLIC "-//Sun Microsystems//DTD DocBook V3.0-Based SolBook Subset V2.0//EN" [
<!--ArborText, Inc., 1988-1999, v.4002-->
<!ENTITY metainfo SYSTEM "metainfo.sgm">
<!ENTITY Software "J2EE SDK 1.4">
<!ENTITY options-common SYSTEM "options-common.sgm">
<!ENTITY synopsis-common SYSTEM "synopsis-common.sgm">
<!ENTITY % commonents SYSTEM "smancommon.ent">
%commonents;
<!ENTITY % booktitles SYSTEM "booktitles.ent">
%booktitles;
<!ENTITY Dash "&ndash;">
]>
<?Pub UDT _bookmark _target>
<?Pub EntList brvbar bull cross dash diam diams frac12 frac13 frac14 hellip
 laquo lArr loz mdash nabla ndash para pound rArr raquo sect yen ne>
<?Pub Inc>
<refentry id="create-jms-resource-1">
<refmeta><refentrytitle>create-jms-resource</refentrytitle><manvolnum>1</manvolnum>&metainfo;
</refmeta>
<refnamediv><indexterm><primary sortas="create-jms-resource ">create-jms-resource &mdash;creates
a JMS resource</primary></indexterm><indexterm><primary sortas="registers the JMS resource to the named instance">
creates a JMS resource &mdash; create-jms-resource</primary></indexterm><refname>
create-jms-resource</refname><refpurpose>creates a JMS resource</refpurpose>
</refnamediv>
<refsynopsisdiv><title>&synp-tt;</title>
<cmdsynopsis><command>create-jms-resource</command>&synopsis-common;
<arg>&Dash;&Dash;target <replaceable>target</replaceable></arg><arg choice="plain">&Dash;&Dash;restype <replaceable>
type</replaceable></arg><arg>&Dash;&Dash;enabled=<replaceable>true</replaceable></arg>
<arg>&Dash;&Dash;description <replaceable>text</replaceable></arg><arg>&Dash;&Dash;property (<replaceable>
name</replaceable>=<replaceable>value</replaceable>)[:<replaceable>name</replaceable>=<replaceable>
value</replaceable>]*</arg><arg choice="plain"><replaceable>jndi_name</replaceable></arg>
</cmdsynopsis></refsynopsisdiv>
<refsect1><title>&desc-tt;</title>
<para>The <command>create-jms-resource</command> command creates a Java Message
Service (JMS) connection factory resource or a JMS destination resource. This
command is supported in remote mode only.</para>
</refsect1>
<refsect1><title>&opts-tt;</title>
<variablelist termlength="medium">&options-common;
<varlistentry><term><option role="nodash">&Dash;&Dash;target</option></term>
<listitem><para>This option helps specify the target for which you are creating
the JMS resource. Valid values are:<itemizedlist>
<listitem><para><literal>server</literal>, which creates the resource for
the default server instance. This is the default value</para>
</listitem>
<listitem><para><literal>domain</literal>, which creates the resource for
the domain</para>
</listitem>
<listitem><para><replaceable>cluster_name</replaceable>, which creates the
resource for every server instance in the cluster</para>
</listitem>
<listitem><para><replaceable>instance_name</replaceable>, which creates the
resource for a particular server instance</para>
</listitem>
</itemizedlist></para>
<para>&se-ee-only;</para>
</listitem></varlistentry>
<varlistentry><term><option role="nodash">&Dash;&Dash;restype</option></term>
<listitem><para>The JMS resource type, which can be <filename>javax.jms.Topic
</filename>, <filename>javax.jms.Queue</filename>,<filename>javax.jms.TopicConnectionFactory
</filename>, or <filename>javax.jms.QueueConnectionFactory</filename>.</para>
</listitem></varlistentry>
<varlistentry><term><option role="nodash">&Dash;&Dash;enabled</option></term>
<listitem><para>If set to true, the resource is enabled at runtime.</para>
</listitem></varlistentry>
<varlistentry><term><option role="nodash">&Dash;&Dash;description</option></term>
<listitem><para>Text providing details of the JMS resource.</para>
</listitem></varlistentry>
<varlistentry><term><option role="nodash">&Dash;&Dash;property</option></term>
<listitem><para>Optional attribute name/value pairs for configuring the JMS
resource.</para>
<para>You can specify the following properties for a connection factory resource:
</para>
<informaltable frame="none" orient="port">
<tgroup cols="2">
<?PubTbl tgroup dispwid="9.17in">
<colspec colname="col1" colwidth="0.68*"><colspec colname="col2" colwidth="1.32*">
<thead>
<row><entry align="center" valign="top"><para>Property</para></entry><entry
align="center" valign="top"><para>Definition</para></entry></row>
</thead>
<tbody>
<row><entry colname="col1"><para>ClientId</para></entry><entry colname="col2"><para>
Specifies a client ID for a connection factory that will be used by a durable
subscriber.</para></entry></row>
<row><entry colname="col1"><para>AddressList</para></entry><entry colname="col2"><para>
This is a comma-separated list of message queue addresses. It specifies the
names (and, optionally, port numbers) of a message broker instance or instances
with which your application will communicate. Each address in the list specifies
the host name (and, optionally, host port and connection service) for the
connection. For example, the value could be <literal>earth</literal> or <literal>
earth:7677</literal>. Specify the port number if the message broker is running
on a port other than the default (7676). If you specify multiple hosts and
ports in a clustered environment, the first available host on the list is
used. Default: An address list composed from the jms-hosts defined in the
target's jms-service configuration. The default for PE is local host and the
default port number is 7676. The client will attempt a connection to a broker
on port 7676 of the local host.</para></entry></row>
<row><entry colname="col1"><para>MessageServiceAddressList</para></entry>
<entry colname="col2"><para>Same as <literal>AddressList</literal>. This property
name is deprecated. Use <literal>AddressList</literal> instead.</para></entry>
</row>
<row><entry colname="col1"><para>UserName</para></entry><entry colname="col2"><para>
The user name for the connection factory. Default: <literal>guest</literal>.
</para></entry></row>
<row><entry colname="col1"><para>Password</para></entry><entry colname="col2"><para>
The password for the connection factory. Default: <literal>guest</literal>.
</para></entry></row>
<row><entry colname="col1"><para>ReconnectEnabled</para></entry><entry colname="col2"><para>
If enabled (value = <literal>true</literal>), it indicates that the client
runtime attempts to reconnect to a message server (or the list of addresses
in the AddressList) when a connection is lost. Default: <literal>false</literal>.
</para></entry></row>
<row><entry colname="col1"><para>ReconnectAttempts</para></entry><entry colname="col2"><para>
Specifies the number of attempts to connect (or reconnect) for each address
in the AddressList before the client runtime tries the next address in the
list. A value of -1 indicates that the number of reconnect attempts is unlimited
(the client runtime attempts to connect to the first address until it succeeds).
Default: 6.</para></entry></row>
<row><entry colname="col1"><para>ReconnectInterval</para></entry><entry colname="col2"><para>
Specifies the interval in milliseconds between reconnect attempts. This applies
to attempts on each address in the AddressList and for successive addresses
in the list. If the interval is too short, the broker does not have time to
recover. If it is too long, the reconnect might represent an unacceptable
delay. Default: 30,000 milliseconds.</para></entry></row>
<row><entry colname="col1"><para>AddressListBehavior</para></entry><entry
colname="col2"><para>Specifies whether connection attempts are in the order
of addresses in the AddressList attribute (<literal>PRIORITY</literal>) or
in a random order (<literal>RANDOM</literal>). <literal>PRIORITY</literal>
means that the reconnect will always try to connect to the first server address
in the AddressList and will use another one only if the first broker is not
available. If you have many clients attempting a connection using the same
connection factory, specify <literal>RANDOM</literal> to prevent them from
all being connected to the same address. Default: The <literal>AddressListBehavior
</literal> value of the target's jms-service configuration.</para></entry>
</row>
<row><entry colname="col1"><para>AddressListIterations</para></entry><entry
colname="col2"><para>Specifies the number of times the client runtime iterates
through the AddressList in an effort to establish (or re-establish) a connection).
A value of -1 indicates that the number of attempts is unlimited. Default:
-1.</para></entry></row>
</tbody>
</tgroup>
</informaltable>
<para>You can specify the following properties for a destination resource:
</para>
<informaltable frame="none" orient="port">
<tgroup cols="2">
<?PubTbl tgroup dispwid="9.17in">
<colspec colname="col1" colwidth="0.68*"><colspec colname="col2" colwidth="1.32*">
<thead>
<row><entry align="center" valign="top"><para> Property</para></entry><entry
align="center" valign="top"><para>Definition</para></entry></row>
</thead>
<tbody>
<row><entry colname="col1"><para>Name</para></entry><entry colname="col2"><para>
(Required) This property specifies the name of the physical destination to
which the resource will refer. You create a physical destination with the <command>
create-jmsdest</command> command.</para></entry></row>
<row><entry colname="col1"><para>Description</para></entry><entry colname="col2"><para>
This property provides a description of the physical destination.</para></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</listitem></varlistentry>
</variablelist></refsect1>
<refsect1><title>OPERANDS</title>
<variablelist termlength="medium">
<varlistentry><term><replaceable>jndi_name</replaceable></term><listitem>
<para>The JNDI name of the JMS resource to be created.</para>
</listitem></varlistentry>
</variablelist></refsect1>
<refsect1><title>&exam-tt;</title>
<example>
<title>Creating a JMS connection factory resource for durable subscriptions
</title>
<para>The following command creates a connection factory resource of type <literal>
javax.jms.TopicConnectionFactory</literal> whose JNDI name is <literal>jms/DurableTopicConnectionFactory
</literal>. The <literal>ClientId</literal> property sets a client ID on the
connection factory so that it can be used for durable subscriptions. The JNDI
name for a JMS resource customarily includes the <literal>jms/</literal> naming
subcontext.</para>
<screen>asadmin> <userinput>create-jms-resource --user admin1 
--passwordfile passwords.txt --host pigeon --port 5001 
--restype javax.jms.TopicConnectionFactory --description 
"example of creating a JMS connection factory" 
--property ClientId=MyID jms/DurableTopicConnectionFactory</userinput>
Command create-jms-resource executed successfully.</screen>
</example>
<example>
<title>Creating a JMS destination resource</title>
<para>The following command creates a destination resource whose JNDI name
is <literal>jms/MyQueue</literal>. The <literal>Name</literal> property specifies
the physical destination to which the resource refers.</para>
<screen>asadmin> <userinput>create-jms-resource --user admin1 
--passwordfile passwords.txt --host pigeon --port 5001 
--restype javax.jms.Queue --property Name=PhysicalQueue jms/MyQueue</userinput>
Command create-jms-resource executed successfully.</screen>
</example>
</refsect1>
<refsect1><title>&exit-tt;</title>
<variablelist termlength="medium">
<varlistentry><term>0</term><listitem><para>command executed successfully
</para>
</listitem></varlistentry>
<varlistentry><term>1</term><listitem><para>error in executing the command
</para>
</listitem></varlistentry>
</variablelist></refsect1><?Pub Caret>
<refsect1><title>&also-tt;</title>
<para><link linkend="delete-jms-resource-1"><citerefentry><refentrytitle>
delete-jms-resource</refentrytitle><manvolnum>1</manvolnum></citerefentry></link>, <link
linkend="list-jms-resources-1"><citerefentry><refentrytitle>list-jms-resources
</refentrytitle><manvolnum>1</manvolnum></citerefentry></link>, <link linkend="create-jmsdest-1"><citerefentry>
<refentrytitle>create-jmsdest</refentrytitle><manvolnum>1</manvolnum></citerefentry></link></para>
</refsect1>
</refentry>
<?Pub *0000012097>
