A Streaming Text Orientated Messaging Protocol Client
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
examples
lib/Net
t
Build.PL
CHANGES
MANIFEST
META.yml
Makefile.PL
README

README

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);

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:

      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' },
      } );

  connect
    This connects to the Stomp server. You must pass in a login and
    passcode.

    You may 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.

  can_read
    This returns whether a frame is waiting to be read. Optionally takes a
    timeout in seconds:

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

  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.

AUTHOR
    Leon Brocard <acme@astray.com>.

COPYRIGHT
    Copyright (C) 2006-9, Leon Brocard

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