examples/features/standard/jmx/readme.html - activemq-artemis - Git at Google

 <!--
 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.
 -->

 <html>
   <head>
     <title>ActiveMQ Artemis JMX Management Example</title>
     <link rel="stylesheet" type="text/css" href="../../../common/common.css" />
     <link rel="stylesheet" type="text/css" href="../../../common/prettify.css" />
     <script type="text/javascript" src="../../../common/prettify.js"></script>
   </head>
   <body onload="prettyPrint()">
      <h1>JMX Management Example</h1>

      <pre>To run the example, simply type <b>mvn verify</b> from this directory, <br>or <b>mvn -PnoServer verify</b> if you want to start and create the server manually.</pre>

      <p>This example shows how to manage ActiveMQ Artemis using <a href="http://java.sun.com/javase/technologies/core/mntr-mgmt/javamanagement/">JMX</a></p>

      <h2>Example configuration</h2>

      <p>ActiveMQ Artemis exposes its managed resources by default on the platform MBeanServer.</p>
      <p>To access this MBeanServer remotely, the Java Virtual machine must be started with system properties:
          <pre class="prettyprint">
              <code>-Dcom.sun.management.jmxremote
              -Dcom.sun.management.jmxremote.port=3000
              -Dcom.sun.management.jmxremote.ssl=false
              -Dcom.sun.management.jmxremote.authenticate=false</code>
         </pre>
         <p>These properties are explained in the Java <a href="http://docs.oracle.com/javase/8/docs/technotes/guides/management/agent.html#gdenl">management guide</a>
             (please note that for this example, we will disable user authentication for simplicity sake).</p>
         <p>With these properties, ActiveMQ Artemis server will be manageable remotely using standard JMX URL on port <code>3000</code>.</p>
      </p>

      <h2>Example step-by-step</h2>
      <ol>
         <li>First we need to get an initial context so we can look-up the JMS connection factory and destination objects from JNDI. This initial context will get its properties from <a href="server0/client-jndi.properties">client-jndi.properties</a></li>
         <pre class="prettyprint">
             <code>InitialContext initialContext = getContext(0);</code>
         </pre>

         <li>We look up the JMS queue object from JNDI</li>
         <pre class="prettyprint">
             <code>Queue queue = (Queue) initialContext.lookup("/queue/exampleQueue");</code>
         </pre>

         <li>We look up the JMS connection factory object from JNDI</li>
         <pre class="prettyprint">
             <code>ConnectionFactory cf = (ConnectionFactory) initialContext.lookup("/ConnectionFactory");</code>
         </pre>

         <li>We create a JMS connection</li>
         <pre class="prettyprint">
             <code>connection = cf.createConnection();</code>
         </pre>

         <li>We create a JMS session. The session is created as non transacted and will auto acknowledge messages.</li>
         <pre class="prettyprint">
             <code>Session session = connection.createSession(false, Session.AUTO_ACKNOWLEDGE);</code>
         </pre>

         <li>We create a JMS message producer on the session. This will be used to send the messages.</li>
         <pre class="prettyprint">
             <code>MessageProducer messageProducer = session.createProducer(topic);</code>
        </pre>

         <li>We create a JMS text message that we are going to send.</li>
         <pre class="prettyprint">
             <code>TextMessage message = session.createTextMessage("This is a text message");</code>
         </pre>

         <li>We send message to the queue</li>
         <pre class="prettyprint">
             <code>messageProducer.send(message);</code>
         </pre>

         <p><em>Now that we have a message in the queue, we will manage the queue by retrieving the number of messages in the queue
             (i.e. 1) and by removing the message which has been sent in step 8.</em></p>

         <li>We retrieve the <code>ObjectName</code> corresponding to the queue using a helper class <code>ObjectNameBuilder</code></li>
         <pre class="prettyprint">
               <code>ObjectName on = ObjectNameBuilder.DEFAULT.getJMSQueueObjectName(queue.getQueueName());</code>
         </pre>

         <li>We create a JMX Connector to connect to the server's MBeanServer using the <a href="http://docs.oracle.com/javase/8/docs/technotes/guides/management/agent.html#gdevg">standard JMX service URL</a></li>
         <pre class="prettyprint">
             <code>JMXConnector connector = JMXConnectorFactory.connect(new JMXServiceURL(JMX_URL), new HashMap());</code>
         </pre>

         <li>We retrieve a <code>MBeanServerConnection</code> from the JMX connector</li>
         <pre class="prettyprint">
            <code>TextMessage messageReceived = (TextMessage) messageConsumer.receive(5000);</code>
         </pre>

         <li>We create a <code>JMSQueueControl</code> proxy to manage the queue on the server</li>
         <pre class="prettyprint">
             <code>JMSQueueControl queueControl = (JMSQueueControl)MBeanServerInvocationHandler.newProxyInstance(mbsc,
                                                                                               on,
                                                                                               JMSQueueControl.class,
                                                                                               false);
              </code>
         </pre>

         <li>We use this mbean proxy to retrieve the number of messages in the queue using the <code>getMessageCount</code> method</li>
         <pre class="prettyprint">
             <code>System.out.println(queueControl.getName() + " contains " + queueControl.getMessageCount() + " messages");</code>
         </pre>

         <li>We will now remove the message sent at step 8 using the <code>removeMessage</code> method with the JMS Message ID of the message</li>
         <pre class="prettyprint">
             <code>System.out.println("message has been removed: " + queueControl.removeMessage(message.getJMSMessageID()));</code>
         </pre>

         <li>We use again the mbean proxy to retrieve the number of messages. This time, it will display <code>0</code> messages</li>
         <pre class="prettyprint">
             <code>System.out.println(queueControl.getName() + " contains " + queueControl.getMessageCount() + " messages");</code>
         </pre>

         <li>Now we have finish the management operations, we close the JMX connector</li>
         <pre class="prettyprint">
             <code>connector.close()</code>
         </pre>

         <p><em>We will now try to consume the message sent to the queue but it won't be there: it has been removed by the management operation</em></p>

         <li>We create a JMS message consumer on the queue</li>
         <pre class="prettyprint">
             <code>MessageConsumer messageConsumer = session.createConsumer(queue);</code>
         </pre>

         <li>We start the connection. In order for delivery to occur on any consumers or subscribers on a connection, the connection must be started</li>
         <pre class="prettyprint">
             <code>connection.start();</code>
         </pre>

         <li>We try to receive a message from the queue. Since there is none, the call will timeout after 5000ms and messageReceived will be null
         </li>
         <pre class="prettyprint">
             <code>TextMessage messageReceived = (TextMessage) messageConsumer.receive(5000);
             System.out.println("Received message: " + messageReceived);</code>
         </pre>

         <li>And finally, <b>always</b> remember to close your JMS connections and resources after use, in a <code>finally</code> block. Closing a JMS connection will automatically close all of its sessions, consumers, producer and browser objects</li>

         <pre class="prettyprint">
            <code>finally
            {
               if (initialContext != null)
               {
                 initialContext.close();
               }
               if (connection != null)
               {
                  connection.close();
               }
            }</code>
         </pre>
      </ol>

      <h2>More information</h2>

      <ul>
         <li>User Manual's <a href="../../../docs/user-manual/en/html_single/index.html#management.jmx">Using Management Via JMX chapter</a></li>
         <li><a href="http://docs.oracle.com/javase/8/docs/technotes/guides/management/agent.html">Java management guide</a></li>
      </ul>
   </body>
 </html>
	<!--
	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.
	-->

	<html>
	<head>
	<title>ActiveMQ Artemis JMX Management Example</title>
	<link rel="stylesheet" type="text/css" href="../../../common/common.css" />
	<link rel="stylesheet" type="text/css" href="../../../common/prettify.css" />
	<script type="text/javascript" src="../../../common/prettify.js"></script>
	</head>
	<body onload="prettyPrint()">
	<h1>JMX Management Example</h1>

	<pre>To run the example, simply type <b>mvn verify</b> from this directory, <br>or <b>mvn -PnoServer verify</b> if you want to start and create the server manually.</pre>

	<p>This example shows how to manage ActiveMQ Artemis using <a href="http://java.sun.com/javase/technologies/core/mntr-mgmt/javamanagement/">JMX</a></p>

	<h2>Example configuration</h2>

	<p>ActiveMQ Artemis exposes its managed resources by default on the platform MBeanServer.</p>
	<p>To access this MBeanServer remotely, the Java Virtual machine must be started with system properties:
	<pre class="prettyprint">
	<code>-Dcom.sun.management.jmxremote
	-Dcom.sun.management.jmxremote.port=3000
	-Dcom.sun.management.jmxremote.ssl=false
	-Dcom.sun.management.jmxremote.authenticate=false</code>
	</pre>
	<p>These properties are explained in the Java <a href="http://docs.oracle.com/javase/8/docs/technotes/guides/management/agent.html#gdenl">management guide</a>
	(please note that for this example, we will disable user authentication for simplicity sake).</p>
	<p>With these properties, ActiveMQ Artemis server will be manageable remotely using standard JMX URL on port <code>3000</code>.</p>
	</p>

	<h2>Example step-by-step</h2>
	<ol>
	<li>First we need to get an initial context so we can look-up the JMS connection factory and destination objects from JNDI. This initial context will get its properties from <a href="server0/client-jndi.properties">client-jndi.properties</a></li>
	<pre class="prettyprint">
	<code>InitialContext initialContext = getContext(0);</code>
	</pre>

	<li>We look up the JMS queue object from JNDI</li>
	<pre class="prettyprint">
	<code>Queue queue = (Queue) initialContext.lookup("/queue/exampleQueue");</code>
	</pre>

	<li>We look up the JMS connection factory object from JNDI</li>
	<pre class="prettyprint">
	<code>ConnectionFactory cf = (ConnectionFactory) initialContext.lookup("/ConnectionFactory");</code>
	</pre>

	<li>We create a JMS connection</li>
	<pre class="prettyprint">
	<code>connection = cf.createConnection();</code>
	</pre>

	<li>We create a JMS session. The session is created as non transacted and will auto acknowledge messages.</li>
	<pre class="prettyprint">
	<code>Session session = connection.createSession(false, Session.AUTO_ACKNOWLEDGE);</code>
	</pre>

	<li>We create a JMS message producer on the session. This will be used to send the messages.</li>
	<pre class="prettyprint">
	<code>MessageProducer messageProducer = session.createProducer(topic);</code>
	</pre>

	<li>We create a JMS text message that we are going to send.</li>
	<pre class="prettyprint">
	<code>TextMessage message = session.createTextMessage("This is a text message");</code>
	</pre>

	<li>We send message to the queue</li>
	<pre class="prettyprint">
	<code>messageProducer.send(message);</code>
	</pre>

	<p><em>Now that we have a message in the queue, we will manage the queue by retrieving the number of messages in the queue
	(i.e. 1) and by removing the message which has been sent in step 8.</em></p>

	<li>We retrieve the <code>ObjectName</code> corresponding to the queue using a helper class <code>ObjectNameBuilder</code></li>
	<pre class="prettyprint">
	<code>ObjectName on = ObjectNameBuilder.DEFAULT.getJMSQueueObjectName(queue.getQueueName());</code>
	</pre>

	<li>We create a JMX Connector to connect to the server's MBeanServer using the <a href="http://docs.oracle.com/javase/8/docs/technotes/guides/management/agent.html#gdevg">standard JMX service URL</a></li>
	<pre class="prettyprint">
	<code>JMXConnector connector = JMXConnectorFactory.connect(new JMXServiceURL(JMX_URL), new HashMap());</code>
	</pre>

	<li>We retrieve a <code>MBeanServerConnection</code> from the JMX connector</li>
	<pre class="prettyprint">
	<code>TextMessage messageReceived = (TextMessage) messageConsumer.receive(5000);</code>
	</pre>

	<li>We create a <code>JMSQueueControl</code> proxy to manage the queue on the server</li>
	<pre class="prettyprint">
	<code>JMSQueueControl queueControl = (JMSQueueControl)MBeanServerInvocationHandler.newProxyInstance(mbsc,
	on,
	JMSQueueControl.class,
	false);
	</code>
	</pre>

	<li>We use this mbean proxy to retrieve the number of messages in the queue using the <code>getMessageCount</code> method</li>
	<pre class="prettyprint">
	<code>System.out.println(queueControl.getName() + " contains " + queueControl.getMessageCount() + " messages");</code>
	</pre>

	<li>We will now remove the message sent at step 8 using the <code>removeMessage</code> method with the JMS Message ID of the message</li>
	<pre class="prettyprint">
	<code>System.out.println("message has been removed: " + queueControl.removeMessage(message.getJMSMessageID()));</code>
	</pre>

	<li>We use again the mbean proxy to retrieve the number of messages. This time, it will display <code>0</code> messages</li>
	<pre class="prettyprint">
	<code>System.out.println(queueControl.getName() + " contains " + queueControl.getMessageCount() + " messages");</code>
	</pre>

	<li>Now we have finish the management operations, we close the JMX connector</li>
	<pre class="prettyprint">
	<code>connector.close()</code>
	</pre>

	<p><em>We will now try to consume the message sent to the queue but it won't be there: it has been removed by the management operation</em></p>

	<li>We create a JMS message consumer on the queue</li>
	<pre class="prettyprint">
	<code>MessageConsumer messageConsumer = session.createConsumer(queue);</code>
	</pre>

	<li>We start the connection. In order for delivery to occur on any consumers or subscribers on a connection, the connection must be started</li>
	<pre class="prettyprint">
	<code>connection.start();</code>
	</pre>

	<li>We try to receive a message from the queue. Since there is none, the call will timeout after 5000ms and messageReceived will be null
	</li>
	<pre class="prettyprint">
	<code>TextMessage messageReceived = (TextMessage) messageConsumer.receive(5000);
	System.out.println("Received message: " + messageReceived);</code>
	</pre>

	<li>And finally, <b>always</b> remember to close your JMS connections and resources after use, in a <code>finally</code> block. Closing a JMS connection will automatically close all of its sessions, consumers, producer and browser objects</li>

	<pre class="prettyprint">
	<code>finally
	{
	if (initialContext != null)
	{
	initialContext.close();
	}
	if (connection != null)
	{
	connection.close();
	}
	}</code>
	</pre>
	</ol>

	<h2>More information</h2>

	<ul>
	<li>User Manual's <a href="../../../docs/user-manual/en/html_single/index.html#management.jmx">Using Management Via JMX chapter</a></li>
	<li><a href="http://docs.oracle.com/javase/8/docs/technotes/guides/management/agent.html">Java management guide</a></li>
	</ul>
	</body>
	</html>