Net::Stomp(3pm) 					User Contributed Perl Documentation					   Net::Stomp(3pm)

NAME

       Net::Stomp - A Streaming Text Orientated Messaging Protocol Client

SYNOPSIS

	 # send a message to the queue 'foo'
	 use Net::Stomp;
	 my $stomp = Net::Stomp->new( { hostname => 'localhost', port => '61613' } );
	 $stomp->connect( { login => 'hello', passcode => 'there' } );
	 $stomp->send(
	     { destination => '/queue/foo', body => 'test message' } );
	 $stomp->disconnect;

	 # subscribe to messages from the queue 'foo'
	 use Net::Stomp;
	 my $stomp = Net::Stomp->new( { hostname => 'localhost', port => '61613' } );
	 $stomp->connect( { login => 'hello', passcode => 'there' } );
	 $stomp->subscribe(
	     {	 destination		 => '/queue/foo',
		 'ack'			 => 'client',
		 'activemq.prefetchSize' => 1
	     }
	 );
	 while(1) {
	   my $frame = $stomp->receive_frame;
	   warn $frame->body; # do something here
	   $stomp->ack( { frame => $frame } );
	 }
	 $stomp->disconnect;

	 # write your own frame
	 my $frame = Net::Stomp::Frame->new(
	      { command => $command, headers => $conf, body => $body } );
	 $self->send_frame($frame);

	 # connect with failover supporting similar URI to ActiveMQ
	 $stomp = Net::Stomp->new({ failover => "failover://tcp://primary:61616" })
	 # "?randomize=..." and other parameters are ignored currently
	 $stomp = Net::Stomp->new({ failover => "failover:(tcp://primary:61616,tcp://secondary:61616)?randomize=false" })

	 # Or in a more natural perl way
	 $stomp = Net::Stomp->new({ hosts => [
	   { hostname => 'primary', port => 61616 },
	   { hostname => 'secondary', port => 61616 },
	 ] });

DESCRIPTION

       This module allows you to write a Stomp client. Stomp is the Streaming Text Orientated Messaging Protocol (or the Protocol Briefly Known as
       TTMP and Represented by the symbol :ttmp). It's a simple and easy to implement protocol for working with Message Orientated Middleware from
       any language. Net::Stomp is useful for talking to Apache ActiveMQ, an open source (Apache 2.0 licensed) Java Message Service 1.1 (JMS)
       message broker packed with many enterprise features.

       A Stomp frame consists of a command, a series of headers and a body - see Net::Stomp::Frame for more details.

       For details on the protocol see <http://stomp.codehaus.org/Protocol>.

       To enable the ActiveMQ Broker for Stomp add the following to the activemq.xml configuration inside the <transportConnectors> section:

	 <transportConnector name="stomp" uri="stomp://localhost:61613"/>

       To enable the ActiveMQ Broker for Stomp and SSL add the following inside the <transportConnectors> section:

	 <transportConnector name="stomp+ssl" uri="stomp+ssl://localhost:61612"/>

       For details on Stomp in ActiveMQ See <http://activemq.apache.org/stomp.html>.

METHODS

   new
       The constructor creates a new object. You must pass in a hostname and a port or set a failover configuration:

	 my $stomp = Net::Stomp->new( { hostname => 'localhost', port => '61613' } );

       If you want to use SSL, make sure you have IO::Socket::SSL and pass in the SSL flag:

	 my $stomp = Net::Stomp->new( {
	   hostname => 'localhost',
	   port     => '61612',
	   ssl	    => 1,
	 } );

       If you want to pass in IO::Socket::SSL options:

	 my $stomp = Net::Stomp->new( {
	   hostname    => 'localhost',
	   port        => '61612',
	   ssl	       => 1,
	   ssl_options => { SSL_cipher_list => 'ALL:!EXPORT' },
	 } );

       Failover

       There is experiemental failover support in Net::Stomp. You can specify failover in a similar maner to ActiveMQ
       (http://activemq.apache.org/failover-transport-reference.html <http://activemq.apache.org/failover-transport-reference.html>) for
       similarity with Java configs or using a more natural method to perl of passing in an array-of-hashrefs in the "hosts" parameter.

       Currently when ever Net::Stomp connects or reconnects it will simply try the next host in the list.

       Reconnect on "fork"

       By default Net::Stomp will reconnect, using a different socket, if the process "fork"s. This avoids problems when parent & child write to
       the socket at the same time. If, for whatever reason, you don't want this to happen, set "reconnect_on_fork" to 0 (either as a constructor
       parameter, or by calling the method).

   connect
       This connects to the Stomp server. You may pass in a "login" and "passcode" options.

       You may also pass in 'client-id', which specifies the JMS Client ID which is used in combination to the activemqq.subscriptionName to
       denote a durable subscriber.

	 $stomp->connect( { login => 'hello', passcode => 'there' } );

   send
       This sends a message to a queue or topic. You must pass in a destination and a body.

	 $stomp->send(
	     { destination => '/queue/foo', body => 'test message' } );

       To send a BytesMessage, you should set the field 'bytes_message' to 1.

   send_transactional
       This sends a message in transactional mode and fails if the receipt of the message is not acknowledged by the server:

	 $stomp->send_transactional(
	     { destination => '/queue/foo', body => 'test message' }
	 ) or die "Couldn't send the message!";

       If using ActiveMQ, you might also want to make the message persistent:

	 $stomp->send_transactional(
	     { destination => '/queue/foo', body => 'test message', persistent => 'true' }
	 ) or die "Couldn't send the message!";

   disconnect
       This disconnects from the Stomp server:

	 $stomp->disconnect;

   subscribe
       This subscribes you to a queue or topic. You must pass in a destination.

       The acknowledge mode defaults to 'auto', which means that frames will be considered delivered after they have been sent to a client. The
       other option is 'client', which means that messages will only be considered delivered after the client specifically acknowledges them with
       an ACK frame.

       Other options:

       'selector': which specifies a JMS Selector using SQL 92 syntax as specified in the JMS 1.1 specificiation. This allows a filter to be
       applied to each message as part of the subscription.

       'activemq.dispatchAsync': should messages be dispatched synchronously or asynchronously from the producer thread for non-durable topics in
       the broker. For fast consumers set this to false. For slow consumers set it to true so that dispatching will not block fast consumers.

       'activemq.exclusive': Would I like to be an Exclusive Consumer on a queue.

       'activemq.maximumPendingMessageLimit': For Slow Consumer Handlingon non-durable topics by dropping old messages - we can set a maximum
       pending limit which once a slow consumer backs up to this high water mark we begin to discard old messages.

       'activemq.noLocal': Specifies whether or not locally sent messages should be ignored for subscriptions. Set to true to filter out locally
       sent messages.

       'activemq.prefetchSize': Specifies the maximum number of pending messages that will be dispatched to the client. Once this maximum is
       reached no more messages are dispatched until the client acknowledges a message. Set to 1 for very fair distribution of messages across
       consumers where processing messages can be slow.

       'activemq.priority': Sets the priority of the consumer so that dispatching can be weighted in priority order.

       'activemq.retroactive': For non-durable topics do you wish this subscription to the retroactive.

       'activemq.subscriptionName': For durable topic subscriptions you must specify the same clientId on the connection and subscriberName on the
       subscribe.

	 $stomp->subscribe(
	     {	 destination		 => '/queue/foo',
		 'ack'			 => 'client',
		 'activemq.prefetchSize' => 1
	     }
	 );

   unsubscribe
       This unsubscribes you to a queue or topic. You must pass in a destination:

	 $stomp->unsubcribe({ destination => '/queue/foo' });

   receive_frame
       This blocks and returns you the next Stomp frame.

	 my $frame = $stomp->receive_frame;
	 warn $frame->body; # do something here

       The header bytes_message is 1 if the message was a BytesMessage.

       By default this method will block until a frame can be returned. If you wish to wait for a specified time pass a "timeout" argument:

	 # Wait half a second for a frame, else return undef
	 $stomp->receive_frame({ timeout => 0.5 })

   can_read
       This returns whether there is new data is waiting to be read from the STOMP server. Optionally takes a timeout in seconds:

	 my $can_read = $stomp->can_read;
	 my $can_read = $stomp->can_read({ timeout => '0.1' });

       "undef" says block until something can be read, 0 says to poll and return immediately.

   ack
       This acknowledges that you have received and processed a frame (if you are using client acknowledgements):

	 $stomp->ack( { frame => $frame } );

   send_frame
       If this module does not provide enough help for sending frames, you may construct your own frame and send it:

	 # write your own frame
	 my $frame = Net::Stomp::Frame->new(
	      { command => $command, headers => $conf, body => $body } );
	 $self->send_frame($frame);

SEE ALSO

       Net::Stomp::Frame.

AUTHORS

       Leon Brocard <acme@astray.com>, Thom May <thom.may@betfair.com>, Michael S. Fischer <michael@dynamine.net>, Ash Berlin
       <ash_github@firemirror.com>

CONTRIBUTORS

       Paul Driver <frodwith@cpan.org>, Andreas Faafeng <aff@cpan.org>, Vigith Maurice <vigith@yahoo-inc.com>, Stephen Fralich <sjf4@uw.edu>,
       Squeeks <squeek@cpan.org>, Chisel Wright <chisel@chizography.net>,

COPYRIGHT

       Copyright (C) 2006-9, Leon Brocard Copyright (C) 2009, Thom May, Betfair.com Copyright (C) 2010, Ash Berlin, Net-a-Porter.com Copyright (C)
       2010, Michael S. Fischer

       This module is free software; you can redistribute it or modify it under the same terms as Perl itself.

perl v5.14.2							    2012-03-15							   Net::Stomp(3pm)