QPID-4587: Improve the quality of the Perl examples.

Added more detailed comments to the code, and reformatted it.

git-svn-id: https://svn.apache.org/repos/asf/qpid/trunk/qpid@1447519 13f79535-47bb-0310-9956-ffa450edef68

8 files changed, 229 insertions, 134 deletions

diff --git a/cpp/bindings/qpid/examples/perl/client.pl b/cpp/bindings/qpid/examples/perl/client.pl
index 5f9d1ff130..586beb787e 100755
--- a/cpp/bindings/qpid/examples/perl/client.pl
+++ b/cpp/bindings/qpid/examples/perl/client.pl
@@ -22,45 +22,57 @@ use warnings;
 
 use qpid;
 
-my $url = ( @ARGV == 1 ) ? $ARGV[0] : "amqp:tcp:127.0.0.1:5672";
-my $connectionOptions =  ( @ARGV > 1 ) ? $ARGV[1] : "";
+my $url               = ( @ARGV == 1 ) ? $ARGV[0] : "amqp:tcp:127.0.0.1:5672";
+my $connectionOptions = ( @ARGV > 1 )  ? $ARGV[1] : "";
 
-
-my $connection = new qpid::messaging::Connection($url, $connectionOptions);
+# creates a new connection instance
+my $connection = new qpid::messaging::Connection( $url, $connectionOptions );
 
 eval {
-$connection->open();
-my $session = $connection->create_session();
+    # open the connection and create a session for interacting with it
+    $connection->open();
 
-my $sender = $session->create_sender("service_queue");
+    my $session = $connection->create_session();
+    my $sender  = $session->create_sender("service_queue");
 
-#create temp queue & receiver...
-my $responseQueue = new qpid::messaging::Address("#response-queue; {create:always, delete:always}");
-my $receiver = $session->create_receiver($responseQueue);
+    # create an address and receiver for incoming messages
+    # the queue will be created always, and will be deleted
+    # when the receive disconnects
+    my $responseQueue = new qpid::messaging::Address(
+        "#response-queue; {create:always, delete:always}");
+    my $receiver = $session->create_receiver($responseQueue);
 
-#Now send some messages...
+    # Now send some messages...
 
-my @s = (
-      "Twas brillig, and the slithy toves",
-      "Did gire and gymble in the wabe.",
-      "All mimsy were the borogroves,",
-      "And the mome raths outgrabe."
-     );
+    my @s = (
+        "Twas brillig, and the slithy toves",
+        "Did gire and gymble in the wabe.",
+        "All mimsy were the borogroves,",
+        "And the mome raths outgrabe."
+    );
 
-my $request = new qpid::messaging::Message();
-$request->set_reply_to($responseQueue);
-for (my $i=0; $i<4; $i++) {
-    $request->set_content($s[$i]);
-    $sender->send($request);
-    my $response = $receiver->fetch();
-    print $request->get_content() . " -> " . $response->get_content() . "\n";
-}
+    # create the message object, and set a reply-to address
+    # so that the server knows where to send responses
+    # the message object will be reused to send each line
+    my $request = new qpid::messaging::Message();
+    $request->set_reply_to($responseQueue);
+    for ( my $i = 0 ; $i < 4 ; $i++ ) {
+        $request->set_content( $s[$i] );
+        $sender->send($request);
+
+        # wait for the response to the last line sent
+        # the message will be taken directly from the
+        # broker's queue rather than waiting for it
+        # to be queued locally
+        my $response = $receiver->fetch();
+        print $request->get_content() . " -> "
+          . $response->get_content() . "\n";
+    }
 
-$connection->close();
+    # close the connection
+    $connection->close();
 };
 
 if ($@) {
     die $@;
 }
-
-
diff --git a/cpp/bindings/qpid/examples/perl/drain.pl b/cpp/bindings/qpid/examples/perl/drain.pl
index 773a398442..f7a710c485 100755
--- a/cpp/bindings/qpid/examples/perl/drain.pl
+++ b/cpp/bindings/qpid/examples/perl/drain.pl
@@ -24,90 +24,114 @@ use qpid;
 use Getopt::Long;
 use Pod::Usage;
 
-my $url = "127.0.0.1";
-my $timeout = 0;
-my $forever = 0;
-my $count   = 0;
+my $url               = "127.0.0.1";
+my $timeout           = 0;
+my $forever           = 0;
+my $count             = 0;
 my $connectionOptions = "";
-my $address = "amq.direct";
+my $address           = "amq.direct";
 my $help;
 
 my $result = GetOptions(
-    "broker|b=s"           => \ $url,
-    "timeout|t=i"          => \ $timeout,
-    "forever|f"            => \ $forever,
-    "connection-options=s" => \ $connectionOptions,
-    "count|c=i"            => \ $count,
-    "help|h"               => \ $help
-    ) || pod2usage(-verbose => 0);
-
-pod2usage(-verbose => 1) if $help;
-
-if ($#ARGV ge 0) {
-    $address = $ARGV[0]
+    "broker|b=s"           => \$url,
+    "timeout|t=i"          => \$timeout,
+    "forever|f"            => \$forever,
+    "connection-options=s" => \$connectionOptions,
+    "count|c=i"            => \$count,
+    "help|h"               => \$help
+) || pod2usage( -verbose => 0 );
+
+pod2usage( -verbose => 1 ) if $help;
+
+if ( $#ARGV ge 0 ) {
+    $address = $ARGV[0];
 }
 
 sub getTimeout {
-   return ($forever) ? qpid::messaging::Duration::FOREVER : new qpid::messaging::Duration($timeout*1000);
+
+    # returns either the named duration FOREVER if the
+    # forever cmdline argument was used, otherwise creates
+    # a new Duration of the specified length
+    return ($forever)
+      ? qpid::messaging::Duration::FOREVER
+      : new qpid::messaging::Duration( $timeout * 1000 );
 }
 
 sub printProperties {
-  my $h = shift();
-  return qq[{${\(join', ',map"'$_': '$h->{$_}'",keys%$h)}}]
+    my $h = shift();
+    return qq[{${\(join', ',map"'$_': '$h->{$_}'",keys%$h)}}];
 }
 
-my $connection = new qpid::messaging::Connection($url, $connectionOptions);
+# create a connection object
+my $connection = new qpid::messaging::Connection( $url, $connectionOptions );
 
 eval {
+    # open the connection, then create a session and receiver
     $connection->open();
     my $session  = $connection->create_session();
     my $receiver = $session->create_receiver($address);
     my $timeout  = getTimeout();
-    my $message = new qpid::messaging::Message();
-    my $i = 0;
+    my $message  = new qpid::messaging::Message();
+    my $i        = 0;
 
-    for (;;) {
-        eval {
-            $message = $receiver->fetch($timeout);
-        };
+    for ( ; ; ) {
+        eval { $message = $receiver->fetch($timeout); };
 
         if ($@) {
             last;
         }
 
-        my $redelivered = ($message->get_redelivered) ? "redelivered=True, " : "";
-        print "Message(" . $redelivered . "properties=" . printProperties($message->get_properties()) . ", content='";        
-        if ($message->get_content_type() eq "amqp/map") {
+        # check if the message was on that was redelivered
+        my $redelivered =
+          ( $message->get_redelivered ) ? "redelivered=True, " : "";
+        print "Message("
+          . $redelivered
+          . "properties="
+          . printProperties( $message->get_properties() )
+          . ", content='";
+
+        # if the message content was a map, then we will print
+        # it out as a series of name => value pairs
+        if ( $message->get_content_type() eq "amqp/map" ) {
             my $content = $message->get_content();
-            map{ print "\n$_ => $content->{$_}"; } keys %{$content};
+            map { print "\n$_ => $content->{$_}"; } keys %{$content};
         }
         else {
+            # it's not a map, so just print the content as a string
             print $message->get_content();
         }
         print "')\n";
 
+        # if the message had a reply-to address, then we'll send a
+        # response back letting the send know the message was processed
         my $replyto = $message->get_reply_to();
-        if ($replyto->get_name()) {
+        if ( $replyto->get_name() ) {
             print "Replying to " . $message->get_reply_to()->str() . "...\n";
+
+            # create a temporary sender for the specified queue
             my $sender = $session->create_sender($replyto);
-            my $response = new qpid::messaging::Message("received by the server.");
+            my $response =
+              new qpid::messaging::Message("received by the server.");
             $sender->send($response);
         }
+
+        # acknowledge all messages received on this queue so far
         $session->acknowledge();
 
-        if ($count and (++$i ==$count)) {
+        if ( $count and ( ++$i == $count ) ) {
             last;
         }
     }
 
+    # close everything to clean up
     $receiver->close();
     $session->close();
     $connection->close();
 };
 
 if ($@) {
-  $connection->close();
-  die $@;
+    $connection->close();
+    die $@;
 }
 
 __END__
diff --git a/cpp/bindings/qpid/examples/perl/hello_world.pl b/cpp/bindings/qpid/examples/perl/hello_world.pl
index faf9cd3638..6ec7d52f1f 100755
--- a/cpp/bindings/qpid/examples/perl/hello_world.pl
+++ b/cpp/bindings/qpid/examples/perl/hello_world.pl
@@ -27,9 +27,11 @@ my $broker            = ( @ARGV > 0 ) ? $ARGV[0] : "localhost:5672";
 my $address           = ( @ARGV > 1 ) ? $ARGV[0] : "amq.topic";
 my $connectionOptions = ( @ARGV > 2 ) ? $ARGV[1] : "";
 
-my $connection = new qpid::messaging::Connection($broker, $connectionOptions);
+# create a connection
+my $connection = new qpid::messaging::Connection( $broker, $connectionOptions );
 
 eval {
+    # open the connection and create a session, and both a sender a receive
     $connection->open();
 
     my $session = $connection->create_session();
@@ -37,13 +39,17 @@ eval {
     my $receiver = $session->create_receiver($address);
     my $sender   = $session->create_sender($address);
 
-    $sender->send(new qpid::messaging::Message("Hello world!"));
+    # send a simple message
+    $sender->send( new qpid::messaging::Message("Hello world!") );
 
+    # receive the message, fetching it directly from the broker
     my $message = $receiver->fetch(qpid::messaging::Duration::SECOND);
 
+    # output the message content, then acknowledge it
     print $message->get_content() . "\n";
     $session->acknowledge();
 
+    # close the connection
     $connection->close();
 };
 
diff --git a/cpp/bindings/qpid/examples/perl/hello_xml.pl b/cpp/bindings/qpid/examples/perl/hello_xml.pl
index 51ccb8bd23..8d77c4b2b8 100755
--- a/cpp/bindings/qpid/examples/perl/hello_xml.pl
+++ b/cpp/bindings/qpid/examples/perl/hello_xml.pl
@@ -43,15 +43,17 @@ x-bindings: [{ exchange: xml-exchange, key: weather, arguments: { xquery:" $quer
 }}
 END
 
-
-my $connection = new qpid::messaging::Connection($broker, $connectionOptions);
+# create a connection object
+my $connection = new qpid::messaging::Connection( $broker, $connectionOptions );
 
 eval {
+    # open the connection, then create from it a session
+    # from the session, create a receiver to handle incoming messages
     $connection->open();
     my $session = $connection->create_session();
-
     my $receiver = $session->create_receiver($address);
 
+    # create a message and set its contentn
     my $message = new qpid::messaging::Message();
 
     my $content = <<END;
@@ -64,12 +66,17 @@ eval {
 END
 
     $message->set_content($content);
+
+    # create a sender for the xml-exchange/weater topic
+    # then send the message
     my $sender = $session->create_sender('xml-exchange/weather');
     $sender->send($message);
 
+    # wait for the response and then output it to the screen
     my $response = $receiver->fetch();
     print $response->get_content() . "\n";
 
+    # close the connection
     $connection->close();
 };
 
diff --git a/cpp/bindings/qpid/examples/perl/map_receiver.pl b/cpp/bindings/qpid/examples/perl/map_receiver.pl
index 8ac868eb89..a538adf380 100755
--- a/cpp/bindings/qpid/examples/perl/map_receiver.pl
+++ b/cpp/bindings/qpid/examples/perl/map_receiver.pl
@@ -23,22 +23,31 @@ use Data::Dumper;
 
 use qpid;
 
-my $url               = ( @ARGV > 0 ) ? $ARGV[0] : "amqp:tcp:127.0.0.1:5672";
-my $address           = ( @ARGV > 1 ) ? $ARGV[0] : "message_queue; {create: always}";
+my $url     = ( @ARGV > 0 ) ? $ARGV[0] : "amqp:tcp:127.0.0.1:5672";
+my $address = ( @ARGV > 1 ) ? $ARGV[0] : "message_queue; {create: always}";
 my $connectionOptions = ( @ARGV > 2 ) ? $ARGV[1] : "";
 
-my $connection = new qpid::messaging::Connection($url, $connectionOptions);
+# create a connection object
+my $connection = new qpid::messaging::Connection( $url, $connectionOptions );
 
 eval {
+    # open the connection, then create a session from it
     $connection->open();
     my $session  = $connection->create_session();
+
+    # create a receiver for the session, subscribed the the specified queue
     my $receiver = $session->create_receiver($address);
+    # wait for a message to appear in the queue
     my $message  = $receiver->fetch();
-    my $content = $message->get_content();
 
+    # display the content of the message
+    my $content  = $message->get_content();
     print Dumper($content);
 
+    # acknowledge the message, removing it from the queue
     $session->acknowledge();
+
+    # close everything, cleaning up
     $receiver->close();
     $connection->close();
 };
diff --git a/cpp/bindings/qpid/examples/perl/map_sender.pl b/cpp/bindings/qpid/examples/perl/map_sender.pl
index 3982259669..27063ef780 100755
--- a/cpp/bindings/qpid/examples/perl/map_sender.pl
+++ b/cpp/bindings/qpid/examples/perl/map_sender.pl
@@ -23,27 +23,37 @@ use Data::Dumper;
 
 use qpid;
 
-my $url               = ( @ARGV > 0 ) ? $ARGV[0] : "amqp:tcp:127.0.0.1:5672";
-my $address           = ( @ARGV > 1 ) ? $ARGV[1] : "message_queue; {create: always}";
+my $url     = ( @ARGV > 0 ) ? $ARGV[0] : "amqp:tcp:127.0.0.1:5672";
+my $address = ( @ARGV > 1 ) ? $ARGV[1] : "message_queue; {create: always}";
 my $connectionOptions = ( @ARGV > 2 ) ? $ARGV[2] : "";
 
-my $connection = new qpid::messaging::Connection($url, $connectionOptions);
+# create a new connection object
+my $connection = new qpid::messaging::Connection( $url, $connectionOptions );
 
 eval {
-    $connection->open();
 
+    # open the connection and create a session
+    $connection->open();
     my $session = $connection->create_session();
+
+    # create a sender and connect it to the supplied address string
     my $sender  = $session->create_sender($address);
 
+    # create a message and set the content to be a map of values
     my $message = new qpid::messaging::Message();
-    my $content = { id   => 987654321,
-                    name => "Widget",
-                    percent => sprintf("%.2f", 0.99),
-                    colours => [ qw (red green white) ],
-                   };
+    my $content = {
+        id      => 987654321,
+        name    => "Widget",
+        percent => sprintf( "%.2f", 0.99 ),
+        colours => [qw (red green white)],
+    };
     $message->set_content($content);
-    $sender->send($message, 1);
 
+    # send the message
+    $sender->send( $message, 1 );
+
+    # close the connection and session
+    $session->close();
     $connection->close();
 };
 
diff --git a/cpp/bindings/qpid/examples/perl/server.pl b/cpp/bindings/qpid/examples/perl/server.pl
index 7dbe7bc51c..be43655aeb 100755
--- a/cpp/bindings/qpid/examples/perl/server.pl
+++ b/cpp/bindings/qpid/examples/perl/server.pl
@@ -22,42 +22,62 @@ use warnings;
 
 use qpid;
 
-my $url = ( @ARGV == 1 ) ? $ARGV[0] : "amqp:tcp:127.0.0.1:5672";
-my $connectionOptions =  ( @ARGV > 1 ) ? $ARGV[1] : "";
+my $url               = ( @ARGV == 1 ) ? $ARGV[0] : "amqp:tcp:127.0.0.1:5672";
+my $connectionOptions = ( @ARGV > 1 )  ? $ARGV[1] : "";
 
-
-my $connection = new qpid::messaging::Connection($url, $connectionOptions);
+# create a connection object
+my $connection = new qpid::messaging::Connection( $url, $connectionOptions );
 
 eval {
+
+    # connect to the broker and create a session
     $connection->open();
     my $session = $connection->create_session();
 
+    # create a receiver for accepting incoming messages
     my $receiver = $session->create_receiver("service_queue; {create: always}");
 
+    # go into an infinite loop to receive messages and process them
     while (1) {
+
+        # wait for the next message to be processed
         my $request = $receiver->fetch();
-        my $address = $request->get_reply_to();
 
+
+        # get the address for sending replies
+        # if no address was supplised then we can't really respond, so
+        # only process when one is present
+        my $address = $request->get_reply_to();
         if ($address) {
+
+            # a temporary sender for sending to the response queue
             my $sender = $session->create_sender($address);
-            my $s = $request->get_content();
+            my $s      = $request->get_content();
             $s = uc($s);
+
+            # create the response message and send it
             my $response = new qpid::messaging::Message($s);
             $sender->send($response);
-            print "Processed request: " . $request->get_content() . " -> " . $response->get_content() . "\n";
+            print "Processed request: "
+              . $request->get_content() . " -> "
+              . $response->get_content() . "\n";
+
+            # acknowledge the message since it was processed
             $session->acknowledge();
         }
         else {
-            print "Error: no reply address specified for request: " . $request->get_content() . "\n";
+            print "Error: no reply address specified for request: "
+              . $request->get_content() . "\n";
             $session->reject($request);
         }
     }
 
-$connection->close();
+    # close connections to clean up
+    $session->close();
+    $connection->close();
 };
 
 if ($@) {
     die $@;
 }
 
-
diff --git a/cpp/bindings/qpid/examples/perl/spout.pl b/cpp/bindings/qpid/examples/perl/spout.pl
index f86f058f31..d8ac860143 100755
--- a/cpp/bindings/qpid/examples/perl/spout.pl
+++ b/cpp/bindings/qpid/examples/perl/spout.pl
@@ -25,63 +25,65 @@ use Getopt::Long;
 use Pod::Usage;
 use Time::Local;
 
-my $url = "127.0.0.1";
+my $url     = "127.0.0.1";
 my $timeout = 0;
 my $count   = 1;
 my $id      = "";
 my $replyto = "";
 my @properties;
 my @entries;
-my $content = "";
+my $content           = "";
 my $connectionOptions = "";
-my $address = "amq.direct";
+my $address           = "amq.direct";
 my $help;
 
 my $result = GetOptions(
-    "broker|b=s"           => \ $url,
-    "timeout|t=i"          => \ $timeout,
-    "count|c=i"            => \ $count,
-    "id|i=s"               => \ $id,
-    "replyto=s"            => \ $replyto,
-    "property|p=s@"        => \ @properties,
-    "map|m=s@"             => \ @entries,
-    "content=s"            => \ $content,
-    "connection-options=s" => \ $connectionOptions,
-    "help|h"               => \ $help
-    ) || pod2usage(-verbose => 0);
-
-pod2usage(-verbose => 1) if $help;
-
-if ($#ARGV ge 0) {
-    $address = $ARGV[0]
+    "broker|b=s"           => \$url,
+    "timeout|t=i"          => \$timeout,
+    "count|c=i"            => \$count,
+    "id|i=s"               => \$id,
+    "replyto=s"            => \$replyto,
+    "property|p=s@"        => \@properties,
+    "map|m=s@"             => \@entries,
+    "content=s"            => \$content,
+    "connection-options=s" => \$connectionOptions,
+    "help|h"               => \$help
+) || pod2usage( -verbose => 0 );
+
+pod2usage( -verbose => 1 ) if $help;
+
+if ( $#ARGV ge 0 ) {
+    $address = $ARGV[0];
 }
 
 sub setEntries {
     my ($content) = @_;
 
     foreach (@entries) {
-        my ($name, $value) = split("=", $_);
+        my ( $name, $value ) = split( "=", $_ );
         $content->{$name} = $value;
     }
 }
 
-
 sub setProperties {
     my ($message) = @_;
 
     foreach (@properties) {
-        my ($name, $value) = split("=", $_);
-        $message->setProperty($name, $value);
+        my ( $name, $value ) = split( "=", $_ );
+        $message->setProperty( $name, $value );
     }
 }
 
-my $connection = new qpid::messaging::Connection($url, $connectionOptions);
+# create a connection object
+my $connection = new qpid::messaging::Connection( $url, $connectionOptions );
 
 eval {
+    # open the connection, create a session and then a sender
     $connection->open();
-    my $session  = $connection->create_session();
-    my $sender = $session->create_sender($address);
+    my $session = $connection->create_session();
+    my $sender  = $session->create_sender($address);
 
+    # create a message to be sent
     my $message = new qpid::messaging::Message();
     setProperties($message) if (@properties);
     if (@entries) {
@@ -94,44 +96,49 @@ eval {
         $message->set_content_type("text/plain");
     }
 
+    # if a reply-to address was supplied, then create a receiver from the
+    # session and wait for a response to be sent
     my $receiver;
     if ($replyto) {
         my $responseQueue = new qpid::messaging::Address($replyto);
         $receiver = $session->create_receiver($responseQueue);
-        $message->setReplyTo($responseQueue);
+        $message->set_reply_to($responseQueue);
     }
 
     my $start = localtime;
-    my @s = split(/[:\s]/, $start);
-    my $s = "$s[3]$s[4]$s[5]";
-    my $n = $s;
-
-    for (my $i = 0;
-        ($i < $count || $count == 0) and
-        ($timeout == 0 || abs($n - $s) < $timeout);
-        $i++) {
+    my @s     = split( /[:\s]/, $start );
+    my $s     = "$s[3]$s[4]$s[5]";
+    my $n     = $s;
+
+    for (
+        my $i = 0 ;
+        ( $i < $count || $count == 0 )
+          and ( $timeout == 0 || abs( $n - $s ) < $timeout ) ;
+        $i++
+      )
+    {
 
         $sender->send($message);
 
         if ($receiver) {
+            print "Waiting for a response.\n";
             my $response = $receiver->fetch();
             print "$i -> " . $response->get_content() . "\n";
         }
 
         my $now = localtime;
-        my @n = split(/[:\s]/, $now);
-        my $n = "$n[3]$n[4]$n[5]";
+        my @n   = split( /[:\s]/, $now );
+        my $n   = "$n[3]$n[4]$n[5]";
     }
     $session->sync();
     $connection->close();
 };
 
 if ($@) {
-  $connection->close();
-  die $@;
+    $connection->close();
+    die $@;
 }
 
-
 __END__
 
 =head1 NAME
@@ -148,7 +155,7 @@ spout - Send messages to the specified address
   -t VALUE, --timeout VALUE    exit after the specified time
   -c VALUE, --count VALUE      stop after count messageshave been sent, zero disables
   -i VALUE, --id VALUE         use the supplied id instead of generating one
-  --reply-to VALUE             specify reply-to value
+  --replyto VALUE              specify reply-to value
   -P VALUE, --property VALUE   specify message property
   -M VALUE, --map VALUE        specify entry for map content
   --content VALUE              specify textual content