diff options
Diffstat (limited to 'cpp/bindings/qpid/perl/lib/qpid/messaging/Receiver.pm')
-rw-r--r-- | cpp/bindings/qpid/perl/lib/qpid/messaging/Receiver.pm | 317 |
1 files changed, 317 insertions, 0 deletions
diff --git a/cpp/bindings/qpid/perl/lib/qpid/messaging/Receiver.pm b/cpp/bindings/qpid/perl/lib/qpid/messaging/Receiver.pm new file mode 100644 index 0000000000..c3bc4bb8a8 --- /dev/null +++ b/cpp/bindings/qpid/perl/lib/qpid/messaging/Receiver.pm @@ -0,0 +1,317 @@ +# +# 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. +# + +=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 { + my ($class) = @_; + my ($self) = { + _impl => $_[1], + _session => $_[2], + }; + + die "Must provide an implementation." unless defined($self->{_impl}); + die "Must provide a Session." unless defined($self->{_session}); + + bless $self, $class; + 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]; + my $impl = $self->{_impl}; + + $duration = $duration->get_implementation() if defined($duration); + + my $message = undef; + + if (defined($duration)) { + $message = $impl->get($duration); + } else { + $message = $impl->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]; + my $impl = $self->{_impl}; + my $message = undef; + + if (defined($duration)) { + $message = $impl->fetch($duration->get_implementation()); + } else { + $message = $impl->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]; + my $impl = $self->{_impl}; + + $impl->setCapacity($capacity); +} + +sub get_capacity { + my ($self) = @_; + my $impl = $self->{_impl}; + + 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}; + + 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}; + + return $impl->getUnsettled; +} + +=pod + +=over + +=item $name = $receiver->get_name + +Returns the name of the receiver. + +=back + +=cut +sub get_name { + my ($self) = @_; + my $impl = $self->{_impl}; + + 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}; + + 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; |