examples.jms.management.readme.html Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of hornetq-resources
The newest version!

  
    HornetQ Management Example
    
    
    
  
  
     Management Example
     This example shows how to manage HornetQ using JMS Messages to invoke management operations on the server.
     To manage HornetQ using JMX, see the JMX example.
     
     Example configuration

     HornetQ can be managed by sending JMS messages with specific properties to its management queue.
     
By default, the management name is called hornetq.management but this can be configured in hornetq-configuration.xml
              <management-address>hornetq.management</management-address>
     
     
     The management queue requires a "special" user permission manage to be able to receive management messages.
         This is also configured in hornetq-configuration.xml
              <security-setting match="hornetq.management">
            <permission type="manage" roles="guest" />
         </security-setting>
     
     
     Example step-by-step
     To run the example, simply type ./build.sh (or build.bat on windows) from this directory
     
        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 client-jndi.properties
                    InitialContext initialContext = getContext(0);
        

        We look up the JMS queue object from JNDI
                    Queue queue = (Queue) initialContext.lookup("/queue/exampleQueue");
        

        We look up the JMS connection factory object from JNDI
                    ConnectionFactory cf = (ConnectionFactory) initialContext.lookup("/ConnectionFactory");
        

        We create a JMS connection
                    connection = cf.createConnection();
        
        
        We create a JMS session. The session is created as non transacted and will auto acknowledge messages.
                    Session session = connection.createSession(false, Session.AUTO_ACKNOWLEDGE);
        

        We create a JMS message producer on the session. This will be used to send the messages.
                    MessageProducer messageProducer = session.createProducer(topic);
       

        We create a JMS text message that we are going to send.
                    TextMessage message = session.createTextMessage("This is a text message");
        

        We send message to the queue
                    messageProducer.send(message);
        

        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.
            
        We create the JMS management queue. This is a special queue which is not looked up from JNDI but instantiated directly
                    Queue managementQueue = new HornetQQueue("hornetq.management", "hornetq.management");
        

        We create a QueueRequestor to send messages to the management queue and receive replies (see queue-requestor example)
                    QueueRequestor requestor = new QueueRequestor(session, managementQueue);
        

        We start the connection to receive replies on the requestor
                   connection.start()
        
        
        We create a JMS message which will be used as a management message
                    Message m = session.createMessage();
        
        
        a management message has well-defined properties that HornetQ server needs to know to perform management operations.

            We use a helper class JMSManagementHelper to fill these properties:
            
                The name of the resource to manage jms.queue.exampleQueue 
                    (i.e. jms.queue followed by the name of the queue as defined in hornetq-jms.xml)
                In our case, the name of the attribute to retrieve MessageCount
            
        
                    JMSManagementHelper.putAttribute(m, "jms.queue.exampleQueue", "MessageCount");
        
        
        We send the management message using the requestor and wait for a reply
                    Message reply = requestor.request(m);
        
        
        We use a helper class JMSManagementHelper to retrieve the result from the reply message:
                    int messageCount = (Integer)JMSManagementHelper.getResult(reply);
            System.out.println(queue.getQueueName() + " contains " + messageCount + " messages");
        
        
        
We create another JMS message to use as a management message
                    m = session.createMessage();
        
        
        This time, we fill the management message with properties to invoke a management operation on the queue
            
                the name of the resource jms.queue.exampleQueue
                the name of the management operation removeMessage
                any parameters required to invoke the management operations (in our case, the JMS Message ID of the message sent in step 8)
            
        
                    JMSManagementHelper.putOperationInvocation(m, "jms.queue.exampleQueue", "removeMessage", message.getJMSMessageID());
        
        
        Again, we use the requestor to send the management message and wait for a reply
                    reply = requestor.request(m);
        
        
        We use the helper class to check that the operation was successfully invoked on the server
                    boolean success = JMSManagementHelper.hasOperationSucceeded(reply);
            System.out.println("operation invocation has succeeded: " + success);
        
        
        We use a helper class JMSManagementHelper to retrieve the result from the reply message:
            (in our case, the removeMessage method returns a boolean)
                    boolean messageRemoved = (Boolean)JMSManagementHelper.getResult(reply);
            System.out.println("message has been removed: " + messageRemoved);
        
            
        We will now consume the message from the queue but there will be none: the message sent at step 8 was removed by the management operation
            
        We create a JMS message consumer on the queue
                    MessageConsumer messageConsumer = session.createConsumer(queue);
        

        We try to receive a message from the queue. Since there is none, the call will timeout after 5000ms and messageReceived will be null
        
                    TextMessage messageReceived = (TextMessage) messageConsumer.receive(5000);
            System.out.println("Received message: " + messageReceived);
        
        
        And finally, always remember to close your JMS connections and resources after use, in a finally block. Closing a JMS connection will automatically close all of its sessions, consumers, producer and browser objects

                   finally
           {
              if (initialContext != null)
              {
                initialContext.close();
              }
              if (connection != null)
              {
                 connection.close();
              }
           }
        
     
     
     More information
     
     
        User Manual's Using Management Via JMS chapter