Author: mcpierce
Date: Wed Feb 13 21:49:31 2013
New Revision: 1445948
URL: http://svn.apache.org/r1445948
Log:
QPID-4580: Provides perldoc documentation to the Perl bindings.
Once installed, the documentation can be accessed using the command:
perldoc [MODULE]
where [MODULE] is the name of one of the source modules. To get an
example app, one can type:
perldoc qpid_messaging
Modified:
qpid/trunk/qpid/cpp/bindings/qpid/perl/ChangeLog
qpid/trunk/qpid/cpp/bindings/qpid/perl/lib/qpid/messaging/Address.pm
qpid/trunk/qpid/cpp/bindings/qpid/perl/lib/qpid/messaging/Connection.pm
qpid/trunk/qpid/cpp/bindings/qpid/perl/lib/qpid/messaging/Duration.pm
qpid/trunk/qpid/cpp/bindings/qpid/perl/lib/qpid/messaging/Message.pm
qpid/trunk/qpid/cpp/bindings/qpid/perl/lib/qpid/messaging/Receiver.pm
qpid/trunk/qpid/cpp/bindings/qpid/perl/lib/qpid/messaging/Sender.pm
qpid/trunk/qpid/cpp/bindings/qpid/perl/lib/qpid/messaging/Session.pm
qpid/trunk/qpid/cpp/bindings/qpid/perl/lib/qpid_messaging.pm
Modified: qpid/trunk/qpid/cpp/bindings/qpid/perl/ChangeLog
URL:
http://svn.apache.org/viewvc/qpid/trunk/qpid/cpp/bindings/qpid/perl/ChangeLog?rev=1445948&r1=1445947&r2=1445948&view=diff
==============================================================================
--- qpid/trunk/qpid/cpp/bindings/qpid/perl/ChangeLog (original)
+++ qpid/trunk/qpid/cpp/bindings/qpid/perl/ChangeLog Wed Feb 13 21:49:31 2013
@@ -3,4 +3,4 @@ Version 0.22 (TBA):
* QPID-4416: Messages with embedded nulls won't break on getContentPtr
* QPID-4505: Provides unit tests for Address, Duration and Message
* QPID-4504: Broke up the Per classes into separate source modules
-
+ * QPID-4580: Added perldoc markup to each source module
Modified: qpid/trunk/qpid/cpp/bindings/qpid/perl/lib/qpid/messaging/Address.pm
URL:
http://svn.apache.org/viewvc/qpid/trunk/qpid/cpp/bindings/qpid/perl/lib/qpid/messaging/Address.pm?rev=1445948&r1=1445947&r2=1445948&view=diff
==============================================================================
--- qpid/trunk/qpid/cpp/bindings/qpid/perl/lib/qpid/messaging/Address.pm
(original)
+++ qpid/trunk/qpid/cpp/bindings/qpid/perl/lib/qpid/messaging/Address.pm Wed
Feb 13 21:49:31 2013
@@ -17,6 +17,69 @@
# under the License.
#
+=pod
+
+=head1 NAME
+
+qpid::messaging::Address
+
+=head1 DESCRIPTION
+
+An B<Address> represents an address to which messages can be sent or
+from which they can be received.
+
+=head2 THE ADDRESS STRING
+
+An address can be described suing the following pattern:
+
+E<lt>addressE<gt> [ / E<lt>subjectE<gt> ]= ; [ { E<lt>keyE<gt> :
E<lt>valueE<gt> , ... } ]
+
+where B<address> is a simple name and B<subject> is a subject or subject
+pattern.
+
+=head3 ADDRESS OPTIONS
+
+The options, encluded in curly braces, are key:value pairs delimited by a
comma.
+The values can be nested maps also enclosed in curly braces. Or they can be
+lists of values, where they are contained within square brackets but still
comma
+delimited, such as:
+
+ [value1,value2,value3]
+
+The following are the list of supported options:
+
+=over
+
+=item B<create>
+
+Indicates if the address should be created; values are B<always>, B<never>,
+B<sender> or B<receiver>
+
+=item B<assert>
+
+Indicates whether or not to assert any specified node properties; values are
+B<always>, B<never>, B<sender> or B<receiver>
+
+=item B<delete>
+
+Indicates whether or not to delete the addressed node when a sender or receiver
+is cancelled; values are B<always>, B<never>, B<sender> or B<receiver>
+
+=item B<node>
+
+A nested map describing properties for the addressed node. Properties are
+B<type> (B<topic> or B<queue>), B<durable> (a boolean), B<x-declare> (a nested
+map of AMQP 0.10-specific options) and B<x-bindings> (a nested list which
+specifies a queue, exchange or a binding key and arguments).
+
+=item B<link>
+
+=item B<mode>
+
+=back
+
+=cut
+
package qpid::messaging::Address;
use overload (
@@ -44,6 +107,29 @@ sub str {
return $self->get_implementation()->str();
}
+=pod
+
+=head1 CONSTRUCTOR
+
+Creates an B<Address>
+
+=over
+
+=item $address = new qpid::messaging::Address( addr )
+
+=back
+
+=head3 ARGUMENTS
+
+=over
+
+=item * addr
+
+The address string.
+
+=back
+
+=cut
sub new {
my ($class) = @_;
my ($self) = {};
@@ -77,6 +163,37 @@ sub get_implementation {
return $self->{_impl};
}
+=pod
+
+=head1 ATTRIBUTES
+
+=cut
+
+=pod
+
+=head2 NAME
+
+The name portion of the address.
+
+=over
+
+=item $address->set_name( name )
+
+=item $name = $address->get_name
+
+=back
+
+=head3 ARGUMENTS
+
+=over
+
+=item * name
+
+See the address string explanation.
+
+=back
+
+=cut
sub set_name {
my ($self) = @_;
my $impl = $self->{_impl};
@@ -91,6 +208,31 @@ sub get_name {
return $impl->getName();
}
+=pod
+
+=head2 SUBJECT
+
+The subject portion of the address.
+
+=over
+
+=item $address->set_subject( subject )
+
+=item $subject = $address->get_subject
+
+=back
+
+=head3 ARGUMENTS
+
+=over
+
+=item * subject
+
+See the address string explanation.
+
+=back
+
+=cut
sub set_subject {
my ($self) = @_;
my $impl = $self->{_impl};
@@ -105,6 +247,31 @@ sub get_subject {
return $impl->getSubject;
}
+=pod
+
+=head2 OPTIONS
+
+The address options.
+
+=over
+
+=item $address->set_options( options )
+
+=item @opts = $address->get_options
+
+=back
+
+=head3 ARGUMENTS
+
+=over
+
+=item * options
+
+The set of name:value pairs for the address. See the address string
explanation.
+
+=back
+
+=cut
sub set_options {
my ($self) = @_;
my $impl = $self->{_impl};
@@ -122,6 +289,35 @@ sub get_options {
return $impl->getOptions;
}
+=pod
+
+=head2 TYPE
+
+The type of the address determines how B<Sender> and B<Receiver> objects are
+constructed for it. It also affects how a b<reply-to> address is encoded.
+
+If no type is specified then it willb e determined by querying the broker.
+Explicitly setting the type prevents this.
+
+=over
+
+=item $address->set_type( type )
+
+=item $type = $address->get_type
+
+=back
+
+=head3 ARGUMENTS
+
+=over
+
+=item * type
+
+Values can be either B<queue> or B<type>.
+
+=back
+
+=cut
sub set_type {
my ($self) = @_;
my $impl = $self->{_impl};
Modified:
qpid/trunk/qpid/cpp/bindings/qpid/perl/lib/qpid/messaging/Connection.pm
URL:
http://svn.apache.org/viewvc/qpid/trunk/qpid/cpp/bindings/qpid/perl/lib/qpid/messaging/Connection.pm?rev=1445948&r1=1445947&r2=1445948&view=diff
==============================================================================
--- qpid/trunk/qpid/cpp/bindings/qpid/perl/lib/qpid/messaging/Connection.pm
(original)
+++ qpid/trunk/qpid/cpp/bindings/qpid/perl/lib/qpid/messaging/Connection.pm Wed
Feb 13 21:49:31 2013
@@ -17,8 +17,55 @@
# under the License.
#
+=pod
+
+=head1 NAME
+
+qpid::messaging::Connection
+
+=head1 DESCRIPTION
+
+A B<qpid::messaging::Connection> represents a network connection to a remote
+endpoint.
+
+=cut
+
package qpid::messaging::Connection;
+=pod
+
+=head1 CONSTRUCTOR
+
+=over
+
+=item $conn = new qpid::messaging::Connection
+
+=item $conn = new qpid::messaging::Connection( url )
+
+=item $conn = new qpid::messaging::Connection( url, options )
+
+Creates a connection object. Raises a C<MessagingError> if an invalid
+connection option is used.
+
+=back
+
+=head3 ARGUMENTS
+
+=over
+
+=item * url
+
+The URL for the broker. See B<qpid::messaging::Address> for more on
+ address strings
+
+=item * options
+
+The connection options.
+
+=back
+
+=cut
+
sub new {
my ($class) = @_;
my $self = {
@@ -31,6 +78,31 @@ sub new {
return $self;
}
+=pod
+
+=head1 ACTIONS
+
+=cut
+
+
+=pod
+
+=head2 OPENING AND CLOSING CONNECTIONS
+
+=cut
+
+
+=pod
+
+=over
+
+=item $conn->open
+
+Establishes the connection to the broker.
+
+=back
+
+=cut
sub open {
my ($self) = @_;
my $impl = $self->{_impl};
@@ -48,6 +120,17 @@ sub open {
$impl->open() unless $impl->isOpen()
}
+=pod
+
+=over
+
+=item $conn->is_open
+
+Reports whether the connection is open.
+
+=back
+
+=cut
sub is_open {
my ($self) = @_;
my $impl = $self->{_impl};
@@ -59,6 +142,17 @@ sub is_open {
}
}
+=pod
+
+=over
+
+=item $conn->close
+
+Closes the connection.
+
+=back
+
+=cut
sub close {
my ($self) = @_;
@@ -70,6 +164,36 @@ sub close {
}
}
+=pod
+
+=head2 SESSIONS
+
+=cut
+
+
+=pod
+
+=over
+
+=item $session = $conn->create_session
+
+=item $conn->create_session( name )
+
+Creates a new session.
+
+=back
+
+=head3 ARGUMENTS
+
+=over
+
+=item * name
+
+Specifies a name for the session.
+
+=back
+
+=cut
sub create_session {
my ($self) = @_;
@@ -82,6 +206,29 @@ sub create_session {
return new qpid::messaging::Session($session, $self);
}
+=pod
+
+=over
+
+=item $session = $conn->create_transactional_session
+
+=item $session = $conn->create_transaction_session( name )
+
+Creates a transactional session.
+
+=back
+
+=head3 ARGUMENTS
+
+=over
+
+=item * name
+
+Specifies a name for the session.
+
+=back
+
+=cut
sub create_transactional_session {
my ($self) = @_;
@@ -94,6 +241,25 @@ sub create_transactional_session {
return new qpid::messaging::Session($session, $self);
}
+=pod
+
+=over
+
+=item $session = $conn->get_session( name )
+
+Returns the session with the specified name.
+
+=over
+
+=item $name
+
+The name given to the session when it was created.
+
+=back
+
+=back
+
+=cut
sub get_session {
my ($self) = @_;
my $impl = $self->{_impl};
@@ -101,6 +267,20 @@ sub get_session {
return $impl->getSession($_[1]);
}
+=pod
+
+=over
+
+=item $uname = $conn->get_authenticated_username
+
+Returns the username user to authenticate with the broker.
+
+If the conneciton did not use authentication credentials, then the
+username returned is "anonymous".
+
+=back
+
+=cut
sub get_authenticated_username {
my ($self) = @_;
my $impl = $self->{_impl};
Modified: qpid/trunk/qpid/cpp/bindings/qpid/perl/lib/qpid/messaging/Duration.pm
URL:
http://svn.apache.org/viewvc/qpid/trunk/qpid/cpp/bindings/qpid/perl/lib/qpid/messaging/Duration.pm?rev=1445948&r1=1445947&r2=1445948&view=diff
==============================================================================
--- qpid/trunk/qpid/cpp/bindings/qpid/perl/lib/qpid/messaging/Duration.pm
(original)
+++ qpid/trunk/qpid/cpp/bindings/qpid/perl/lib/qpid/messaging/Duration.pm Wed
Feb 13 21:49:31 2013
@@ -17,14 +17,78 @@
# under the License.
#
+=pod
+
+=head1 NAME
+
+qpid::messaging::Duration
+
+=head1 DESCRIPTION
+
+A B<qpid::messaging::Duration> represents a period of time in milliseconds.
+
+=head1 NAMED DURATIONS
+
+The following named durations are available as constants
+
+=over
+
+=item B<FOREVER>
+
+The maximum wait time, equal to the maximum integer value for the platform.
+Effective this will wait forever.
+
+=item B<IMMEDIATE>
+
+An alias for 0 milliseconds.
+
+=item B<SECOND>
+
+An alias for 1,000 milliseconds.
+
+=item B<MINUTE>
+
+An alias for 60,000 milliseconds.
+
+=back
+
+=cut
+
package qpid::messaging::Duration;
+=pod
+
+=head1 OPERATORS
+
+=cut
+
use overload (
"*" => \&multiply,
"==" => \&equalify,
"!=" => \&unequalify,
);
+=pod
+
+=over
+
+=item $doubled = $duration * $factor
+
+=item $doubled = $duration * 2
+
+Multiplies the duration and returns a new instance.
+
+=over
+
+=item $factor
+
+A factor for multiplying the duration.
+
+=back
+
+=back
+
+=cut
sub multiply {
my ($self) = @_;
my $factor = $_[1];
@@ -54,6 +118,29 @@ sub unequalify {
return ($self->get_milliseconds() != $that->get_milliseconds()) ? 1 : 0;
}
+=pod
+
+=head1 CONSTRUCTOR
+
+Creates a new instance.
+
+=over
+
+=item duration = new qpid::messaging::Duration( time )
+
+=back
+
+=head3 ARGUMENTS
+
+=over
+
+=item * time
+
+The duration in B<milliseconds>.
+
+=back
+
+=cut
sub new {
my ($class) = @_;
my $duration = $_[1];
@@ -73,6 +160,26 @@ sub new {
return $self;
}
+=pod
+
+=head1 ATTRIBUTES
+
+=cut
+
+
+=pod
+
+=head2 MILLISECONDS
+
+The length of time is measured in milliseconds.
+
+=over
+
+=item time = $duration->get_milliseconds
+
+=back
+
+=cut
sub get_milliseconds {
my ($self) = @_;
my $impl = $self->{_impl};
Modified: qpid/trunk/qpid/cpp/bindings/qpid/perl/lib/qpid/messaging/Message.pm
URL:
http://svn.apache.org/viewvc/qpid/trunk/qpid/cpp/bindings/qpid/perl/lib/qpid/messaging/Message.pm?rev=1445948&r1=1445947&r2=1445948&view=diff
==============================================================================
--- qpid/trunk/qpid/cpp/bindings/qpid/perl/lib/qpid/messaging/Message.pm
(original)
+++ qpid/trunk/qpid/cpp/bindings/qpid/perl/lib/qpid/messaging/Message.pm Wed
Feb 13 21:49:31 2013
@@ -17,8 +17,46 @@
# under the License.
#
+=pod
+
+=head1 NAME
+
+qpid::messaging::Message
+
+=head1 DESCRIPTION
+
+A B<qpid::messaging::Message> a routable piece of information.
+
+=cut
+
package qpid::messaging::Message;
+
+=pod
+
+=head1 CONSTRUCTOR
+
+Creates a B<Message>.
+
+=over
+
+=item $msg = new qpid::messaging::Message
+
+=item $msg = new qpid::messaging::Message( $content )
+
+=back
+
+=head3 ARGUMENTS
+
+=over
+
+=item * $content
+
+The message's content.
+
+=back
+
+=cut
sub new {
my ($class) = @_;
my $content = $_[1] if (@_ > 1);
@@ -44,6 +82,41 @@ sub get_implementation {
return $self->{_impl};
}
+
+=pod
+
+=head1 ATTRIBUTES
+
+=cut
+
+=pod
+
+=head2 REPLY TO ADDRESS
+
+The reply-to address tells a receiver where to send any responses.
+
+=over
+
+=item $msg->set_reply_to( "#reqly-queue;{create:always}" )
+
+=item $msg->set_reply_to( address )
+
+=item $address = $msg->get_reply_to
+
+=back
+
+=head3 ARGUMENTS
+
+=over
+
+=item * address
+
+The address. Can be either an instance of B<qpid::messaging::Address> or else
an
+address string.
+
+=back
+
+=cut
sub set_reply_to {
my ($self) = @_;
my $impl = $self->{_impl};
@@ -65,6 +138,21 @@ sub get_reply_to {
return new qpid::messaging::Address($impl->getReplyTo());
}
+=pod
+
+=head2 SUBJECT
+
+=over
+
+=item $msg->set_subject( "responses" )
+
+=item $msg->set_subject( subject )
+
+=item $subject = $msg->get_subject
+
+=back
+
+=cut
sub set_subject {
my ($self) = @_;
my $impl = $self->{_impl};
@@ -79,6 +167,35 @@ sub get_subject {
return $impl->getSubject;
}
+=pod
+
+=head2 CONTENT TYPE
+
+This should be set by the sending application and indicates to the
+recipients of the message how to interpret or decide the content.
+
+By default, only dictionaries and maps are automatically given a content
+type. If this content type is replaced then retrieving the content will
+not behave correctly.
+
+=over
+
+=item $msg->set_content_type( content_type )
+
+=back
+
+=head3 ARGUMENTS
+
+=over
+
+=item * content_type
+
+The content type. For a list this would be C<amqp/list> and for a hash it is
+C<amqp/map>.
+
+=back
+
+=cut
sub set_content_type {
my ($self) = @_;
my $type = $_[1];
@@ -94,6 +211,22 @@ sub get_content_type {
return $impl->getContentType;
}
+=pod
+
+=head2 MESSAGE ID
+
+A message id must be a UUID type. A non-UUID value will be converted
+to a zero UUID, thouygh a blank ID will be left untouched.
+
+=over
+
+=item $msg->set_message_id( id )
+
+=item $id = $msg->get_message_id
+
+=back
+
+=cut
sub set_message_id {
my ($self) = @_;
my $impl = $self->{_impl};
@@ -111,6 +244,25 @@ sub get_message_id {
return $impl->getMessageId;
}
+=pod
+
+=head2 USER ID
+
+The user id should, in general, be the user-id which was used when
+authenticating the connection itself, as the messaging infrastructure
+will verify this.
+
+See B<qpid::messaging::Address#authenticated_username>.
+
+=over
+
+=item $msg->set_user_id( id )
+
+=item $id = $msg->get_user_id
+
+=back
+
+=cut
sub set_user_id {
my ($self) = @_;
my $impl = $self->{_impl};
@@ -125,6 +277,27 @@ sub get_user_id {
return $impl->getUserId;
}
+=pod
+
+=head2 CORRELATION ID
+
+The correlation id can be used as part of a protocol for message exchange
+patterns; e.g., a request-response pattern might require the correlation id
+of the request and hte response to match, or it might use the message id of
+the request as the correlation id on the response.
+
+B<NOTE:> If the id is not a string then the id is setup using the object's
+string representation.
+
+=over
+
+=item $msg->set_correlation_id( id )
+
+=item $id = $msg->get_correlation_id
+
+=back
+
+=cut
sub set_correlation_id {
my ($self) = @_;
my $impl = $self->{_impl};
@@ -139,6 +312,26 @@ sub get_correlation_id {
return $impl->getCorrelationId;
}
+=pod
+
+=head2 PRIORITY
+
+The priority may be used by the messaging infrastructure to prioritize
+delivery of messages with higher priority.
+
+B<NOTE:> If the priority is not an integer type then it is set using the
+object's integer represtation. If the integer value is greater than an
+8-bit value then only 8-bits are used.
+
+=over
+
+=item $msg->set_priority( priority )
+
+=item $priority = $msg->get_priority
+
+=back
+
+=cut
sub set_priority {
my ($self) = @_;
my $impl = $self->{_impl};
@@ -159,6 +352,36 @@ sub get_priority {
return $impl->getPriority;
}
+=pod
+
+=head2 TIME TO LIVE
+
+This can be used by the messaging infrastructure to discard messages
+that are no longer of relevance.
+
+=over
+
+=item $msg->set_ttl( ttl )
+
+=item $ttl = $msg->get_ttl
+
+=back
+
+=head3 ARGUMENTS
+
+=over
+
+=item * ttl
+
+A B<qpid::messaging::Duration> instance. If it is not, then a new instance
+is created using the integer value for the argument.
+
+A B<negative> value is treated as the equipment of
+B<qpid::messaging::Duration::FOREVER>.
+
+=back
+
+=cut
sub set_ttl {
my ($self) = @_;
my $impl = $self->{_impl};
@@ -187,6 +410,23 @@ sub get_ttl {
return new qpid::messaging::Duration($impl->getTtl);
}
+=pod
+
+=head2 DURABILITY
+
+The durability of a B<Message> is a hint to the messaging infrastructure that
+the message should be persisted or otherwise stored. This helps to ensure that
+the message is not lost due to failures or a shutdown.
+
+=over
+
+=item $msg->set_durable( 1 )
+
+=item $durable = $msg->get_durable
+
+=back
+
+=cut
sub set_durable {
my ($self) = @_;
my $impl = $self->{_impl};
@@ -204,6 +444,23 @@ sub get_durable {
return $impl->getDurable;
}
+=pod
+
+=head2 REDELIVERED
+
+This is a hint to the messaging infrastructure that if de-duplication is
+required, that this message should be examined to determine if it is a
+duplicate.
+
+=over
+
+=item $msg->set_redelivered( 1 )
+
+=item $redelivered = $msg->get_redelivered
+
+=back
+
+=cut
sub set_redelivered {
my ($self) = @_;
my $impl = $self->{_impl};
@@ -221,6 +478,37 @@ sub get_redelivered {
return $impl->getRedelivered;
}
+=pod
+
+=head2 PROPERTIES
+
+Named properties for the message are name/value pairs.
+
+=over
+
+=item $msg->set_property( name, value )
+
+=item $value = $msg->get_property( name )
+
+=item @props = $msg->get_properties
+
+=back
+
+=head3 ARGUMENTS
+
+=over
+
+=item * name
+
+The property name.
+
+=item * value
+
+The property value.
+
+=back
+
+=cut
sub set_property {
my ($self) = @_;
my $impl = $self->{_impl};
@@ -237,6 +525,30 @@ sub get_properties {
return $impl->getProperties;
}
+=pod
+
+=head2 CONTENT
+
+The message content.
+
+=begin _private
+
+TODO: Need to make the content automatically encode and decode for
+hashes and lists.
+
+=end _private
+
+=over
+
+=item $msg->set_content( content )
+
+=item $content = $msg->get_content
+
+=item $length = $msg->get_content_size
+
+=back
+
+=cut
sub set_content {
my ($self) = @_;
my $content = $_[1];
Modified: qpid/trunk/qpid/cpp/bindings/qpid/perl/lib/qpid/messaging/Receiver.pm
URL:
http://svn.apache.org/viewvc/qpid/trunk/qpid/cpp/bindings/qpid/perl/lib/qpid/messaging/Receiver.pm?rev=1445948&r1=1445947&r2=1445948&view=diff
==============================================================================
--- qpid/trunk/qpid/cpp/bindings/qpid/perl/lib/qpid/messaging/Receiver.pm
(original)
+++ qpid/trunk/qpid/cpp/bindings/qpid/perl/lib/qpid/messaging/Receiver.pm Wed
Feb 13 21:49:31 2013
@@ -17,6 +17,38 @@
# under the License.
#
+=pod
+
+=head1 NAME
+
+qpid::messaging::Receiver
+
+=head1 DESCRIPTION
+
+A B<qpid::messaging::Receiver> is the entity though which messages are
received.
+
+An instance can only be created using an active (i.e., not previously closed)
+B<qpid::messaging::Session>.
+
+=head1 EXAMPLE
+
+ # create a connection and a session
+ my $conn = new qpid::messaging::Connection("mybroker:5672");
+ conn->open;
+ my $session = $conn->create_session;
+
+ # create a receiver that listens on the "updates" topic of "alerts"
+ my $recv = $session->create_receiver("alerts/updates");
+
+ # set the local queue size to hold a maximum of 100 messages
+ $recv->set_capacity(100);
+
+ # wait for an incoming message and process it
+ my $incoming = $recv->get;
+ process($incoming)
+
+=cut
+
package qpid::messaging::Receiver;
sub new {
@@ -33,6 +65,42 @@ sub new {
return $self;
}
+=pod
+
+=head1 ACTIONS
+
+=cut
+
+
+=pod
+
+There are two ways to retrieve messages: from the local queue or from the
+remote queue.
+
+=head2 GETTING FROM THE LOCAL QUEUE
+
+Messages can be held locally in message queues.
+
+=over
+
+=item $incoming = $receiver->get
+
+=item $incoming = $receiver->get( timeout)
+
+=back
+
+=head3 ARGUMENTS
+
+=over
+
+=item * timeout
+
+The period of time to wait for a message before raising an exception. If no
+period of time is specified then the default is to wait B<forever>.
+
+=back
+
+=cut
sub get {
my ($self) = @_;
my $duration = $_[1];
@@ -49,6 +117,33 @@ sub get {
}
}
+=pod
+
+=head2 FETCHING FROM THE REMOTE QUEUE
+
+Messages held in the remote queue must be fetched from the broker in order
+to be processed.
+
+=over
+
+=item $incoming = $receiver->fetch
+
+=item $incoming = $receiver->fetch( time )
+
+=back
+
+=head3 ARGUMENTS
+
+=over
+
+=item * timeout
+
+The period of time to wait for a message before raising an exception. If no
+period of time is specified then the default is to wait B<forever>.
+
+=back
+
+=cut
sub fetch {
my ($self) = @_;
my $duration = $_[1];
@@ -64,6 +159,49 @@ sub fetch {
return new qpid::messaging::Message("", $message);
}
+=pod
+
+=head2 CLOSING THE RECEIVER
+
+=over
+
+=item receiver->close
+
+Closes the receiver.
+
+=back
+
+=cut
+sub close {
+ my ($self) = @_;
+ my $impl = $self->{_impl};
+
+ $impl->close;
+}
+
+=pod
+
+=head1 ATTRIBUTES
+
+=cut
+
+
+=pod
+
+=head2 CAPACITY
+
+The maximum number of messages that are prefected and held locally is
+determined by the capacity of the receiver.
+
+=over
+
+=item $receiver->set_capacity( size )
+
+=item $size = $receiver->get_capacity
+
+=back
+
+=cut
sub set_capacity {
my ($self) = @_;
my $capacity = $_[1];
@@ -79,6 +217,22 @@ sub get_capacity {
return $impl->getCapacity;
}
+=pod
+
+=head2 AVAILABLE
+
+The number of messages waiting in the local queue.
+
+The value is always in the range 0 <= B<available> <= B<capacity>.
+
+=over
+
+=item $count = $receiver->get_available
+
+=back
+
+=cut
+
sub get_available {
my ($self) = @_;
my $impl = $self->{_impl};
@@ -86,6 +240,18 @@ sub get_available {
return $impl->getAvailable;
}
+=pod
+
+=over
+
+=item $count = $receiver->get_unsettled
+
+Returns the number of messages that have been received and acknowledged but
+whose acknowledgements have not been confirmed by the sender.
+
+=back
+
+=cut
sub get_unsettled {
my ($self) = @_;
my $impl = $self->{_impl};
@@ -93,20 +259,17 @@ sub get_unsettled {
return $impl->getUnsettled;
}
-sub close {
- my ($self) = @_;
- my $impl = $self->{_impl};
+=pod
- $impl->close;
-}
+=over
-sub is_closed {
- my ($self) = @_;
- my $impl = $self->{_impl};
+=item $name = $receiver->get_name
- return $impl->isClosed;
-}
+Returns the name of the receiver.
+=back
+
+=cut
sub get_name {
my ($self) = @_;
my $impl = $self->{_impl};
@@ -114,6 +277,18 @@ sub get_name {
return $impl->getName;
}
+=pod
+
+=over
+
+=item $session = $receiver->get_session
+
+Returns the B<qpid::messaging::Session> instance from which this
+receiver was created.
+
+=back
+
+=cut
sub get_session {
my ($self) = @_;
my $impl = $self->{_impl};
@@ -121,4 +296,22 @@ sub get_session {
return $impl->{_session};
}
+=pod
+
+=over
+
+=item $receiver->is_closed
+
+Returns whether the receiver is closed.
+
+=back
+
+=cut
+sub is_closed {
+ my ($self) = @_;
+ my $impl = $self->{_impl};
+
+ return $impl->isClosed;
+}
+
1;
Modified: qpid/trunk/qpid/cpp/bindings/qpid/perl/lib/qpid/messaging/Sender.pm
URL:
http://svn.apache.org/viewvc/qpid/trunk/qpid/cpp/bindings/qpid/perl/lib/qpid/messaging/Sender.pm?rev=1445948&r1=1445947&r2=1445948&view=diff
==============================================================================
--- qpid/trunk/qpid/cpp/bindings/qpid/perl/lib/qpid/messaging/Sender.pm
(original)
+++ qpid/trunk/qpid/cpp/bindings/qpid/perl/lib/qpid/messaging/Sender.pm Wed Feb
13 21:49:31 2013
@@ -17,6 +17,37 @@
# under the License.
#
+=pod
+
+=head1 NAME
+
+qpid::messaging::Sender
+
+=head1 DESCRIPTION
+
+A B<qpid::messaging::Sender> is the entity through which messages are sent.
+
+An instance can only be created using an active (i.e., not previously closed)
+B<qpid::messaging::Session>.
+
+=head1 EXAMPLE
+
+ # create a connection and a session
+ my $conn = new qpid::messaging::Connection("mybroker:5672");
+ conn->open;
+ my $session = $conn->create_session;
+
+ # create a sender that posts messages to the "updates" queue
+ my $sender = $session->create_sender "updates;{create:always}"
+
+ # begin sending updates
+ while( 1 ) {
+ my $content = wait_for_event;
+ $sender->send(new qpid::messaging::Message($content));
+ }
+
+=cut
+
package qpid::messaging::Sender;
sub new {
@@ -33,6 +64,43 @@ sub new {
return $self;
}
+=pod
+
+=head1 ACTIONS
+
+=cut
+
+
+=pod
+
+=head2 SENDING MESSAGES
+
+=over
+
+=item $sender->send( message )
+
+=item $sender->send( message, block)
+
+Sends a message, optionally blocking until the message is received by
+the broker.
+
+=back
+
+=head3 ARGUMENTS
+
+=over
+
+=item * message
+
+The message to be sent.
+
+=item * block
+
+If true then blocks until the message is received.
+
+=back
+
+=cut
sub send {
my ($self) = @_;
my $message = $_[1];
@@ -45,6 +113,19 @@ sub send {
$impl->send($message->get_implementation, $sync);
}
+=pod
+
+=head2 CLOSING THE SENDER
+
+=item sender->close
+
+Closes the sender.
+
+This does not affect the ownering B<Session> or B<Connection>
+
+=back
+
+=cut
sub close {
my ($self) = @_;
my $impl = $self->{_impl};
@@ -52,6 +133,30 @@ sub close {
$impl->close;
}
+=pod
+
+=head1 ATTRIBUTES
+
+=cut
+
+=pod
+
+=head2 CAPACITY
+
+The capacity is the number of outoing messages that can be held pending
+confirmation of receipt by the broker.
+
+=over
+
+=item sender->set_capacity( size )
+
+=item $size = sender->get_capacity
+
+=back
+
+=back
+
+=cut
sub set_capacity {
my ($self) = @_;
my $impl = $self->{_impl};
@@ -66,6 +171,19 @@ sub get_capacity {
return $impl->getCapacity;
}
+=pod
+
+=head2 UNSETTLED
+
+The number of messages sent that are pending receipt confirmation by the
broker.
+
+=over
+
+=item $count = sender->get_unsettled
+
+=back
+
+=cut
sub get_unsettled {
my ($self) = @_;
my $impl = $self->{_impl};
@@ -73,6 +191,24 @@ sub get_unsettled {
return $impl->getUnsettled;
}
+=pod
+
+=head2 AVAILABLE
+
+The available slots for sending messages.
+
+This differences form B<capacity> in that it is the available slots in the
+senders capacity for holding outgoing messages. The difference between
+capacity and available is the number of messages that have no been delivered
+yet.
+
+=over
+
+=item $slots = sender->get_available
+
+=back
+
+=cut
sub get_available {
my ($self) = @_;
my $impl = $self->{_impl};
@@ -80,6 +216,19 @@ sub get_available {
return $impl->getAvailable();
}
+=pod
+
+=head2 NAME
+
+The human-readable name for this sender.
+
+=over
+
+=item $name = sender-get_name
+
+=back
+
+=cut
sub get_name {
my ($self) = @_;
my $impl = $self->{_impl};
@@ -87,6 +236,19 @@ sub get_name {
return $impl->getName;
}
+=pod
+
+=head2 SESSION
+
+The owning session from which the sender was created.
+
+=over
+
+=item $session = $sender->get_session
+
+=back
+
+=cut
sub get_session {
my ($self) = @_;
Modified: qpid/trunk/qpid/cpp/bindings/qpid/perl/lib/qpid/messaging/Session.pm
URL:
http://svn.apache.org/viewvc/qpid/trunk/qpid/cpp/bindings/qpid/perl/lib/qpid/messaging/Session.pm?rev=1445948&r1=1445947&r2=1445948&view=diff
==============================================================================
--- qpid/trunk/qpid/cpp/bindings/qpid/perl/lib/qpid/messaging/Session.pm
(original)
+++ qpid/trunk/qpid/cpp/bindings/qpid/perl/lib/qpid/messaging/Session.pm Wed
Feb 13 21:49:31 2013
@@ -17,6 +17,20 @@
# under the License.
#
+=pod
+
+=head1 NAME
+
+qpid::messaging::Session
+
+=head1 DESCRIPTION
+
+A B<qpid::messaging::Session> represents a distinct conversation between end
+points. They are created from an active (i.e, not closed) B<Connection>.
+
+A session is used to acknowledge individual or all messages that have
+passed through it, as well as for creating senders and receivers for
conversing.
+=cut
package qpid::messaging::Session;
sub new {
@@ -33,6 +47,24 @@ sub new {
return $self;
}
+=pod
+
+=head1 ACTIONS
+
+=cut
+
+
+=pod
+
+=head2 CLOSING THE SESSION
+
+=over
+
+=item $session->close
+
+=back
+
+=cut
sub close {
my ($self) = @_;
my $impl = $self->{_impl};
@@ -40,6 +72,21 @@ sub close {
$impl->close;
}
+=pod
+
+=head2 TRANSACTIONS
+
+Transactions can be rolled back or committed.
+
+=over
+
+=item $session->commit
+
+=item $session->rollback
+
+=back
+
+=cut
sub commit {
my ($self) = @_;
my $impl = $self->{_impl};
@@ -54,7 +101,30 @@ sub rollback {
$impl->rollback;
}
-# TODO how to handle acknowledging a specific message
+=pod
+
+=head2 MESSAGE DISPOSITIONS
+
+=cut
+
+
+=pod
+
+=over
+
+=item $session->acknowledge( msg )
+
+Acknowledges that a specific message that has been received.
+
+=back
+
+=begin _private
+
+TODO: How to handle acknowledging a specific message?
+
+=end _private
+
+=cut
sub acknowledge {
my ($self) = @_;
my $sync = $_[1] || 0;
@@ -64,9 +134,17 @@ sub acknowledge {
$impl->acknowledge($sync);
}
-sub acknowledge_up_to {
-}
+=pod
+
+=over
+=item $session->reject( msg )
+
+Rejects the specified message. A reject message will not be redelivered.
+
+=back
+
+=cut
sub reject {
my ($self) = @_;
my $impl = $self->{_impl};
@@ -74,6 +152,18 @@ sub reject {
$impl->reject($_[1]);
}
+=pod
+
+=over
+
+=item $session->release( msg )
+
+Releases the specified message, which allows the broker to attempt to
+redeliver it.
+
+=back
+
+=cut
sub release {
my ($self) = @_;
my $impl = $self->{_impl};
@@ -81,6 +171,29 @@ sub release {
$impl->release($_[1]);
}
+=pod
+
+=over
+
+=item $session->sync
+
+=item $session->sync( block )
+
+Requests synchronization with the broker.
+
+=back
+
+=head3 ARGUMENTS
+
+=over
+
+=item * block
+
+If true, then the call blocks until the process completes.
+
+=back
+
+=cut
sub sync {
my ($self) = @_;
my $impl = $self->{_impl};
@@ -92,29 +205,34 @@ sub sync {
}
}
-sub get_receivable {
- my ($self) = @_;
- my $impl = $self->{_impl};
+=pod
- return $impl->getReceivable;
-}
+=head2 SENDERS AND RECEIVERS
-sub get_unsettled_acks {
- my ($self) = @_;
- my $impl = $self->{_impl};
+=cut
- return $impl->getUnsettledAcks;
-}
-sub get_next_receiver {
- my ($self) = @_;
- my $impl = $self->{_impl};
+=pod
- my $timeout = $_[1] || qpid::messaging::Duration::FOREVER;
+=over
- return $impl->getNextReceiver($timeout);
-}
+=item $sender = $session->create_sender( address )
+
+Creates a new sender.
+
+=back
+
+=head3 ARGUMENTS
+
+=over
+
+=item * address
+The sender address. See B<qpid::messaging::Address> for more details
+
+=back
+
+=cut
sub create_sender {
my ($self) = @_;
my $impl = $self->{_impl};
@@ -130,20 +248,27 @@ sub create_sender {
return new qpid::messaging::Sender($send_impl, $self);
}
-sub create_receiver {
- my ($self) = @_;
- my $impl = $self->{_impl};
+=pod
- my $address = $_[1];
+=over
- if (ref($address) eq "qpid::messaging::Address") {
- $address = $address->get_implementation();
- }
- my $recv_impl = $impl->createReceiver($address);
+=item $sender = $session->get_session( name )
- return new qpid::messaging::Receiver($recv_impl, $self);
-}
+=back
+
+=head3 ARGUMENTS
+
+=over
+
+=item * name
+
+The name of the sender.
+
+Raises an exception when no sender with that name exists.
+=back
+
+=cut
sub get_sender {
my ($self) = @_;
my $impl = $self->{_impl};
@@ -158,6 +283,58 @@ sub get_sender {
return $sender;
}
+=pod
+
+=over
+
+=item $receiver = $session->create_receiver( address )
+
+=back
+
+=head3 ARGUMENTS
+
+=over
+
+=item * address
+
+The receiver address. see B<qpid::messaging::Address> for more details.
+
+=back
+
+=cut
+sub create_receiver {
+ my ($self) = @_;
+ my $impl = $self->{_impl};
+
+ my $address = $_[1];
+
+ if (ref($address) eq "qpid::messaging::Address") {
+ $address = $address->get_implementation();
+ }
+ my $recv_impl = $impl->createReceiver($address);
+
+ return new qpid::messaging::Receiver($recv_impl, $self);
+}
+
+=pod
+
+=over
+
+=item $receiver = $session->get_receiver( name )
+
+=back
+
+=head3 ARGUMENTS
+
+=over
+
+=item * name
+
+The name of the receiver.
+
+=back
+
+=cut
sub get_receiver {
my ($self) = @_;
my $impl = $self->{_impl};
@@ -172,6 +349,107 @@ sub get_receiver {
return $receiver;
}
+=pod
+
+=head1 ATTRIBUTES
+
+=cut
+
+
+=pod
+
+=head2 RECEIVABLE
+
+The total number of receivable messages, and messages already received,
+by receivers associated with this session.
+
+=over
+
+=item $session->get_receivable
+
+=back
+
+=cut
+sub get_receivable {
+ my ($self) = @_;
+ my $impl = $self->{_impl};
+
+ return $impl->getReceivable;
+}
+
+=pod
+
+=head2 UNSETTLED ACKNOWLEDGEMENTS
+
+The number of messages that have been acknowledged by this session whose
+acknowledgements have not been confirmed as processed by the broker.
+
+=over
+
+=item $session->get_unsettled_acks
+
+=back
+
+=cut
+sub get_unsettled_acks {
+ my ($self) = @_;
+ my $impl = $self->{_impl};
+
+ return $impl->getUnsettledAcks;
+}
+
+=pod
+
+=head2 NEXT RECEIVER
+
+The next receiver is the one, created by this session, that has any pending
+local messages.
+
+If no receivers are found within the timeout then a B<MessagingException> is
+raised.
+
+=over
+
+=item $session->get_next_receiver
+
+=item $session->get_next_receiver( timeout )
+
+=back
+
+=head3 ARGUMENTS
+
+=over
+
+=item * timeout
+
+The period of time to wait for a receiver to be found. If no period of time is
+specified then the default is to wait B<forever>.
+
+=back
+
+=cut
+sub get_next_receiver {
+ my ($self) = @_;
+ my $impl = $self->{_impl};
+
+ my $timeout = $_[1] || qpid::messaging::Duration::FOREVER;
+
+ return $impl->getNextReceiver($timeout);
+}
+
+=pod
+
+=head2 CONNECTION
+
+=over
+
+=item $conn = $session->get_connection
+
+Returns the owning connection for the session.
+
+=back
+
+=cut
sub get_connection {
my ($self) = @_;
Modified: qpid/trunk/qpid/cpp/bindings/qpid/perl/lib/qpid_messaging.pm
URL:
http://svn.apache.org/viewvc/qpid/trunk/qpid/cpp/bindings/qpid/perl/lib/qpid_messaging.pm?rev=1445948&r1=1445947&r2=1445948&view=diff
==============================================================================
--- qpid/trunk/qpid/cpp/bindings/qpid/perl/lib/qpid_messaging.pm (original)
+++ qpid/trunk/qpid/cpp/bindings/qpid/perl/lib/qpid_messaging.pm Wed Feb 13
21:49:31 2013
@@ -21,6 +21,8 @@ use strict;
use warnings;
use cqpid_perl;
+package qpid::messaging;
+
use qpid::messaging::codec;
use qpid::messaging::Address;
use qpid::messaging::Duration;
@@ -31,3 +33,63 @@ use qpid::messaging::Session;
use qpid::messaging::Connection;
1;
+
+__END__
+
+=pod
+
+=head1 NAME
+
+qpid::messaging
+
+=head1 DESCRIPTION
+
+The Qpid Messaging framework is an enterprise messaging framework
+based on the open-source AMQP protocol.
+
+=head1 EXAMPLE
+
+Here is a simple example application. It creates a link to a broker located
+on a system named C<broker.myqpiddomain.com>. It then creates a new messaging
+queue named C<qpid-examples> and publishes a message to it. It then consumes
+that same message and closes the connection.
+
+ use strict;
+ use warnings;
+
+ use qpid;
+
+ # create a connection, open it and then create a session named "session1"
+ my $conn = new qpid::messaging::Connection("broker.myqpiddomain.com");
+ $conn->open();
+ my $session = $conn->create_session("session1");
+
+ # create a sender and a receiver
+ # the sender marks the queue as one that is deleted when the sender
disconnects
+ my $send = $session->create_sender("qpid-examples;{create:always}");
+ my $recv = $session->create_receiver("qpid-examples");
+
+ # create an outgoing message and send it
+ my $outgoing = new qpid::messaging::Message();
+ $outgoing->set_content("The time is " . localtime(time)");
+ $send->send($outgoing);
+
+ # set the receiver's capacity to 10 and then check out many messages are
pending
+ $recv->set_capacity(10);
+ print "There are " . $recv->get_available . " messages waiting.\n";
+
+ # get the nextwaitingmessage, which should be in the local queue now,
+ # and output the contents
+ my $incoming = $recv->fetch();
+ print "Received the following message: " . $incoming->get_content() . "\n";
+ # the output should be the text that was sent earlier
+
+ # acknowledge the message, letting the sender know the message was received
+ printf "The sender currently has " . $send->get_unsettled . " message(s)
pending.\n";
+ # should report 1 unsettled message
+ $session->acknowledge(); # acknowledges all pending messages
+ print "Now sender currently has " . $send->get_unsettled . " message(s)
pending.\n";
+ # should report 0 unsettled messages
+
+ # close the connection
+ $conn->close
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscr...@qpid.apache.org
For additional commands, e-mail: commits-h...@qpid.apache.org
