You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@qpid.apache.org by ro...@apache.org on 2017/05/24 14:58:42 UTC
[3/8] qpid-cpp git commit: QPID-7756: remove stale AMQP 0-10 JMS
client content, a seperate book for that client was based on it via QPID-7265
QPID-7756: remove stale AMQP 0-10 JMS client content, a seperate book for that client was based on it via QPID-7265
Project: http://git-wip-us.apache.org/repos/asf/qpid-cpp/repo
Commit: http://git-wip-us.apache.org/repos/asf/qpid-cpp/commit/57cbe59b
Tree: http://git-wip-us.apache.org/repos/asf/qpid-cpp/tree/57cbe59b
Diff: http://git-wip-us.apache.org/repos/asf/qpid-cpp/diff/57cbe59b
Branch: refs/heads/master
Commit: 57cbe59b5a46a620553d28306b0da648a1272895
Parents: cbc5098
Author: Robert Gemmell <ro...@apache.org>
Authored: Wed May 24 15:45:04 2017 +0100
Committer: Robert Gemmell <ro...@apache.org>
Committed: Wed May 24 15:57:54 2017 +0100
----------------------------------------------------------------------
.../programming/Programming-In-Apache-Qpid.xml | 1256 ------------------
1 file changed, 1256 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/qpid-cpp/blob/57cbe59b/docs/book/src/programming/Programming-In-Apache-Qpid.xml
----------------------------------------------------------------------
diff --git a/docs/book/src/programming/Programming-In-Apache-Qpid.xml b/docs/book/src/programming/Programming-In-Apache-Qpid.xml
index 8bd9225..a16a7d9 100644
--- a/docs/book/src/programming/Programming-In-Apache-Qpid.xml
+++ b/docs/book/src/programming/Programming-In-Apache-Qpid.xml
@@ -2786,1262 +2786,6 @@ spout - -content "$(cat rdu.xml | sed -e 's/70/45/')" xml/weather
</chapter>
-
- <chapter id="QpidJMS">
- <title>Using the Qpid JMS client</title>
- <section>
- <title>A Simple Messaging Program in Java JMS</title>
-
- <para>The following program shows how to send and receive a
- message using the Qpid JMS client. JMS programs typically use
- JNDI to obtain connection factory and destination objects which
- the application needs. In this way the configuration is kept
- separate from the application code itself.</para>
-
- <para>In this example, we create a JNDI context using a
- properties file, use the context to lookup a connection factory,
- create and start a connection, create a session, and lookup a
- destination from the JNDI context. Then we create a producer and
- a consumer, send a message with the producer and receive it with
- the consumer. This code should be straightforward for anyone
- familiar with Java JMS.</para>
-
- <example>
- <title>"Hello world!" in Java</title>
- <programlisting lang="java">
- package org.apache.qpid.example.jmsexample.hello;
-
- import javax.jms.*;
- import javax.naming.Context;
- import javax.naming.InitialContext;
- import java.util.Properties;
-
- public class Hello {
-
- public Hello() {
- }
-
- public static void main(String[] args) {
- Hello producer = new Hello();
- producer.runTest();
- }
-
- private void runTest() {
- try {
- Properties properties = new Properties();
- properties.load(this.getClass().getResourceAsStream("hello.properties")); <co id="hello-java-properties" linkends="callout-java-properties"/>
- Context context = new InitialContext(properties); <co id="hello-java-context" linkends="callout-java-context"/>
-
- ConnectionFactory connectionFactory
- = (ConnectionFactory) context.lookup("qpidConnectionfactory"); <co id="hello-java-connection-factory" linkends="callout-java-connection-factory"/>
- Connection connection = connectionFactory.createConnection(); <co id="hello-java-connection" linkends="callout-java-connection"/>
- connection.start(); <co id="hello-java-start" linkends="callout-java-start"/>
-
- Session session=connection.createSession(false,Session.AUTO_ACKNOWLEDGE);<co id="hello-java-session" linkends="callout-java-session"/>
- Destination destination = (Destination) context.lookup("topicExchange"); <co id="hello-java-destination" linkends="callout-java-destination"/>
-
- MessageProducer messageProducer = session.createProducer(destination); <co id="hello-java-producer" linkends="callout-java-producer"/>
- MessageConsumer messageConsumer = session.createConsumer(destination); <co id="hello-java-consumer" linkends="callout-java-consumer"/>
-
- TextMessage message = session.createTextMessage("Hello world!");
- messageProducer.send(message);
-
- message = (TextMessage)messageConsumer.receive(); <co id="hello-java-receive" linkends="callout-java-receive"/>
- System.out.println(message.getText());
-
- connection.close(); <co id="hello-java-close" linkends="callout-java-close"/>
- context.close(); <co id="hello-java-jndi-close" linkends="callout-java-jndi-close"/>
- }
- catch (Exception exp) {
- exp.printStackTrace();
- }
- }
- }
- </programlisting>
- </example>
-
- <calloutlist>
- <callout id="callout-java-properties" arearefs="hello-java-properties">
- <para>Loads the JNDI properties file, which specifies connection properties, queues, topics, and addressing options. See <xref linkend="QpidJNDI"/> for details.</para>
- </callout>
- <callout id="callout-java-context" arearefs="hello-java-context">
- <para>Creates the JNDI initial context.</para>
- </callout>
- <callout id="callout-java-connection-factory" arearefs="hello-java-connection-factory">
- <para>Creates a JMS connection factory for Qpid.</para>
- </callout>
- <callout id="callout-java-connection" arearefs="hello-java-connection">
- <para>Creates a JMS connection.</para>
- </callout>
- <callout id="callout-java-start" arearefs="hello-java-start">
- <para>Activates the connection.</para>
- </callout>
- <callout id="callout-java-session" arearefs="hello-java-session">
- <para>Creates a session. This session is not transactional (transactions='false'), and messages are automatically acknowledged.</para>
- </callout>
- <callout id="callout-java-destination" arearefs="hello-java-destination">
- <para>Creates a destination for the topic exchange, so senders and receivers can use it.</para>
- </callout>
- <callout id="callout-java-producer" arearefs="hello-java-producer">
- <para>Creates a producer that sends messages to the topic exchange.</para>
- </callout>
- <callout id="callout-java-consumer" arearefs="hello-java-consumer">
- <para>Creates a consumer that reads messages from the topic exchange.</para>
- </callout>
- <callout id="callout-java-receive" arearefs="hello-java-receive">
- <para>Reads the next available message.</para>
- </callout>
- <callout id="callout-java-close" arearefs="hello-java-close">
- <para>Closes the connection, all sessions managed by the connection, and all senders and receivers managed by each session.</para>
- </callout>
- <callout id="callout-java-jndi-close" arearefs="hello-java-jndi-close">
- <para>Closes the JNDI context.</para>
- </callout>
- </calloutlist>
-
- <para>The contents of the hello.properties file are shown below.</para>
-
- <example>
- <title>JNDI Properties File for "Hello world!" example</title>
- <programlisting>
- java.naming.factory.initial
- = org.apache.qpid.jndi.PropertiesFileInitialContextFactory
-
- # connectionfactory.[jndiname] = [ConnectionURL]
- connectionfactory.qpidConnectionfactory
- = amqp://guest:guest@clientid/test?brokerlist='tcp://localhost:5672' <co id="hello-properties-connectionfactory" linkends="callout-hello-properties-connectionfactory"/>
- # destination.[jndiname] = [address_string]
- destination.topicExchange = amq.topic <co id="hello-properties-destination" linkends="callout-hello-properties-destination"/>
- </programlisting>
- </example>
-
- <calloutlist>
- <callout id="callout-hello-properties-connectionfactory" arearefs="hello-properties-connectionfactory">
- <para>Defines a connection factory from which connections
- can be created. The syntax of a ConnectionURL is given in
- <xref linkend="QpidJNDI"/>.</para>
- </callout>
- <callout id="callout-hello-properties-destination" arearefs="hello-properties-destination">
- <para>Defines a destination for which MessageProducers
- and/or MessageConsumers can be created to send and receive
- messages. The value for the destination in the properties
- file is an address string as described in
- <xref linkend="section-addresses"/>. In the JMS
- implementation MessageProducers are analogous to senders in
- the Qpid Message API, and MessageConsumers are analogous to
- receivers.</para>
- </callout>
- </calloutlist>
-
- </section>
-
- <section id="QpidJNDI">
- <title>Apache Qpid JNDI Properties for AMQP Messaging</title>
-
-
- <para>
- Apache Qpid defines JNDI properties that can be used to specify JMS Connections and Destinations. Here is a typical JNDI properties file:
- </para>
-
- <example>
- <title>JNDI Properties File</title>
- <programlisting><![CDATA[
- java.naming.factory.initial
- = org.apache.qpid.jndi.PropertiesFileInitialContextFactory
-
- # connectionfactory.[jndiname] = [ConnectionURL]
- connectionfactory.qpidConnectionfactory
- = amqp://guest:guest@clientid/test?brokerlist='tcp://localhost:5672'
- # destination.[jndiname] = [address_string]
- destination.topicExchange = amq.topic
- ]]></programlisting>
- </example>
-
- <para>The following sections describe the JNDI properties that Qpid uses.</para>
-
-
- <section>
- <title>JNDI Properties for Apache Qpid</title>
- <para>
- Apache Qpid supports the properties shown in the following table:
- </para>
- <table>
- <title>JNDI Properties supported by Apache Qpid</title>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>
- Property
- </entry>
- <entry>
- Purpose
- </entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>
- connectionfactory.<jndiname>
- </entry>
- <entry>
- <para>
- The Connection URL that the connection factory uses to perform connections.
- </para>
- </entry>
- </row>
- <row>
- <entry>
- queue.<jndiname>
- </entry>
- <entry>
- <para>
- A JMS queue, which is implemented as an amq.direct exchange in Apache Qpid.
- </para>
- </entry>
- </row>
- <row>
- <entry>
- topic.<jndiname>
- </entry>
- <entry>
- <para>
- A JMS topic, which is implemented as an amq.topic exchange in Apache Qpid.
- </para>
- </entry>
- </row>
- <row>
- <entry>
- destination.<jndiname>
- </entry>
- <entry>
- <para>
- Can be used for defining all amq destinations,
- queues, topics and header matching, using an
- address string.
-
- <footnote><para>Binding URLs, which were used in
- earlier versions of the Qpid Java JMS client, can
- still be used instead of address
- strings.</para></footnote>
- </para>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </section>
-
- <section id="section-jms-connection-url">
- <title>Connection URLs</title>
- <para>
- In JNDI properties, a Connection URL specifies properties for a connection. The format for a Connection URL is:
- </para>
-
- <programlisting>amqp://[<user>:<pass>@][<clientid>]<virtualhost>[?<option>='<value>'[&<option>='<value>']]
- </programlisting>
- <para>
- For instance, the following Connection URL specifies a user name, a password, a client ID, a virtual host ("test"), a broker list with a single broker, and a TCP host with the host name <quote>localhost</quote> using port 5672:
- </para>
-
- <programlisting>amqp://username:password@clientid/test?brokerlist='tcp://localhost:5672'
- </programlisting>
- <para>
- Apache Qpid supports the following properties in Connection URLs:
- </para>
- <table pgwide="1">
- <title>Connection URL Properties</title>
- <tgroup cols="3">
- <thead>
- <row>
- <entry>
- Option
- </entry>
- <entry>
- Type
- </entry>
- <entry>
- Description
- </entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>
- brokerlist
- </entry>
- <entry>
- see below
- </entry>
- <entry>
- List of one or more broker addresses.
- </entry>
- </row>
- <row>
- <entry>
- maxprefetch
- </entry>
- <entry>
- integer
- </entry>
- <entry>
- <para>
- The maximum number of pre-fetched messages per consumer. If not specified, default value of 500 is used.
- </para>
- <para>
- Note: You can also set the default per-consumer prefetch value on a client-wide basis by configuring the client using <link linkend="client-jvm-properties">Java system properties.</link>
- </para>
- </entry>
- </row>
- <row>
- <entry>
- sync_publish
- </entry>
- <entry>
- {'persistent' | 'all'}
- </entry>
- <entry>
- A sync command is sent after every persistent message to guarantee that it has been received; if the value is 'persistent', this is done only for persistent messages.
- </entry>
- </row>
- <row>
- <entry>
- sync_ack
- </entry>
- <entry>
- Boolean
- </entry>
- <entry>
- A sync command is sent after every acknowledgement to guarantee that it has been received.
- </entry>
- </row>
- <row>
- <entry>
- use_legacy_map_msg_format
- </entry>
- <entry>
- Boolean
- </entry>
- <entry>
- If you are using JMS Map messages and deploying a new client with any JMS client older than 0.8 release, you must set this to true to ensure the older clients can understand the map message encoding.
- </entry>
- </row>
- <row>
- <entry>
- failover
- </entry>
- <entry>
- {'singlebroker' | 'roundrobin' | 'failover_exchange' | 'nofailover' | '<class>'}
- </entry>
- <entry>
- <para>
- This option controls failover behaviour. The method <literal>singlebroker</literal> uses only the first broker in the list,
- <literal>roundrobin</literal> will try each broker given in the broker list until a connection is established,
- <literal>failover_exchange</literal> connects to the initial broker given in the broker URL and will receive membership updates
- via the failover exchange. <literal>nofailover</literal> disables all retry and failover logic. Any other value is interpreted as a
- classname which must implement the <literal>org.apache.qpid.jms.failover.FailoverMethod</literal> interface.
- </para>
- <para>
- The broker list options <literal>retries</literal> and <literal>connectdelay</literal> (described below) determine the number of times a
- connection to a broker will be retried and the the length of time to wait between successive connection attempts before moving on to
- the next broker in the list. The failover option <literal>cyclecount</literal> controls the number of times to loop through the list of
- available brokers before finally giving up.
- </para>
- <para>
- Defaults to <literal>roundrobin</literal> if the brokerlist contains multiple brokers, or <literal>singlebroker</literal> otherwise.
- </para>
- </entry>
- </row>
- <row>
- <entry>
- ssl
- </entry>
- <entry>
- boolean
- </entry>
- <entry>
- <para>
- If <literal>ssl='true'</literal>, use SSL for all broker connections. Overrides any per-broker settings in the brokerlist (see below) entries. If not specified, the brokerlist entry for each given broker is used to determine whether SSL is used.
- </para>
- <para>
- Introduced in version 0.22.
- </para>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- <para>
- Broker lists are specified using a URL in this format:
- </para>
-
- <programlisting>brokerlist=<transport>://<host>[:<port>](?<param>='<value>')(&<param>='<value>')*</programlisting>
- <para>
- For instance, this is a typical broker list:
- </para>
-
- <programlisting>brokerlist='tcp://localhost:5672'
- </programlisting>
-
- <para>
- A broker list can contain more than one broker address; if so, the connection is made to the first broker in the list that is available. In general, it is better to use the failover exchange when using multiple brokers, since it allows applications to fail over if a broker goes down.
- </para>
-
- <example>
- <title>Broker Lists</title>
- <para>A broker list can specify properties to be used when connecting to the broker, such as security options. This broker list specifies options for a Kerberos connection using GSSAPI:</para>
- <programlisting><![CDATA[
- amqp://guest:guest@test/test?sync_ack='true'
- &brokerlist='tcp://ip1:5672?sasl_mechs='GSSAPI''
- ]]></programlisting>
-
- <para>This broker list specifies SSL options:</para>
-
- <programlisting><![CDATA[
- amqp://guest:guest@test/test?sync_ack='true'
- &brokerlist='tcp://ip1:5672?ssl='true'&ssl_cert_alias='cert1''
- ]]></programlisting>
-
- <para>
- This broker list specifies two brokers using the connectdelay and retries broker options. It also illustrates the failover connection URL
- property.
- </para>
-
- <programlisting><![CDATA[
-
- amqp://guest:guest@/test?failover='roundrobin?cyclecount='2''
- &brokerlist='tcp://ip1:5672?retries='5'&connectdelay='2000';tcp://ip2:5672?retries='5'&connectdelay='2000''
- ]]></programlisting>
- </example>
-
- <para>The following broker list options are supported.</para>
-
- <table pgwide="1">
- <title>Broker List Options</title>
- <tgroup cols="3">
- <thead>
- <row>
- <entry>
- Option
- </entry>
- <entry>
- Type
- </entry>
- <entry>
- Description
- </entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>
- heartbeat
- </entry>
- <entry>
- integer
- </entry>
- <entry>
- Frequency of heartbeat messages (in seconds). A value of 0 disables heartbeating. <para>For compatibility
- with old client configuration, option <varname>idle_timeout</varname> (in milliseconds) is also supported.</para>
- </entry>
- </row>
- <row>
- <entry>
- sasl_mechs
- </entry>
- <entry>
- --
- </entry>
- <entry>
- For secure applications, we suggest CRAM-MD5,
- DIGEST-MD5, or GSSAPI. The ANONYMOUS method is not
- secure. The PLAIN method is secure only when used
- together with SSL. For Kerberos, sasl_mechs must be
- set to GSSAPI, sasl_protocol must be set to the
- principal for the qpidd broker, e.g. qpidd/, and
- sasl_server must be set to the host for the SASL
- server, e.g. sasl.com. SASL External is supported
- using SSL certification, e.g.
- <literal>ssl='true'&sasl_mechs='EXTERNAL'</literal>
- </entry>
- </row>
- <row>
- <entry>
- sasl_encryption
- </entry>
- <entry>
- Boolean
- </entry>
- <entry>
- If <literal>sasl_encryption='true'</literal>, the JMS client attempts to negotiate a security layer with the broker using GSSAPI to encrypt the connection. Note that for this to happen, GSSAPI must be selected as the sasl_mech.
- </entry>
- </row>
- <row>
- <entry>
- sasl_protocol
- </entry>
- <entry>
- --
- </entry>
- <entry>
- Used only for
- Kerberos. <literal>sasl_protocol</literal> must be
- set to the principal for the qpidd broker,
- e.g. <literal>qpidd/</literal>
- </entry>
- </row>
- <row>
- <entry>
- sasl_server
- </entry>
- <entry>
- --
- </entry>
- <entry>
- For Kerberos, sasl_mechs must be set to GSSAPI,
- sasl_server must be set to the host for the SASL
- server, e.g. <literal>sasl.com</literal>.
- </entry>
- </row>
- <row>
- <entry>
- trust_store
- </entry>
- <entry>
- --
- </entry>
- <entry>
- path to trust store
- </entry>
- </row>
- <row>
- <entry>
- trust_store_password
- </entry>
- <entry>
- --
- </entry>
- <entry>
- Trust store password
- </entry>
- </row>
- <row>
- <entry>
- key_store
- </entry>
- <entry>
- --
- </entry>
- <entry>
- path to key store
- </entry>
- </row>
- <row>
- <entry>
- key_store_password
- </entry>
- <entry>
- --
- </entry>
- <entry>
- key store password
- </entry>
- </row>
- <row>
- <entry>
- ssl
- </entry>
- <entry>
- Boolean
- </entry>
- <entry>
- <para>If <literal>ssl='true'</literal>, the JMS client will encrypt the connection to this broker using SSL.</para>
-
- <para>This can also be set/overridden for all brokers using the <link linkend="section-jms-connection-url">Connection URL</link> options.</para>
- </entry>
- </row>
- <row>
- <entry>
- ssl_verify_hostname
- </entry>
- <entry>
- Boolean
- </entry>
- <entry>
- When using SSL you can enable hostname verification
- by using <literal>ssl_verify_hostname='true'</literal> in the broker
- URL.
- </entry>
- </row>
- <row>
- <entry>
- ssl_cert_alias
- </entry>
- <entry>
- --
- </entry>
- <entry>
- If multiple certificates are present in the keystore, the alias will be used to extract the correct certificate.
- </entry>
- </row>
- <row>
- <entry>
- retries
- </entry>
- <entry>
- integer
- </entry>
- <entry>
- The number of times to retry connection to each broker in the broker list. Defaults to 1.
- </entry>
- </row>
- <row>
- <entry>
- connectdelay
- </entry>
- <entry>
- integer
- </entry>
- <entry>
- Length of time (in milliseconds) to wait before attempting to reconnect. Defaults to 0.
- </entry>
- </row>
- <row>
- <entry>
- connecttimeout
- </entry>
- <entry>
- integer
- </entry>
- <entry>
- Length of time (in milliseconds) to wait for the socket connection to succeed. A value of 0 represents an infinite timeout, i.e. the connection attempt will block until established or an error occurs. Defaults to 30000.
- </entry>
- </row>
- <row>
- <entry>
- tcp_nodelay
- </entry>
- <entry>
- Boolean
- </entry>
- <entry>
- If <literal>tcp_nodelay='true'</literal>, TCP packet
- batching is disabled. Defaults to true since Qpid 0.14.
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </section>
- </section>
-
- <section>
- <title>Java JMS Message Properties</title>
-
- <para>The following table shows how Qpid Messaging API message
- properties are mapped to AMQP 0-10 message properties and
- delivery properties. In this table <varname>msg</varname>
- refers to the Message class defined in the Qpid Messaging API,
- <varname>mp</varname> refers to an AMQP 0-10
- <varname>message-properties</varname> struct, and
- <varname>dp</varname> refers to an AMQP 0-10
- <varname>delivery-properties</varname> struct.</para>
-
- <table >
- <title>Java JMS Mapping to AMQP 0-10 Message Properties</title>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Java JMS Message Property</entry>
- <entry>AMQP 0-10 Property<footnote><para>In these entries, <literal>mp</literal> refers to an AMQP message property, and <literal>dp</literal> refers to an AMQP delivery property.</para></footnote></entry>
-
- </row>
- </thead>
- <tbody>
- <row>
- <entry>JMSMessageID</entry><entry>mp.message_id</entry>
- </row>
- <row>
- <entry>qpid.subject<footnote><para>This is a custom JMS property, set automatically by the Java JMS client implementation.</para></footnote></entry><entry>mp.application_headers["qpid.subject"]</entry>
- </row>
- <row>
- <entry>JMSXUserID</entry><entry>mp.user_id</entry>
- </row>
- <row>
- <entry>JMSReplyTo</entry><entry>mp.reply_to<footnote><para>The reply_to is converted from the protocol representation into an address.</para></footnote></entry>
- </row>
- <row>
- <entry>JMSCorrelationID</entry><entry>mp.correlation_id</entry>
- </row>
- <row>
- <entry>JMSDeliveryMode</entry><entry>dp.delivery_mode</entry>
- </row>
- <row>
- <entry>JMSPriority</entry><entry>dp.priority</entry>
- </row>
- <row>
- <entry>JMSExpiration</entry><entry>dp.ttl<footnote><para>JMSExpiration = dp.ttl + currentTime</para></footnote></entry>
- </row>
- <row>
- <entry>JMSRedelivered</entry><entry>dp.redelivered</entry>
- </row>
- <row>
- <entry>JMS Properties</entry><entry>mp.application_headers</entry>
- </row>
- <row>
- <entry>JMSType</entry><entry>mp.content_type</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- </section>
-
- <section id="section-JMS-MapMessage">
- <title>JMS MapMessage Types</title>
-
- <para>Qpid supports the Java JMS <classname>MapMessage</classname> interface, which provides support for maps in messages. The following code shows how to send a <classname>MapMessage</classname> in Java JMS.</para>
-
- <example>
- <title>Sending a Java JMS MapMessage</title>
- <programlisting><![CDATA[
- import java.util.ArrayList;
- import java.util.HashMap;
- import java.util.List;
- import java.util.Map;
-
- import javax.jms.Connection;
- import javax.jms.Destination;
- import javax.jms.MapMessage;
- import javax.jms.MessageProducer;
- import javax.jms.Session;
-
- import java.util.Arrays;
-
- // !!! SNIP !!!
-
- MessageProducer producer = session.createProducer(queue);
-
- MapMessage m = session.createMapMessage();
- m.setIntProperty("Id", 987654321);
- m.setStringProperty("name", "Widget");
- m.setDoubleProperty("price", 0.99);
-
- List<String> colors = new ArrayList<String>();
- colors.add("red");
- colors.add("green");
- colors.add("white");
- m.setObject("colours", colors);
-
- Map<String,Double> dimensions = new HashMap<String,Double>();
- dimensions.put("length",10.2);
- dimensions.put("width",5.1);
- dimensions.put("depth",2.0);
- m.setObject("dimensions",dimensions);
-
- List<List<Integer>> parts = new ArrayList<List<Integer>>();
- parts.add(Arrays.asList(new Integer[] {1,2,5}));
- parts.add(Arrays.asList(new Integer[] {8,2,5}));
- m.setObject("parts", parts);
-
- Map<String,Object> specs = new HashMap<String,Object>();
- specs.put("colours", colors);
- specs.put("dimensions", dimensions);
- specs.put("parts", parts);
- m.setObject("specs",specs);
-
- producer.send(m);
- ]]></programlisting>
- </example>
-
- <para>The following table shows the datatypes that can be sent in a <classname>MapMessage</classname>, and the corresponding datatypes that will be received by clients in Python or C++.</para>
-
- <table id="table-Java-Maps">
- <title>Java Datatypes in Maps</title>
- <tgroup cols="3">
- <thead>
- <row>
- <entry>Java Datatype</entry>
- <entry>→ Python</entry>
- <entry>→ C++</entry>
- </row>
- </thead>
- <tbody>
- <row><entry>boolean</entry><entry>bool</entry><entry>bool</entry></row>
- <row><entry>short</entry><entry>int | long</entry><entry>int16</entry></row>
- <row><entry>int</entry><entry>int | long</entry><entry>int32</entry></row>
- <row><entry>long</entry><entry>int | long</entry><entry>int64</entry></row>
- <row><entry>float</entry><entry>float</entry><entry>float</entry></row>
- <row><entry>double</entry><entry>float</entry><entry>double</entry></row>
- <row><entry>java.lang.String</entry><entry>unicode</entry><entry>std::string</entry></row>
- <row><entry>java.util.UUID</entry><entry>uuid</entry><entry>qpid::types::Uuid</entry></row>
- <row><entry>java.util.Map<footnote><para>In Qpid, maps can nest. This goes beyond the functionality required by the JMS specification.</para></footnote></entry><entry>dict</entry><entry>Variant::Map</entry></row>
- <row><entry>java.util.List</entry><entry>list</entry><entry>Variant::List</entry></row>
- </tbody>
- </tgroup>
- </table>
-
- </section>
-
- <section id="section-JMS-Logging">
- <title>JMS Client Logging</title>
- <para>The JMS Client logging is handled using the Simple Logging Facade for Java (<ulink url="http://www.slf4j.org/">SLF4J</ulink>). As the name implies, slf4j is a facade that delegates to other logging systems like log4j or JDK 1.4 logging. For more information on how to configure slf4j for specific logging systems, please consult the slf4j documentation.</para>
-
- <para>When using the log4j binding, please set the log level for org.apache.qpid explicitly. Otherwise log4j will default to DEBUG which will degrade performance considerably due to excessive logging. The recommended logging level for production is <literal>WARN</literal>.</para>
-
- <para>The following example shows the logging properties used to configure client logging for slf4j using the log4j binding. These properties can be placed in a log4j.properties file and placed in the <varname>CLASSPATH</varname>, or they can be set explicitly using the <literal>-Dlog4j.configuration</literal> property.</para>
-
- <example>
- <title>log4j Logging Properties</title>
-
- <programlisting><![CDATA[
- log4j.logger.org.apache.qpid=WARN, console
- log4j.additivity.org.apache.qpid=false
-
- log4j.appender.console=org.apache.log4j.ConsoleAppender
- log4j.appender.console.Threshold=all
- log4j.appender.console.layout=org.apache.log4j.PatternLayout
- log4j.appender.console.layout.ConversionPattern=%t %d %p [%c{4}] %m%n
- ]]></programlisting>
- </example>
-
- </section>
-
- <section>
- <title>Configuring the JMS Client</title>
-
- <para>The Qpid JMS Client allows several configuration options to customize it's behaviour at different levels of granualarity.</para>
-
- <itemizedlist>
- <listitem>
- <para>
- JVM level using JVM arguments : Configuration that affects all connections, sessions, consumers and producers created within that JVM.
- </para>
- <para>Ex. <varname>-Dmax_prefetch=1000</varname> property specifies the message credits to use.</para>
- </listitem>
-
- <listitem>
- <para>
- Connection level using Connection/Broker properties : Affects the respective connection and sessions, consumers and produces created by that connection.
- </para>
- <para>Ex. <varname>amqp://guest:guest@test/test?max_prefetch='1000'
- &brokerlist='tcp://localhost:5672'
- </varname> property specifies the message credits to use. This overrides any value specified via the JVM argument <varname>max_prefetch</varname>.</para>
- <para>Please refer to the <xref linkend="section-jms-connection-url"/> section for a complete list of all properties and how to use them.</para>
- </listitem>
-
- <listitem>
- <para>
- Destination level using Addressing options : Affects the producer(s) and consumer(s) created using the respective destination.
- </para>
- <para>Ex. <varname>my-queue; {create: always, link:{capacity: 10}}</varname>, where <varname>capacity</varname> option specifies the message credits to use. This overrides any connection level configuration.</para>
- <para>Please refer to the <xref linkend="section-addresses"/> section for a complete understanding of addressing and it's various options.</para>
- </listitem>
- </itemizedlist>
-
- <para>Some of these config options are available at all three levels (Ex. <varname>max_prefetch</varname>), while others are available only at JVM or connection level.</para>
-
- <section id="client-jvm-properties">
- <title>Qpid JVM Arguments</title>
-
- <table >
- <title>Config Options For Connection Behaviour</title>
- <tgroup cols="4">
- <thead>
- <row>
- <entry>Property Name</entry>
- <entry>Type</entry>
- <entry>Default Value</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>qpid.amqp.version</entry>
- <entry>string</entry>
- <entry>0-10</entry>
- <entry><para>Sets the AMQP version to be used - currently supports one of {0-8,0-9,0-91,0-10}.</para><para>The client will begin negotiation at the specified version and only negotiate downwards if the Broker does not support the specified version.</para></entry>
- </row>
- <row>
- <entry>qpid.heartbeat</entry>
- <entry>int</entry>
- <entry><para>When using the 0-10 protocol, the default is 120 (secs)</para><para>When using protocols 0-8...0-91, the default is the broker-supplied value.</para></entry>
- <entry>Frequency of heartbeat messages (in seconds). A value of 0 disables heartbeating. <para>Two consective misssed heartbeats will result in the connection timing out.</para><para>This can also be set per connection using the <link linkend="section-jms-connection-url">Connection URL</link> options.</para><para>For compatibility with old client configuration, the synonym <varname>amqj.heartbeat.delay</varname> is supported.</para></entry>
- </row>
- <row>
- <entry>ignore_setclientID</entry>
- <entry>boolean</entry>
- <entry>false</entry>
- <entry>If a client ID is specified in the connection URL it's used or else an ID is generated. If an ID is specified after it's been set Qpid will throw an exception. <para>Setting this property to 'true' will disable that check and allow you to set a client ID of your choice later on.</para></entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
-
- <table >
- <title>Config Options For Session Behaviour</title>
- <tgroup cols="4">
- <thead>
- <row>
- <entry>Property Name</entry>
- <entry>Type</entry>
- <entry>Default Value</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>qpid.session.command_limit</entry>
- <entry>int</entry>
- <entry>65536</entry>
- <entry>Limits the # of unacked commands</entry>
- </row>
-
- <row>
- <entry>qpid.session.byte_limit</entry>
- <entry>int</entry>
- <entry>1048576</entry>
- <entry>Limits the # of unacked commands in terms of bytes</entry>
- </row>
-
- <row>
- <entry>qpid.use_legacy_map_message</entry>
- <entry>boolean</entry>
- <entry>false</entry>
- <entry><para>If set will use the old map message encoding. By default the Map messages are encoded using the 0-10 map encoding.</para><para>This can also be set per connection using the <link linkend="section-jms-connection-url">Connection URL</link> options.</para></entry>
- </row>
-
- <row>
- <entry>qpid.jms.daemon.dispatcher</entry>
- <entry>boolean</entry>
- <entry>false</entry>
- <entry><para>Controls whether the Session dispatcher thread is a daemon thread or not. If this system property is set to true then the Session dispatcher threads will be created as daemon threads. This setting is introduced in version 0.16.</para></entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table >
- <title>Config Options For Consumer Behaviour</title>
- <tgroup cols="4">
- <thead>
- <row>
- <entry>Property Name</entry>
- <entry>Type</entry>
- <entry>Default Value</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>max_prefetch</entry>
- <entry>int</entry>
- <entry>500</entry>
- <entry>Maximum number of pre-fetched messages per consumer. <para>This can also be defaulted for consumers created on a particular connection using the <link linkend="section-jms-connection-url">Connection URL</link> options, or per destination (see the <varname>capacity</varname> option under link properties in addressing)</para></entry>
- </row>
-
- <row>
- <entry>qpid.session.max_ack_delay</entry>
- <entry>long</entry>
- <entry>1000 (ms)</entry>
- <entry><para>Timer interval to flush message acks in buffer when using AUTO_ACK and DUPS_OK.</para> <para>When using the above ack modes, message acks are batched and sent if one of the following conditions are met (which ever happens first).
- <itemizedlist>
- <listitem><para>When the ack timer fires.</para></listitem>
- <listitem><para>if un_acked_msg_count > max_prefetch/2.</para></listitem>
- </itemizedlist>
- </para>
- <para>The ack timer can be disabled by setting it to 0.</para>
- </entry>
- </row>
-
- <row>
- <entry>sync_ack</entry>
- <entry>boolean</entry>
- <entry>false</entry>
- <entry><para>If set, each message will be acknowledged synchronously. When using AUTO_ACK mode, you need to set this to "true", in order to get the correct behaviour as described by the JMS spec.</para><para>This is set to false by default for performance reasons, therefore by default AUTO_ACK behaves similar to DUPS_OK.</para><para>This can also be set per connection using the <link linkend="section-jms-connection-url">Connection URL</link> options.</para></entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table >
- <title>Config Options For Producer Behaviour</title>
- <tgroup cols="4">
- <thead>
- <row>
- <entry>Property Name</entry>
- <entry>Type</entry>
- <entry>Default Value</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>sync_publish</entry>
- <entry>string</entry>
- <entry>"" (disabled)</entry>
- <entry><para>If one of {persistent|all} is set then persistent messages or all messages will be sent synchronously.</para><para>This can also be set per connection using the <link linkend="section-jms-connection-url">Connection URL</link> options.</para></entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table >
- <title>Config Options For Threading</title>
- <tgroup cols="4">
- <thead>
- <row>
- <entry>Property Name</entry>
- <entry>Type</entry>
- <entry>Default Value</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>qpid.thread_factory</entry>
- <entry>string</entry>
- <entry>org.apache.qpid.thread.DefaultThreadFactory</entry>
- <entry><para>Specifies the thread factory to use.</para><para>If using a real time JVM, you need to set the above property to <varname>org.apache.qpid.thread.RealtimeThreadFactory</varname>.</para></entry>
- </row>
-
- <row>
- <entry>qpid.rt_thread_priority</entry>
- <entry>int</entry>
- <entry>20</entry>
- <entry><para>Specifies the priority (1-99) for Real time threads created by the real time thread factory.</para></entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table >
- <title>Config Options For I/O</title>
- <tgroup cols="4">
- <thead>
- <row>
- <entry>Property Name</entry>
- <entry>Type</entry>
- <entry>Default Value</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>qpid.transport</entry>
- <entry>string</entry>
- <entry>org.apache.qpid.transport.network.io.IoNetworkTransport</entry>
- <entry><para>The transport implementation to be used.</para><para>A user could specify an alternative transport mechanism that implements the interface <varname>org.apache.qpid.transport.network.OutgoingNetworkTransport</varname>.</para></entry>
- </row>
- <row>
- <entry>qpid.sync_op_timeout</entry>
- <entry>long</entry>
- <entry>60000</entry>
- <entry><para>The length of time (in milliseconds) to wait for a synchronous operation to complete.</para><para>For compatibility with older clients, the synonym <varname>amqj.default_syncwrite_timeout</varname> is supported.</para></entry>
- </row>
- <row>
- <entry>qpid.tcp_nodelay</entry>
- <entry>boolean</entry>
- <entry>true</entry>
- <entry>
- <para>Sets the TCP_NODELAY property of the underlying socket. The default was changed to true as of Qpid 0.14.</para>
- <para>This can also be set per connection using the <link linkend="section-jms-connection-url">Connection URL</link> options.</para>
- <para>For compatibility with older clients, the synonym <varname>amqj.tcp_nodelay</varname> is supported.</para>
- </entry>
- </row>
- <row>
- <entry>qpid.send_buffer_size</entry>
- <entry>integer</entry>
- <entry>65535</entry>
- <entry>
- <para>Sets the SO_SNDBUF property of the underlying socket. Added in Qpid 0.16.</para>
- <para>For compatibility with older clients, the synonym <varname>amqj.sendBufferSize</varname> is supported.</para>
- </entry>
- </row>
- <row>
- <entry>qpid.receive_buffer_size</entry>
- <entry>integer</entry>
- <entry>65535</entry>
- <entry>
- <para>Sets the SO_RCVBUF property of the underlying socket. Added in Qpid 0.16.</para>
- <para>For compatibility with older clients, the synonym <varname>amqj.receiveBufferSize</varname> is supported.</para>
- </entry>
- </row>
- <row>
- <entry>qpid.failover_method_timeout</entry>
- <entry>long</entry>
- <entry>60000</entry>
- <entry>
- <para>During failover, this is the timeout for each attempt to try to re-establish the connection.
- If a reconnection attempt exceeds the timeout, the entire failover process is aborted.</para>
- <para>It is only applicable for AMQP 0-8/0-9/0-9-1 clients.</para>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table >
- <title>Config Options For Security</title>
- <tgroup cols="4">
- <thead>
- <row>
- <entry>Property Name</entry>
- <entry>Type</entry>
- <entry>Default Value</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>qpid.sasl_mechs</entry>
- <entry>string</entry>
- <entry>PLAIN</entry>
- <entry><para>The SASL mechanism to be used. More than one could be specified as a comma separated list.</para><para>We currently support the following mechanisms {PLAIN | GSSAPI | EXTERNAL}.</para><para>This can also be set per connection using the <link linkend="section-jms-connection-url">Connection URL</link> options.</para></entry>
- </row>
-
- <row>
- <entry>qpid.sasl_protocol</entry>
- <entry>string</entry>
- <entry>AMQP</entry>
- <entry><para>When using GSSAPI as the SASL mechanism, <varname>sasl_protocol</varname> must be set to the principal for the qpidd broker, e.g. <varname>qpidd</varname>.</para><para>This can also be set per connection using the <link linkend="section-jms-connection-url">Connection URL</link> options.</para></entry>
- </row>
-
- <row>
- <entry>qpid.sasl_server_name</entry>
- <entry>string</entry>
- <entry>localhost</entry>
- <entry><para>When using GSSAPI as the SASL mechanism, <varname>sasl_server</varname> must be set to the host for the SASL server, e.g. <varname>example.com</varname>.</para><para>This can also be set per connection using the <link linkend="section-jms-connection-url">Connection URL</link> options.</para></entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table>
- <title>Config Options For Security - Standard JVM properties needed when using GSSAPI as the SASL mechanism.<footnote><para>Please refer to the Java security documentation for a complete understanding of the above properties.</para></footnote></title>
- <tgroup cols="4">
- <thead>
- <row>
- <entry>Property Name</entry>
- <entry>Type</entry>
- <entry>Default Value</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>javax.security.auth.useSubjectCredsOnly</entry>
- <entry>boolean</entry>
- <entry>true</entry>
- <entry><para>If set to 'false', forces the SASL GASSPI client to obtain the kerberos credentials explicitly instead of obtaining from the "subject" that owns the current thread.</para></entry>
- </row>
-
- <row>
- <entry>java.security.auth.login.config</entry>
- <entry>string</entry>
- <entry></entry>
- <entry><para>Specifies the jass configuration file.</para><para><varname>Ex-Djava.security.auth.login.config=myjas.conf</varname>
- </para><para>Here is the sample myjas.conf JASS configuration file: <programlisting><![CDATA[
-
- com.sun.security.jgss.initiate {
- com.sun.security.auth.module.Krb5LoginModule required useTicketCache=true;
- };
-
- ]]></programlisting></para></entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table>
- <title>Config Options For Security - Using SSL for securing connections or using EXTERNAL as the SASL mechanism.</title>
- <tgroup cols="4">
- <thead>
- <row>
- <entry>Property Name</entry>
- <entry>Type</entry>
- <entry>Default Value</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>qpid.ssl_timeout</entry>
- <entry>long</entry>
- <entry>60000</entry>
- <entry><para>Timeout value used by the Java SSL engine when waiting on operations.</para></entry>
- </row>
-
- <row>
- <entry>qpid.ssl.KeyManagerFactory.algorithm</entry>
- <entry>string</entry>
- <entry>-</entry>
- <entry>
- <para>The key manager factory algorithm name. If not set, defaults to the value returned from the Java runtime call <literal>KeyManagerFactory.getDefaultAlgorithm()</literal></para>
- <para>For compatibility with older clients, the synonym <varname>qpid.ssl.keyStoreCertType</varname> is supported.</para>
- </entry>
- </row>
-
- <row>
- <entry>qpid.ssl.TrustManagerFactory.algorithm</entry>
- <entry>string</entry>
- <entry>-</entry>
- <entry>
- <para>The trust manager factory algorithm name. If not set, defaults to the value returned from the Java runtime call <literal>TrustManagerFactory.getDefaultAlgorithm()</literal></para>
- <para>For compatibility with older clients, the synonym <varname>qpid.ssl.trustStoreCertType</varname> is supported.</para>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table>
- <title>Config Options For Security - Standard JVM properties needed when Using SSL for securing connections or using EXTERNAL as the SASL mechanism.<footnote><para>Qpid allows you to have per connection key and trust stores if required. If specified per connection, the JVM arguments are ignored.</para></footnote></title>
- <tgroup cols="4">
- <thead>
- <row>
- <entry>Property Name</entry>
- <entry>Type</entry>
- <entry>Default Value</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>javax.net.ssl.keyStore</entry>
- <entry>string</entry>
- <entry>jvm default</entry>
- <entry><para>Specifies the key store path.</para><para>This can also be set per connection using the <link linkend="section-jms-connection-url">Connection URL</link> options.</para></entry>
- </row>
-
- <row>
- <entry>javax.net.ssl.keyStorePassword</entry>
- <entry>string</entry>
- <entry>jvm default</entry>
- <entry><para>Specifies the key store password.</para><para>This can also be set per connection using the <link linkend="section-jms-connection-url">Connection URL</link> options.</para></entry>
- </row>
-
- <row>
- <entry>javax.net.ssl.trustStore</entry>
- <entry>string</entry>
- <entry>jvm default</entry>
- <entry><para>Specifies the trust store path.</para><para>This can also be set per connection using the <link linkend="section-jms-connection-url">Connection URL</link> options.</para></entry>
- </row>
-
- <row>
- <entry>javax.net.ssl.trustStorePassword</entry>
- <entry>string</entry>
- <entry>jvm default</entry>
- <entry><para>Specifies the trust store password.</para><para>This can also be set per connection using the <link linkend="section-jms-connection-url">Connection URL</link> options.</para></entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </section>
- </section>
-
- </chapter>
-
<chapter id="QpidWCF">
<title>Using the Qpid WCF client</title>
<section>
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@qpid.apache.org
For additional commands, e-mail: commits-help@qpid.apache.org