http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/large-messages.xml ---------------------------------------------------------------------- diff --git a/docs/user-manual/en/large-messages.xml b/docs/user-manual/en/large-messages.xml deleted file mode 100644 index 43bc2a8..0000000 --- a/docs/user-manual/en/large-messages.xml +++ /dev/null @@ -1,285 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!-- ============================================================================= --> -<!-- Licensed to the Apache Software Foundation (ASF) under one or more --> -<!-- contributor license agreements. See the NOTICE file distributed with --> -<!-- this work for additional information regarding copyright ownership. --> -<!-- The ASF licenses this file to You under the Apache License, Version 2.0 --> -<!-- (the "License"); you may not use this file except in compliance with --> -<!-- the License. You may obtain a copy of the License at --> -<!-- --> -<!-- http://www.apache.org/licenses/LICENSE-2.0 --> -<!-- --> -<!-- Unless required by applicable law or agreed to in writing, software --> -<!-- distributed under the License is distributed on an "AS IS" BASIS, --> -<!-- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. --> -<!-- See the License for the specific language governing permissions and --> -<!-- limitations under the License. --> -<!-- ============================================================================= --> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"; [ -<!ENTITY % BOOK_ENTITIES SYSTEM "ActiveMQ_User_Manual.ent"> -%BOOK_ENTITIES; -]> -<chapter id="large-messages"> - <title>Large Messages</title> - <para>ActiveMQ supports sending and receiving of huge messages, even when the client and server - are running with limited memory. The only realistic limit to the size of a message that can - be sent or consumed is the amount of disk space you have available. We have tested sending - and consuming messages up to 8 GiB in size with a client and server running in just 50MiB of - RAM!</para> - <para>To send a large message, the user can set an <literal>InputStream</literal> on a message - body, and when that message is sent, ActiveMQ will read the <literal>InputStream</literal>. A - <literal>FileInputStream</literal> could be used for example to send a huge message from - a huge file on disk.</para> - <para>As the <literal>InputStream</literal> is read the data is sent to the server as a stream - of fragments. The server persists these fragments to disk as it receives them and when the - time comes to deliver them to a consumer they are read back of the disk, also in fragments - and sent down the wire. When the consumer receives a large message it initially receives - just the message with an empty body, it can then set an <literal>OutputStream</literal> on - the message to stream the huge message body to a file on disk or elsewhere. At no time is - the entire message body stored fully in memory, either on the client or the server.</para> - <section id="large.message.configuring"> - <title>Configuring the server</title> - <para>Large messages are stored on a disk directory on the server side, as configured on the - main configuration file.</para> - <para>The configuration property <literal>large-messages-directory</literal> specifies where - large messages are stored.</para> - <programlisting> -<configuration xmlns="urn:activemq" - xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; - xsi:schemaLocation="urn:activemq /schema/activemq-configuration.xsd"> -... -<large-messages-directory>/data/large-messages</large-messages-directory> -... -</configuration</programlisting> - <para>By default the large message directory is <literal>data/largemessages</literal></para> - <para>For the best performance we recommend large messages directory is stored on a - different physical volume to the message journal or paging directory.</para> - </section> - <section> - <title>Configuring Parameters</title> - <para>Any message larger than a certain size is considered a large message. Large messages - will be split up and sent in fragments. This is determined by the parameter <literal - >min-large-message-size</literal></para> - <note> - <para>ActiveMQ messages are encoded using 2 bytes per character so if the message data is filled - with ASCII characters (which are 1 byte) the size of the resulting ActiveMQ message would roughly - double. This is important when calculating the size of a "large" message as it may appear to be - less than the <literal>min-large-message-size</literal> before it is sent, but it then turns into - a "large" message once it is encoded.</para> - </note> - <para>The default value is 100KiB.</para> - <section id="large-messages.core.config"> - <title>Using Core API</title> - <para>If the ActiveMQ Core API is used, the minimal large message size is specified by - <literal>ServerLocator.setMinLargeMessageSize</literal>.</para> - <programlisting> -ServerLocator locator = ActiveMQClient.createServerLocatorWithoutHA(new TransportConfiguration(NettyConnectorFactory.class.getName())) - -locator.setMinLargeMessageSize(25 * 1024); - -ClientSessionFactory factory = ActiveMQClient.createClientSessionFactory();</programlisting> - <para><xref linkend="configuring-transports.client.side"/> will provide more information - on how to instantiate the session factory.</para> - </section> - <section> - <title>Using JMS</title> - <para>If JNDI is used to instantiate and look up the connection factory, the minimum large message size - is configured in the JNDI context environment, e.g. <literal>jndi.properties</literal>. Here's a simple - example using the "ConnectionFactory" connection factory which is available in the context by default:</para> - <programlisting> -java.naming.factory.initial=org.apache.activemq.jndi.ActiveMQInitialContextFactory -java.naming.provider.url=tcp://localhost:5445 -connection.ConnectionFactory.minLargeMessageSize=250000 - </programlisting> - <para>If the connection factory is being instantiated directly, the minimum large - message size is specified by <literal - >ActiveMQConnectionFactory.setMinLargeMessageSize</literal>.</para> - </section> - <section> - <title>Compressed Large Messages</title> - <para> - You can choose to send large messages in compressed form using <literal> - compress-large-messages</literal> attributes. - </para> - <section> - <title><literal>compress-large-messages</literal></title> - <para>If you specify the boolean property <literal>compress-large-messages</literal> on - the <literal>server locator</literal> or <literal>ConnectionFactory</literal> as true, The - system will use the ZIP algorithm to compress the message body as the message is - transferred to the server's side. Notice that there's no special treatment at the - server's side, all the compressing and uncompressing is done at the client.</para> - <para>If the compressed size of a large message is below <literal> - min-large-message-size</literal>, it is sent to server as regular messages. This means - that the message won't be written into the server's large-message - data directory, thus reducing the disk I/O.</para> - </section> - <section> - <para>If JNDI is used to instantiate and look up the connection factory, large message compression can be - configured in the JNDI context environment, e.g. <literal>jndi.properties</literal>. Here's a simple - example using the "ConnectionFactory" connection factory which is available in the context by default:</para> - <programlisting> -java.naming.factory.initial=org.apache.activemq.jndi.ActiveMQInitialContextFactory -java.naming.provider.url=tcp://localhost:5445 -connection.ConnectionFactory.compressLargeMessages=true</programlisting> - </section> - </section> - </section> - <section> - <title>Streaming large messages</title> - <para>ActiveMQ supports setting the body of messages using input and output streams (<literal - >java.lang.io</literal>)</para> - <para>These streams are then used directly for sending (input streams) and receiving (output - streams) messages.</para> - <para>When receiving messages there are 2 ways to deal with the output stream; you may - choose to block while the output stream is recovered using the method <literal - >ClientMessage.saveOutputStream</literal> or alternatively using the method <literal - >ClientMessage.setOutputstream</literal> which will asynchronously write the message - to the stream. If you choose the latter the consumer must be kept alive until the - message has been fully received.</para> - <para>You can use any kind of stream you like. The most common use case is to send files - stored in your disk, but you could also send things like JDBC Blobs, <literal - >SocketInputStream</literal>, things you recovered from <literal - >HTTPRequests</literal> etc. Anything as long as it implements <literal - >java.io.InputStream</literal> for sending messages or <literal - >java.io.OutputStream</literal> for receiving them.</para> - <section> - <title>Streaming over Core API</title> - <para>The following table shows a list of methods available at <literal - >ClientMessage</literal> which are also available through JMS by the use of - object properties.</para> - <table frame="topbot" id="large-messages.ClientMessageAPI"> - <title>org.apache.activemq.api.core.client.ClientMessage API</title> - <tgroup cols="3"> - <colspec colname="Name" colnum="1"/> - <colspec colname="Descr" colnum="2"/> - <colspec colname="JMS" colnum="3"/> - <thead> - <row> - <entry>Name</entry> - <entry>Description</entry> - <entry>JMS Equivalent Property</entry> - </row> - </thead> - <tbody> - <row> - <entry>setBodyInputStream(InputStream)</entry> - <entry>Set the InputStream used to read a message body when sending - it.</entry> - <entry>JMS_HQ_InputStream</entry> - </row> - <row> - <entry>setOutputStream(OutputStream)</entry> - <entry>Set the OutputStream that will receive the body of a message. - This method does not block.</entry> - <entry>JMS_HQ_OutputStream</entry> - </row> - <row> - <entry>saveOutputStream(OutputStream)</entry> - <entry>Save the body of the message to the <literal - >OutputStream</literal>. It will block until the entire content - is transferred to the <literal>OutputStream</literal>.</entry> - <entry>JMS_HQ_SaveStream</entry> - </row> - </tbody> - </tgroup> - </table> - <para>To set the output stream when receiving a core message: </para> - <programlisting> -... -ClientMessage msg = consumer.receive(...); - - -// This will block here until the stream was transferred -msg.saveOutputStream(someOutputStream); - -ClientMessage msg2 = consumer.receive(...); - -// This will not wait the transfer to finish -msg.setOutputStream(someOtherOutputStream); -...</programlisting> - <para> Set the input stream when sending a core message: </para> - <programlisting> -... -ClientMessage msg = session.createMessage(); -msg.setInputStream(dataInputStream); -...</programlisting> - <para>Notice also that for messages with more than 2GiB the getBodySize() will return - invalid values since this is an integer (which is also exposed to the JMS API). On - those cases you can use the message property _HQ_LARGE_SIZE.</para> - </section> - <section id="large-messages.streaming.over.jms"> - <title>Streaming over JMS</title> - <para>When using JMS, ActiveMQ maps the streaming methods on the core API (see <xref - linkend="large-messages.ClientMessageAPI"/>) by setting object properties . You - can use the method <literal>Message.setObjectProperty</literal> to set the input and - output streams.</para> - <para>The <literal>InputStream</literal> can be defined through the JMS Object Property - JMS_HQ_InputStream on messages being sent:</para> - <programlisting> -BytesMessage message = session.createBytesMessage(); - -FileInputStream fileInputStream = new FileInputStream(fileInput); - -BufferedInputStream bufferedInput = new BufferedInputStream(fileInputStream); - -message.setObjectProperty("JMS_HQ_InputStream", bufferedInput); - -someProducer.send(message);</programlisting> - <para>The <literal>OutputStream</literal> can be set through the JMS Object Property - JMS_HQ_SaveStream on messages being received in a blocking way.</para> - <programlisting> -BytesMessage messageReceived = (BytesMessage)messageConsumer.receive(120000); - -File outputFile = new File("huge_message_received.dat"); - -FileOutputStream fileOutputStream = new FileOutputStream(outputFile); - -BufferedOutputStream bufferedOutput = new BufferedOutputStream(fileOutputStream); - -// This will block until the entire content is saved on disk -messageReceived.setObjectProperty("JMS_HQ_SaveStream", bufferedOutput);</programlisting> - <para>Setting the <literal>OutputStream</literal> could also be done in a non blocking - way using the property JMS_HQ_OutputStream.</para> - <programlisting> -// This won't wait the stream to finish. You need to keep the consumer active. -messageReceived.setObjectProperty("JMS_HQ_OutputStream", bufferedOutput);</programlisting> - <note> - <para>When using JMS, Streaming large messages are only supported on <literal - >StreamMessage</literal> and <literal>BytesMessage</literal>.</para> - </note> - </section> - </section> - <section> - <title>Streaming Alternative</title> - <para>If you choose not to use the <literal>InputStream</literal> or <literal - >OutputStream</literal> capability of ActiveMQ You could still access the data - directly in an alternative fashion.</para> - <para>On the Core API just get the bytes of the body as you normally would.</para> - <programlisting> -ClientMessage msg = consumer.receive(); - -byte[] bytes = new byte[1024]; -for (int i = 0 ; i < msg.getBodySize(); i += bytes.length) -{ - msg.getBody().readBytes(bytes); - // Whatever you want to do with the bytes -}</programlisting> - <para>If using JMS API, <literal>BytesMessage</literal> and <literal>StreamMessage</literal> - also supports it transparently.</para> - <programlisting> -BytesMessage rm = (BytesMessage)cons.receive(10000); - -byte data[] = new byte[1024]; - -for (int i = 0; i < rm.getBodyLength(); i += 1024) -{ - int numberOfBytes = rm.readBytes(data); - // Do whatever you want with the data -} </programlisting> - </section> - <section id="large-messages.example"> - <title>Large message example</title> - <para>Please see <xref linkend="examples.large-message"/> for an example which shows how - large message is configured and used with JMS.</para> - </section> -</chapter>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/last-value-queues.md ---------------------------------------------------------------------- diff --git a/docs/user-manual/en/last-value-queues.md b/docs/user-manual/en/last-value-queues.md new file mode 100644 index 0000000..eca5eb5 --- /dev/null +++ b/docs/user-manual/en/last-value-queues.md @@ -0,0 +1,55 @@ +Last-Value Queues +================= + +Last-Value queues are special queues which discard any messages when a +newer message with the same value for a well-defined Last-Value property +is put in the queue. In other words, a Last-Value queue only retains the +last value. + +A typical example for Last-Value queue is for stock prices, where you +are only interested by the latest value for a particular stock. + +Configuring Last-Value Queues +============================= + +Last-value queues are defined in the address-setting configuration: + + <address-setting match="jms.queue.lastValueQueue"> + <last-value-queue>true</last-value-queue> + </address-setting> + +By default, `last-value-queue` is false. Address wildcards can be used +to configure Last-Value queues for a set of addresses (see ?). + +Using Last-Value Property +========================= + +The property name used to identify the last value is `"_HQ_LVQ_NAME"` +(or the constant `Message.HDR_LAST_VALUE_NAME` from the Core API). + +For example, if two messages with the same value for the Last-Value +property are sent to a Last-Value queue, only the latest message will be +kept in the queue: + + // send 1st message with Last-Value property set to STOCK_NAME + TextMessage message = session.createTextMessage("1st message with Last-Value property set"); + message.setStringProperty("_HQ_LVQ_NAME", "STOCK_NAME"); + producer.send(message); + + // send 2nd message with Last-Value property set to STOCK_NAME + message = session.createTextMessage("2nd message with Last-Value property set"); + message.setStringProperty("_HQ_LVQ_NAME", "STOCK_NAME"); + producer.send(message); + + ... + + // only the 2nd message will be received: it is the latest with + // the Last-Value property set + TextMessage messageReceived = (TextMessage)messageConsumer.receive(5000); + System.out.format("Received message: %s\n", messageReceived.getText()); + +Example +======= + +See ? for an example which shows how last value queues are configured +and used with JMS. http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/last-value-queues.xml ---------------------------------------------------------------------- diff --git a/docs/user-manual/en/last-value-queues.xml b/docs/user-manual/en/last-value-queues.xml deleted file mode 100644 index f6f44b6..0000000 --- a/docs/user-manual/en/last-value-queues.xml +++ /dev/null @@ -1,70 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!-- ============================================================================= --> -<!-- Licensed to the Apache Software Foundation (ASF) under one or more --> -<!-- contributor license agreements. See the NOTICE file distributed with --> -<!-- this work for additional information regarding copyright ownership. --> -<!-- The ASF licenses this file to You under the Apache License, Version 2.0 --> -<!-- (the "License"); you may not use this file except in compliance with --> -<!-- the License. You may obtain a copy of the License at --> -<!-- --> -<!-- http://www.apache.org/licenses/LICENSE-2.0 --> -<!-- --> -<!-- Unless required by applicable law or agreed to in writing, software --> -<!-- distributed under the License is distributed on an "AS IS" BASIS, --> -<!-- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. --> -<!-- See the License for the specific language governing permissions and --> -<!-- limitations under the License. --> -<!-- ============================================================================= --> - -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"; [ -<!ENTITY % BOOK_ENTITIES SYSTEM "ActiveMQ_User_Manual.ent"> -%BOOK_ENTITIES; -]> -<chapter id="last-value-queues"> - <title>Last-Value Queues</title> - <para>Last-Value queues are special queues which discard any messages when a newer message with - the same value for a well-defined Last-Value property is put in the queue. In other words, a - Last-Value queue only retains the last value.</para> - <para>A typical example for Last-Value queue is for stock prices, where you are only interested - by the latest value for a particular stock.</para> - <section> - <title>Configuring Last-Value Queues</title> - <para>Last-value queues are defined in the address-setting configuration:</para> - <programlisting> -<address-setting match="jms.queue.lastValueQueue"> - <last-value-queue>true</last-value-queue> -</address-setting></programlisting> - <para>By default, <literal>last-value-queue</literal> is false. Address wildcards can be used - to configure Last-Value queues for a set of addresses (see <xref linkend="wildcard-syntax" - />).</para> - </section> - <section> - <title>Using Last-Value Property</title> - <para>The property name used to identify the last value is <literal>"_HQ_LVQ_NAME"</literal> - (or the constant <literal>Message.HDR_LAST_VALUE_NAME</literal> from the Core API).</para> - <para>For example, if two messages with the same value for the Last-Value property are sent to - a Last-Value queue, only the latest message will be kept in the queue:</para> - <programlisting> -// send 1st message with Last-Value property set to STOCK_NAME -TextMessage message = session.createTextMessage("1st message with Last-Value property set"); -message.setStringProperty("_HQ_LVQ_NAME", "STOCK_NAME"); -producer.send(message); - -// send 2nd message with Last-Value property set to STOCK_NAME -message = session.createTextMessage("2nd message with Last-Value property set"); -message.setStringProperty("_HQ_LVQ_NAME", "STOCK_NAME"); -producer.send(message); - -... - -// only the 2nd message will be received: it is the latest with -// the Last-Value property set -TextMessage messageReceived = (TextMessage)messageConsumer.receive(5000); -System.out.format("Received message: %s\n", messageReceived.getText());</programlisting> - </section> - <section> - <title>Example</title> - <para>See <xref linkend="examples.last-value-queue"/> for an example which shows how last - value queues are configured and used with JMS.</para> - </section> -</chapter> http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/libaio.md ---------------------------------------------------------------------- diff --git a/docs/user-manual/en/libaio.md b/docs/user-manual/en/libaio.md new file mode 100644 index 0000000..1e5f9ae --- /dev/null +++ b/docs/user-manual/en/libaio.md @@ -0,0 +1,109 @@ +Libaio Native Libraries +======================= + +ActiveMQ distributes a native library, used as a bridge between ActiveMQ +and Linux libaio. + +`libaio` is a library, developed as part of the Linux kernel project. +With `libaio` we submit writes to the operating system where they are +processed asynchronously. Some time later the OS will call our code back +when they have been processed. + +We use this in our high performance journal if configured to do so, +please see ?. + +These are the native libraries distributed by ActiveMQ: + +- libActiveMQAIO32.so - x86 32 bits + +- libActiveMQAIO64.so - x86 64 bits + +When using libaio, ActiveMQ will always try loading these files as long +as they are on the [library path](#using-server.library.path). + +Compiling the native libraries +============================== + +In the case that you are using Linux on a platform other than x86\_32 or +x86\_64 (for example Itanium 64 bits or IBM Power) you may need to +compile the native library, since we do not distribute binaries for +those platforms with the release. + +Install requirements +-------------------- + +> **Note** +> +> At the moment the native layer is only available on Linux. If you are +> in a platform other than Linux the native compilation will not work + +The native library uses +[autoconf](http://en.wikipedia.org/wiki/Autoconf) what makes the +compilation process easy, however you need to install extra packages as +a requirement for compilation: + +- gcc - C Compiler + +- gcc-c++ or g++ - Extension to gcc with support for C++ + +- autoconf - Tool for automating native build process + +- make - Plain old make + +- automake - Tool for automating make generation + +- libtool - Tool for link editing native libraries + +- libaio - library to disk asynchronous IO kernel functions + +- libaio-dev - Compilation support for libaio + +- A full JDK installed with the environment variable JAVA\_HOME set to + its location + +To perform this installation on RHEL or Fedora, you can simply type this +at a command line: + + sudo yum install automake libtool autoconf gcc-c++ gcc libaio libaio-devel make + +Or on Debian systems: + + sudo apt-get install automake libtool autoconf gcc-g++ gcc libaio libaio-dev make + +> **Note** +> +> You could find a slight variation of the package names depending on +> the version and Linux distribution. (for example gcc-c++ on Fedora +> versus g++ on Debian systems) + +Invoking the compilation +------------------------ + +In the distribution, in the `native-src` directory, execute the shell +script `bootstrap`. This script will invoke `automake` and `make` what +will create all the make files and the native library. + + someUser@someBox:/messaging-distribution/native-src$ ./bootstrap + checking for a BSD-compatible install... /usr/bin/install -c + checking whether build environment is sane... yes + checking for a thread-safe mkdir -p... /bin/mkdir -p + + ... + + configure: creating ./config.status + config.status: creating Makefile + config.status: creating ./src/Makefile + config.status: creating config.h + config.status: config.h is unchanged + config.status: executing depfiles commands + config.status: executing libtool commands + + ... + +The produced library will be at +`./native-src/src/.libs/libActiveMQAIO.so`. Simply move that file over +`bin` on the distribution or the place you have chosen on the [library +path](#using-server.library.path). + +If you want to perform changes on the ActiveMQ libaio code, you could +just call make directly at the `native-src` directory. http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/libaio.xml ---------------------------------------------------------------------- diff --git a/docs/user-manual/en/libaio.xml b/docs/user-manual/en/libaio.xml deleted file mode 100644 index 75007ed..0000000 --- a/docs/user-manual/en/libaio.xml +++ /dev/null @@ -1,129 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!-- ============================================================================= --> -<!-- Licensed to the Apache Software Foundation (ASF) under one or more --> -<!-- contributor license agreements. See the NOTICE file distributed with --> -<!-- this work for additional information regarding copyright ownership. --> -<!-- The ASF licenses this file to You under the Apache License, Version 2.0 --> -<!-- (the "License"); you may not use this file except in compliance with --> -<!-- the License. You may obtain a copy of the License at --> -<!-- --> -<!-- http://www.apache.org/licenses/LICENSE-2.0 --> -<!-- --> -<!-- Unless required by applicable law or agreed to in writing, software --> -<!-- distributed under the License is distributed on an "AS IS" BASIS, --> -<!-- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. --> -<!-- See the License for the specific language governing permissions and --> -<!-- limitations under the License. --> -<!-- ============================================================================= --> - -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"; [ -<!ENTITY % BOOK_ENTITIES SYSTEM "ActiveMQ_User_Manual.ent"> -%BOOK_ENTITIES; -]> -<chapter id="libaio"> - <title>Libaio Native Libraries</title> - <para>ActiveMQ distributes a native library, used as a bridge between ActiveMQ and Linux - libaio.</para> - <para><literal>libaio</literal> is a library, developed as part of the Linux kernel project. - With <literal>libaio</literal> we submit writes to the operating system where they are - processed asynchronously. Some time later the OS will call our code back when they have been - processed.</para> - <para>We use this in our high performance journal if configured to do so, please see <xref - linkend="persistence"/>.</para> - <para>These are the native libraries distributed by ActiveMQ:</para> - <itemizedlist> - <listitem> - <para>libActiveMQAIO32.so - x86 32 bits</para> - </listitem> - <listitem> - <para>libActiveMQAIO64.so - x86 64 bits</para> - </listitem> - </itemizedlist> - <para>When using libaio, ActiveMQ will always try loading these files as long as they are on the - <link linkend="using-server.library.path">library path</link>.</para> - <section> - <title>Compiling the native libraries</title> - <para>In the case that you are using Linux on a platform other than x86_32 or x86_64 - (for example Itanium 64 bits or IBM Power) you may need to compile the native library, since we - do not distribute binaries for those platforms with the release.</para> - <section> - <title>Install requirements</title> - <note> - <para>At the moment the native layer is only available on Linux. If you are in a - platform other than Linux the native compilation will not work</para> - </note> - <para>The native library uses <ulink url="http://en.wikipedia.org/wiki/Autoconf"; - >autoconf</ulink> what makes the compilation process easy, however you need to - install extra packages as a requirement for compilation:</para> - <itemizedlist> - <listitem> - <para>gcc - C Compiler</para> - </listitem> - <listitem> - <para>gcc-c++ or g++ - Extension to gcc with support for C++</para> - </listitem> - <listitem> - <para>autoconf - Tool for automating native build process</para> - </listitem> - <listitem> - <para>make - Plain old make</para> - </listitem> - <listitem> - <para>automake - Tool for automating make generation</para> - </listitem> - <listitem> - <para>libtool - Tool for link editing native libraries</para> - </listitem> - <listitem> - <para>libaio - library to disk asynchronous IO kernel functions</para> - </listitem> - <listitem> - <para>libaio-dev - Compilation support for libaio</para> - </listitem> - <listitem> - <para>A full JDK installed with the environment variable JAVA_HOME set to its - location</para> - </listitem> - </itemizedlist> - <para>To perform this installation on RHEL or Fedora, you can simply type this at a - command line:</para> - <programlisting>sudo yum install automake libtool autoconf gcc-c++ gcc libaio libaio-devel make</programlisting> - <para>Or on Debian systems:</para> - <programlisting>sudo apt-get install automake libtool autoconf gcc-g++ gcc libaio libaio-dev make</programlisting> - <note> - <para>You could find a slight variation of the package names depending on the - version and Linux distribution. (for example gcc-c++ on Fedora versus g++ on - Debian systems)</para> - </note> - </section> - <section> - <title>Invoking the compilation</title> - <para>In the distribution, in the <literal>native-src</literal> directory, execute the - shell script <literal>bootstrap</literal>. This script will invoke <literal - >automake</literal> and <literal>make</literal> what will create all the make - files and the native library.</para> - <programlisting>someUser@someBox:/messaging-distribution/native-src$ ./bootstrap -checking for a BSD-compatible install... /usr/bin/install -c -checking whether build environment is sane... yes -checking for a thread-safe mkdir -p... /bin/mkdir -p - -... - -configure: creating ./config.status -config.status: creating Makefile -config.status: creating ./src/Makefile -config.status: creating config.h -config.status: config.h is unchanged -config.status: executing depfiles commands -config.status: executing libtool commands - -...</programlisting> - <para>The produced library will be at <literal - >./native-src/src/.libs/libActiveMQAIO.so</literal>. Simply move that file over - <literal>bin</literal> on the distribution or the place you have chosen on the - <link linkend="using-server.library.path">library path</link>.</para> - <para>If you want to perform changes on the ActiveMQ libaio code, you could just call - make directly at the <literal>native-src</literal> directory.</para> - </section> - </section> -</chapter> http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/logging.md ---------------------------------------------------------------------- diff --git a/docs/user-manual/en/logging.md b/docs/user-manual/en/logging.md new file mode 100644 index 0000000..32ef718 --- /dev/null +++ b/docs/user-manual/en/logging.md @@ -0,0 +1,93 @@ +Logging +======= + +ActiveMQ uses the JBoss Logging framework to do its logging and is +configurable via the `logging.properties` file found in the +configuration directories. This is configured by Default to log to both +the console and to a file. + +There are 6 loggers available which are as follows: + + Logger Logger Description + ------------------------------------------- ---------------------------------------------------- + org.jboss.logging Logs any calls not handled by the ActiveMQ loggers + org.apache.activemq.core.server Logs the core server + org.apache.activemq.utils Logs utility calls + org.apache.activemq.journal Logs Journal calls + org.apache.activemq.jms Logs JMS calls + org.apache.activemq.integration.bootstrap Logs bootstrap calls + + : Global Configuration Properties + +Logging in a client or with an Embedded server +============================================== + +Firstly, if you want to enable logging on the client side you need to +include the JBoss logging jars in your library. If you are using maven +add the following dependencies. + + <dependency> + <groupId>org.jboss.logmanager</groupId> + <artifactId>jboss-logmanager</artifactId> + <version>1.3.1.Final</version> + </dependency> + <dependency> + <groupId>org.apache.activemq</groupId> + <artifactId>activemq-core-client</artifactId> + <version>2.3.0.Final</version> + </dependency> + +There are 2 properties you need to set when starting your java program, +the first is to set the Log Manager to use the JBoss Log Manager, this +is done by setting the `-Djava.util.logging.manager` property i.e. +`-Djava.util.logging.manager=org.jboss.logmanager.LogManager` + +The second is to set the location of the logging.properties file to use, +this is done via the `-Dlogging.configuration` for instance +`-Dlogging.configuration=file:///home/user/projects/myProject/logging.properties`. + +> **Note** +> +> The value for this needs to be valid URL + +The following is a typical `logging.properties for a client` + + # Root logger option + loggers=org.jboss.logging,org.apache.activemq.core.server,org.apache.activemq.utils,org.apache.activemq.journal,org.apache.activemq.jms,org.apache.activemq.ra + + # Root logger level + logger.level=INFO + # ActiveMQ logger levels + logger.org.apache.activemq.core.server.level=INFO + logger.org.apache.activemq.utils.level=INFO + logger.org.apache.activemq.jms.level=DEBUG + + # Root logger handlers + logger.handlers=FILE,CONSOLE + + # Console handler configuration + handler.CONSOLE=org.jboss.logmanager.handlers.ConsoleHandler + handler.CONSOLE.properties=autoFlush + handler.CONSOLE.level=FINE + handler.CONSOLE.autoFlush=true + handler.CONSOLE.formatter=PATTERN + + # File handler configuration + handler.FILE=org.jboss.logmanager.handlers.FileHandler + handler.FILE.level=FINE + handler.FILE.properties=autoFlush,fileName + handler.FILE.autoFlush=true + handler.FILE.fileName=activemq.log + handler.FILE.formatter=PATTERN + + # Formatter pattern configuration + formatter.PATTERN=org.jboss.logmanager.formatters.PatternFormatter + formatter.PATTERN.properties=pattern + formatter.PATTERN.pattern=%d{HH:mm:ss,SSS} %-5p [%c] %s%E%n + +Logging With The JBoss Application Server +========================================= + +When ActiveMQ is deployed within the JBoss Application Server version +7.x or above then it will still use JBoss Logging, refer to the AS7 +documentation on how to configure AS7 logging. http://git-wip-us.apache.org/repos/asf/activemq-6/blob/4245a6b4/docs/user-manual/en/logging.xml ---------------------------------------------------------------------- diff --git a/docs/user-manual/en/logging.xml b/docs/user-manual/en/logging.xml deleted file mode 100644 index 8277b55..0000000 --- a/docs/user-manual/en/logging.xml +++ /dev/null @@ -1,138 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!-- ============================================================================= --> -<!-- Licensed to the Apache Software Foundation (ASF) under one or more --> -<!-- contributor license agreements. See the NOTICE file distributed with --> -<!-- this work for additional information regarding copyright ownership. --> -<!-- The ASF licenses this file to You under the Apache License, Version 2.0 --> -<!-- (the "License"); you may not use this file except in compliance with --> -<!-- the License. You may obtain a copy of the License at --> -<!-- --> -<!-- http://www.apache.org/licenses/LICENSE-2.0 --> -<!-- --> -<!-- Unless required by applicable law or agreed to in writing, software --> -<!-- distributed under the License is distributed on an "AS IS" BASIS, --> -<!-- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. --> -<!-- See the License for the specific language governing permissions and --> -<!-- limitations under the License. --> -<!-- ============================================================================= --> - -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"; [ -<!ENTITY % BOOK_ENTITIES SYSTEM "ActiveMQ_User_Manual.ent"> -%BOOK_ENTITIES; -]> -<chapter id="logging"> - <title>Logging</title> - <para>ActiveMQ uses the JBoss Logging framework to do its logging and is configurable via the <literal>logging.properties</literal> - file found in the configuration directories. This is configured by Default to log to both the console and to a file.</para> - <para>There are 6 loggers available which are as follows:</para> - <table frame="topbot" border="2"> - <title>Global Configuration Properties</title> - <tgroup cols="2"> - <colspec colname="c1" colnum="1"/> - <colspec colname="c2" colnum="2"/> - <thead> - <row> - <entry>Logger</entry> - <entry>Logger Description</entry> - </row> - </thead> - <tbody> - <row> - <entry>org.jboss.logging</entry> - <entry>Logs any calls not handled by the ActiveMQ loggers</entry> - </row> - <row> - <entry>org.apache.activemq.core.server</entry> - <entry>Logs the core server</entry> - </row> - <row> - <entry>org.apache.activemq.utils</entry> - <entry>Logs utility calls</entry> - </row> - <row> - <entry>org.apache.activemq.journal</entry> - <entry>Logs Journal calls</entry> - </row> - <row> - <entry>org.apache.activemq.jms</entry> - <entry>Logs JMS calls</entry> - </row> - <row> - <entry>org.apache.activemq.integration.bootstrap</entry> - <entry>Logs bootstrap calls</entry> - </row> - </tbody> - </tgroup> - <para>you can configure the levels on these loggers independently in the appropriate <literal>logging.properties</literal> - file</para> - </table> - <section> - <title>Logging in a client or with an Embedded server</title> - <para> - Firstly, if you want to enable logging on the client side you need to include the JBoss logging jars in your library. - If you are using maven add the following dependencies. - <programlisting> -<dependency> - <groupId>org.jboss.logmanager</groupId> - <artifactId>jboss-logmanager</artifactId> - <version>1.3.1.Final</version> -</dependency> -<dependency> - <groupId>org.apache.activemq</groupId> - <artifactId>activemq-core-client</artifactId> - <version>2.3.0.Final</version> -</dependency></programlisting> - </para> - <para> - There are 2 properties you need to set when starting your java program, the first is to set the Log Manager to use - the JBoss Log Manager, this is done by setting the <literal>-Djava.util.logging.manager</literal> property i.e. - <literal>-Djava.util.logging.manager=org.jboss.logmanager.LogManager</literal> - </para> - <para> - The second is to set the location of the logging.properties file to use, this is done via the <literal>-Dlogging.configuration</literal> - for instance <literal>-Dlogging.configuration=file:///home/user/projects/myProject/logging.properties</literal>. - <note>The value for this needs to be valid URL</note> - </para> - <para> - The following is a typical <literal>logging.properties for a client</literal> - <programlisting> -# Root logger option -loggers=org.jboss.logging,org.apache.activemq.core.server,org.apache.activemq.utils,org.apache.activemq.journal,org.apache.activemq.jms,org.apache.activemq.ra - -# Root logger level -logger.level=INFO -# ActiveMQ logger levels -logger.org.apache.activemq.core.server.level=INFO -logger.org.apache.activemq.utils.level=INFO -logger.org.apache.activemq.jms.level=DEBUG - -# Root logger handlers -logger.handlers=FILE,CONSOLE - -# Console handler configuration -handler.CONSOLE=org.jboss.logmanager.handlers.ConsoleHandler -handler.CONSOLE.properties=autoFlush -handler.CONSOLE.level=FINE -handler.CONSOLE.autoFlush=true -handler.CONSOLE.formatter=PATTERN - -# File handler configuration -handler.FILE=org.jboss.logmanager.handlers.FileHandler -handler.FILE.level=FINE -handler.FILE.properties=autoFlush,fileName -handler.FILE.autoFlush=true -handler.FILE.fileName=activemq.log -handler.FILE.formatter=PATTERN - -# Formatter pattern configuration -formatter.PATTERN=org.jboss.logmanager.formatters.PatternFormatter -formatter.PATTERN.properties=pattern -formatter.PATTERN.pattern=%d{HH:mm:ss,SSS} %-5p [%c] %s%E%n</programlisting> - </para> - </section> - <section> - <title>Logging With The JBoss Application Server</title> - <para>When ActiveMQ is deployed within the JBoss Application Server version 7.x or above then - it will still use JBoss Logging, refer to the AS7 documentation on how to configure AS7 logging.</para> - </section> -</chapter>
