rubywmq 0.3.0

data/examples/put_a.rb

@@ -0,0 +1,34 @@
+################################################################################
+#  Copyright 2006 J. Reid Morrison. Dimension Solutions, Inc.
+#
+#  Licensed 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.
+################################################################################
+
+#
+# Sample : put() : Put a single message to a queue
+#          Open the queue so that multiple puts can be performed
+#
+require 'wmq/wmq'
+
+WMQ::QueueManager.connect(:q_mgr_name=>'REID') do |qmgr|
+  qmgr.open_queue(:q_name=>'TEST.QUEUE', :mode=>:output) do |queue|
+
+    # First message
+    queue.put(:data => 'Hello World')
+
+    # Second message
+    #   This message will have new message and correlation id's
+    queue.put(:data => 'Hello Again')
+  end
+end
+

data/examples/put_b.rb

@@ -0,0 +1,42 @@
+################################################################################
+#  Copyright 2006 J. Reid Morrison. Dimension Solutions, Inc.
+#
+#  Licensed 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.
+################################################################################
+
+#
+# Sample : put() : Put two Messages to a queue
+#          Open the queue so that multiple puts can be performed
+#          Ensure that all messages have the same correlation id
+#
+require 'wmq/wmq'
+
+WMQ::QueueManager.connect(:q_mgr_name=>'REID') do |qmgr|
+  qmgr.open_queue(:q_name=>'TEST.QUEUE', :mode=>:output) do |queue|
+
+    message = WMQ::Message.new
+
+    # First message
+    #   Results in a WMQ generated msg_id and empty correl_id
+    message.data = 'Hello World'
+    queue.put(:message => message)
+
+    # Second message
+    #   new_msg_id will cause the second message to have a new message id
+    #   otherwise both messages will have the same message and correlation id's
+    #   This message will have the same correlation id as the first message (empty)
+    message.data = 'Hello Again'
+    p message.descriptor
+    queue.put(:message => message, :new_msg_id => true)
+  end
+end

data/examples/put_dlh.rb

@@ -0,0 +1,40 @@
+################################################################################
+#  Copyright 2006 J. Reid Morrison. Dimension Solutions, Inc.
+#
+#  Licensed 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.
+################################################################################
+
+#
+# Sample : put() : Put a message to a queue with a dead letter header
+#          Open the queue so that multiple puts can be performed
+#
+require 'wmq/wmq'
+
+WMQ::QueueManager.connect(:q_mgr_name=>'REID') do |qmgr|
+  qmgr.open_queue(:q_name=>'TEST.QUEUE', :mode=>:output) do |queue|
+    message = WMQ::Message.new
+    message.data = 'Hello World'
+    
+    message.headers = [
+     {:header_type =>:dead_letter_header,
+      :reason      => WMQ::MQRC_UNKNOWN_REMOTE_Q_MGR,
+      :dest_q_name =>'ORIGINAL_QUEUE_NAME',
+      :dest_q_mgr_name =>'BAD_Q_MGR'}
+    ]
+    
+    message.descriptor[:format] = WMQ::MQFMT_STRING
+    
+    queue.put(:message=>message)
+  end
+end
+

data/examples/put_dynamic_q.rb

@@ -0,0 +1,37 @@
+################################################################################
+#  Copyright 2006 J. Reid Morrison. Dimension Solutions, Inc.
+#
+#  Licensed 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.
+################################################################################
+
+#
+# Sample : put() : Put a single message to a queue
+#          Create the queue if it does not already exist
+#
+#   Note : The queue name is that of the model queue
+#          The dynamic_q_name is the actual queue name
+#
+#   This sample is more usefull if the model queue was a Permanent Dynamic one.
+#   That way the queue would remain after termination of this code.
+#   In this sample the queue will disappear when this program terminates
+#
+require 'wmq/wmq'
+
+WMQ::QueueManager.connect(:q_mgr_name=>'REID') do |qmgr|
+  qmgr.open_queue(:q_name => 'SYSTEM.DEFAULT.MODEL.QUEUE',
+                  :dynamic_q_name => 'TEST.QUEUE.SAMPLE',
+                  :mode  => :output
+                  ) do |queue|
+    queue.put(:data => 'Hello World')
+  end
+end

data/examples/put_rfh.rb

@@ -0,0 +1,66 @@
+################################################################################
+#  Copyright 2006 J. Reid Morrison. Dimension Solutions, Inc.
+#
+#  Licensed 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.
+################################################################################
+
+#
+# Sample : put() : Put a message to a queue with a Refernce header
+#          Open the queue so that multiple puts can be performed
+#
+require 'wmq/wmq'
+
+# The Rules Format header (MQRFH) allows a list of name value pairs to be sent along
+# with a WMQ message. These name value pairs are represented as follows on the "wire":
+#   Name1 Value1 Name2 Value2 Name3 Value3
+#   
+# Ruby WMQ converts the above string of data into a Ruby hash by
+# using the name as the key, as follows:
+# data = {
+#    'Name1' => 'Value1',
+#    'Name2' => 'Value2',
+#    'Name3' => 'Value3'
+# }
+# 
+# Since a name can consist of any character except null, it is stored as a String
+# 
+# Note: It is possible to send or receive the same Name with multiple values using an array.
+#   E.g.   Name1 Value1 Name2 Value2 Name1 Value3
+#   Becomes:
+# data = {
+#    'Name1' => ['Value1', 'Value3'],
+#    'Name2' => 'Value2'
+# }
+# 
+# Note: Since a Hash does not preserve order, reading a Rules Format Header and then writing
+#       it out immediately again could result in re-ordering of the name value pairs.
+#   
+
+WMQ::QueueManager.connect(:q_mgr_name=>'REID') do |qmgr|
+  qmgr.open_queue(:q_name=>'TEST.QUEUE', :mode=>:output) do |queue|
+    message = WMQ::Message.new
+    message.data = 'Hello World'
+    
+    message.headers = [
+     {:header_type =>:rf_header,
+      :name_value => {'name1' => 'value1', 
+                      'name2' => 'value2', 
+                      'name3' => ['value 3a', 'value 3b']} 
+     }]
+    
+    message.descriptor[:format] = WMQ::MQFMT_STRING
+    
+    queue.put(:message=>message)
+  end
+end
+

data/examples/put_rfh2_a.rb

@@ -0,0 +1,42 @@
+################################################################################
+#  Copyright 2006 J. Reid Morrison. Dimension Solutions, Inc.
+#
+#  Licensed 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.
+################################################################################
+
+#
+# Sample : put() : Put a message to a queue with a Refernce header
+#          Open the queue so that multiple puts can be performed
+#
+require 'wmq/wmq'
+
+# The Rules Format header2 (MQRFH2) allows a an XML-like string to be passed as a header
+# to the data.
+#   
+
+WMQ::QueueManager.connect(:q_mgr_name=>'REID') do |qmgr|
+  qmgr.open_queue(:q_name=>'TEST.QUEUE', :mode=>:output) do |queue|
+    message = WMQ::Message.new
+    message.data = 'Hello World'
+    
+    message.headers = [
+     {:header_type =>:rf_header_2,
+      :xml => '<hello>to the world</hello>'
+     }]
+    
+    message.descriptor[:format] = WMQ::MQFMT_STRING
+    
+    queue.put(:message=>message)
+  end
+end
+

data/examples/put_rfh2_b.rb

@@ -0,0 +1,42 @@
+################################################################################
+#  Copyright 2006 J. Reid Morrison. Dimension Solutions, Inc.
+#
+#  Licensed 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.
+################################################################################
+
+#
+# Sample : put() : Put a message to a queue with a Refernce header
+#          Open the queue so that multiple puts can be performed
+#
+require 'wmq/wmq'
+
+# The Rules Format header2 (MQRFH2) allows a an XML-like string to be passed as a header
+# to the data.
+#   
+
+WMQ::QueueManager.connect(:q_mgr_name=>'REID') do |qmgr|
+  qmgr.open_queue(:q_name=>'TEST.QUEUE', :mode=>:output) do |queue|
+    message = WMQ::Message.new
+    message.data = 'Hello World'
+    
+    message.headers = [
+     {:header_type =>:rf_header_2,
+      :xml => ['<hello>to the world</hello>', '<another>xml like string</another>'],
+     }]
+    
+    message.descriptor[:format] = WMQ::MQFMT_STRING
+    
+    queue.put(:message=>message)
+  end
+end
+

data/examples/put_xmit_q.rb

@@ -0,0 +1,32 @@
+################################################################################
+#  Copyright 2006 J. Reid Morrison. Dimension Solutions, Inc.
+#
+#  Licensed 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.
+################################################################################
+
+#
+# Sample : put() : Put a message to a queue with a Transmission header
+#
+require 'wmq/wmq'
+
+WMQ::QueueManager.connect(:q_mgr_name=>'REID') do |qmgr|
+  qmgr.open_queue(:q_name=>'TEST.QUEUE', :mode=>:output) do |queue|
+    message = WMQ::Message.new
+    message.data = "Test message from 'LOCALQMS1'"
+    message.descriptor = {:original_length=>-1, :priority=>0, :put_time=>"18510170", :msg_id=>"AMQ LOCALQMS1   E\233\001\237 \000\003\005", :expiry=>-1, :persistence=>0, :reply_to_q=>"MQMON", :correl_id=>"AMQ LOCALQMS1   E\233\001\237 \000\003\004", :feedback=>0, :offset=>0, :report=>0, :msg_flags=>0, :reply_to_q_mgr=>"LOCALQMS1", :appl_identity_data=>"", :put_appl_name=>"LOCALQMS1", :user_identifier=>"mqm", :msg_seq_number=>1, :appl_origin_data=>"", :accounting_token=>"\026\001\005\025\000\000\000\271U\305\002\261\022\362\321\021D\3206\357\003\000\000\000\000\000\000\000\000\000\000\v", :backout_count=>0, :coded_char_set_id=>437, :put_appl_type=>7, :msg_type=>8, :group_id=>"", :put_date=>"20070109", :format=>"MQSTR", :encoding=>546}
+    message.headers = [{:priority=>0, :remote_q_mgr_name=>"OTHER.QMGR", :put_time=>"18510170", :msg_id=>"AMQ LOCALQMS1   E\233\001\237 \000\003\004", :expiry=>-1, :persistence=>0, :remote_q_name=>"OTHER.Q", :header_type=>:xmit_q_header, :reply_to_q=>"MQMON", :correl_id=>"", :feedback=>0, :report=>0, :reply_to_q_mgr=>"LOCALQMS1", :appl_identity_data=>"", :put_appl_name=>"uments\\MQ\\MQMon\\mqmonntp.exe", :user_identifier=>"mqm", :appl_origin_data=>"", :accounting_token=>"\026\001\005\025\000\000\000\271U\305\002\261\022\362\321\021D\3206\357\003\000\000\000\000\000\000\000\000\000\000\v", :backout_count=>0, :coded_char_set_id=>437, :put_appl_type=>11, :msg_type=>8, :put_date=>"20070109", :encoding=>546}]
+    
+    queue.put(:message=>message)
+  end
+end
+

data/examples/request.rb

@@ -0,0 +1,59 @@
+################################################################################
+#  Copyright 2006 J. Reid Morrison. Dimension Solutions, Inc.
+#
+#  Licensed 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.
+################################################################################
+
+#
+# Sample : request.rb
+# 
+#          Sample program that demonstrates how to send a request message
+#          and then block until the response is received from the server.
+#          
+#          A temporary Dynamic Reply To Queue is used with non-persistent messaging
+#
+require 'wmq'
+
+wait_seconds = 30
+
+WMQ::QueueManager.connect(:q_mgr_name=>'REID') do |qmgr|
+  qmgr.open_queue(:q_name        => 'SYSTEM.DEFAULT.MODEL.QUEUE',
+                  :dynamic_q_name=> 'REQUEST.*',
+                  :mode          => :input
+                 ) do |reply_queue|
+                 
+    message = WMQ::Message.new()
+    message.descriptor = { :msg_type      => WMQ::MQMT_REQUEST,
+                           :reply_to_q    => reply_queue.name,
+                           :reply_to_q_mgr=> qmgr.name,
+                           :format        => WMQ::MQFMT_STRING,
+                           :expiry        => wait_seconds*10}  # Measured in tenths of a second
+    message.data = 'Hello World'        
+                  
+    # Send request message
+    qmgr.put(:q_name=>'TEST.QUEUE', :message=>message)
+    
+    # Copy outgoing Message id to correlation id
+    message.descriptor[:correl_id]=message.descriptor[:msg_id]
+
+    # Wait for reply 
+    #   Only get the message that matches the correlation id set above
+    if reply_queue.get(:wait=>wait_seconds*1000, :message=>message, :match=>WMQ::MQMO_MATCH_CORREL_ID)
+      puts "Received:"
+      puts message.data
+    else
+      # get returns false when no message received. Also: message.data = nil
+      puts "Timed Out waiting for a reply from the server"
+    end
+  end
+end

data/examples/server.rb

@@ -0,0 +1,96 @@
+################################################################################
+#  Copyright 2006 J. Reid Morrison. Dimension Solutions, Inc.
+#
+#  Licensed 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.
+################################################################################
+
+#
+# Sample : Sample program to show how to write a server side application
+#
+#     This server times out after 60 seconds, but could be modified to
+#     run forever. Example:
+#         queue.each(:wait=>-1) do |message|
+#
+#     Note: - All calls are being performed under synchpoint control to
+#             prevent messages being if the program terminates unexpectedly
+#             or an error occurrs.
+#             Uses:  :sync=>true
+#           - Queue#each will backout any message changes if an excecption is raised 
+#             but not handled within the each block
+#           
+#     A "well-behaved" WebSphere MQ application should adhere to the following rules:
+#     - Perform puts and gets under synchpoint where applicable
+#     - Only send replies to Request messages. No reply for Datagrams
+#     - Set the message type to Reply when replying to a request message
+#     - Reply with:
+#         - Remaining Expiry (Ideally deduct any processing time since get)
+#         - Same priority as received message
+#         - Same persistence as received message
+#     - Adhere to the Report options supplied for message and correlation id's 
+#         in reply message
+#     - All headers must be returned on reply messages
+#         - This allows the calling application to store state information 
+#           in these headers
+#         - Unless of course if the relevant header is input only and used
+#           for completing the request
+#             - In this case any remaining headers should be returned
+#               to the caller
+#     - If an error occurs trying to process the message, an error message
+#       must be sent back to the requesting application
+#     - If the reply fails, it must be put to the dead letter queue
+#       with the relevant dead letter header and reason
+#     
+#     Note: - It is not recommended to run server side MQ applications over a client
+#             connection.
+#           - Client connections require substantially more error handling.
+#             - E.g. Connection to queue manager can be lost due to netowk issues
+#               - Need to go into some sort of retry state attempting
+#                 to reconnect to the queue manager
+#               - What about any work that was in progress?
+#               - Need to re-open any queues
+#               - Do any changes to other resources need to be undone first?
+#                 - E.g. Database, File etc..
+#             - etc....
+#
+require 'wmq/wmq'
+
+WMQ::QueueManager.connect(:q_mgr_name=>'REID') do |qmgr|
+  qmgr.open_queue(:q_name=>'TEST.QUEUE', :mode=>:input) do |queue|
+    queue.each(:wait=>60000, :sync=>true, :convert=>true) do |request|
+      puts "Data Received:"
+      puts request.data
+      
+      begin
+        reply = WMQ::Message.new
+        reply.data = 'Echo back:'+request.data
+        
+        qmgr.put_to_reply_q(:message=>reply,
+                            :request_message=>request, # Only replies if message type is request
+                            :sync=>true)
+        
+      rescue WMQ::WMQException => exc
+        # Failed to send reply, put message to the Dead Letter Queue and add a dead letter header
+        p exc
+        puts "Failed to reply to sender, Put to dead letter queue"
+        qmgr.put_to_dead_letter_q(:message=>request, 
+                                  :reason=>WMQ::MQRC_UNKNOWN_REMOTE_Q_MGR,
+                                  :q_name=>queue.name,
+                                  :sync=>true)
+        # If it fails to put to the dead letter queue, this program will terminate and
+        # the changes will be "backed out". E.g. Queue Full, ...
+      end
+      qmgr.commit
+    end
+  end
+  puts 'No more messages found after 60 second wait interval'
+end