Creating a message collection by using Java

A message collection can be constructed by using Java™ and the MbMessageCollection class. Using a message collection is useful if messages must be grouped together for parsing, or if the message collection must be constructed to represent a particular data structure, such as a CICS® Transaction Server for z/OS® channel data structure.

About this task

A message collection is a message that consists of a Properties header and a single domain element named Collection. The Collection folder contains a number of child messages, each of which can contain a Properties folder, a number of headers (such as MQMD), and a body. A message collection can also have zero or more attributes that are name/value pairs. The name of an attribute must be unique within a message collection. A standard attribute for the message collection is an attribute called CollectionName.

The following figure shows an example of a message collection structure.

You can create a message collection by using Java, and the MbMessageCollection class, to group messages together for parsing, or create a message collection that must be constructed to represent a particular data structure, such as a CICS channel data structure.

To configure a message collection by using Java, complete the following steps:

1. Create a new message by using the following example:

   // create new message
   MbMessageCollection outMessage = new MbMessageCollection();
   MbMessageAssembly outAssembly = new MbMessageAssembly(inAssembly,
   	outMessage);

2. Create a Properties folder for the collection by using the following example:

   // create top level Properties folder and data
   MbElement omroot = outMessage.getRootElement();
   MbElement properties = omroot.createElementAsFirstChild("Properties");
   MbElement property1 = properties.createElementAsLastChild(
   	MbElement.TYPE_NAME_VALUE, "myProperty1", "propertyData1");
   MbElement property2 = properties.createElementAsLastChild(
   	MbElement.TYPE_NAME_VALUE, "myProperty2", "propertyData2");

3. Create the name value pairs by using the following example:

   // create collection attributes (name/value pairs)
   MbElement cn  = outMessage.createNameValue("CollectionName", "myCollectionName");
   MbElement nv1 = outMessage.createNameValue("NAME1", "Value1");
   MbElement nv2 = outMessage.createNameValue("NAME2", 12345);

   As with message folders, the domain element is always the last child of the message property.

4. The following example shows the procedure to create a message within the collection. Steps one, two, and three are repeated.

   public void evaluate(MbMessageAssembly inAssembly) throws MbException {
   	MbOutputTerminal out = getOutputTerminal("out");
   
   	// create new message
   	MbMessageCollection outMessage = new MbMessageCollection();
   	MbMessageAssembly outAssembly = new MbMessageAssembly(inAssembly,
   		outMessage);
   
   	// create top level Properties folder and data
   	MbElement omroot = outMessage.getRootElement();
   	MbElement properties = omroot.createElementAsFirstChild("Properties");
   	MbElement property1 = properties.createElementAsLastChild(
   		MbElement.TYPE_NAME_VALUE, "myProperty1", "propertyData1");
   	MbElement property2 = properties.createElementAsLastChild(
   		MbElement.TYPE_NAME_VALUE, "myProperty2", "propertyData2");
   
   	// create collection attributes (name/value pairs)
   	MbElement cn  = outMessage.createNameValue("CollectionName", "myCollectionName");
   	MbElement nv1 = outMessage.createNameValue("NAME1", "Value1");
   	MbElement nv2 = outMessage.createNameValue("NAME2", 12345);
   
   	// create folder 1
   	MbElement folder1 = outMessage.createFolder("folder1");
   
   	// create properties for folder 1
   	MbElement folder1properties = folder1.createElementAsFirstChild("Properties");
   	MbElement folder1property1 = folder1properties.createElementAsLastChild(
   		MbElement.TYPE_NAME_VALUE, "myFolder1Property1", "folder1propertyData1");
   	MbElement folder1property2 = folder1properties.createElementAsLastChild(
   		MbElement.TYPE_NAME_VALUE, "myFolder1Property2", "folder1propertyData2");
   
   	// create body of folder 1
   	MbElement mrm = folder1.createElementAsLastChild("MRM");
   
   	// create message domain element of folder 1
   	MbElement msg = mrm.createElementAsLastChild(MbElement.TYPE_NAME,
   		"msg", null);
   
   	// create data within the message body for folder 1
   	MbElement data = msg.createElementAsLastChild(
   		MbElement.TYPE_NAME_VALUE, "data", "myData");
   
   	// create folder 2
   	MbElement folder2 = outMessage.createFolder("Folder2");
   
   	// create properties for folder 2
   	MbElement folder2properties = folder2.createElementAsFirstChild("Properties");
   	MbElement folder2property1 = folder2properties.createElementAsLastChild(
   		MbElement.TYPE_NAME_VALUE, "myFolder2Property1", "folder2propertyData1");
   	MbElement folder2property2 = folder2properties.createElementAsLastChild(
   		MbElement.TYPE_NAME_VALUE, "myFolder2Property2", "folder2propertyData2");
   
   	// create body of folder 2
   	MbElement xmlnsc = folder2.createElementAsLastChild("XMLNSC");
   
   	// create message domain element of folder 2
   	MbElement msg2 = xmlnsc.createElementAsLastChild(
   		MbElement.TYPE_NAME, "msg2", null);
   
   	// create data within the message body for folder 2
   	MbElement data2 = msg2.createElementAsLastChild(
   		MbElement.TYPE_NAME_VALUE, "myData2", "myXMLData");
   
   	try {
   		out.propagate(outAssembly);
   	} finally {
   		// clear the outMessage even if there's an exception
   		outMessage.clearMessage();
   	}
   }

TraceOutput:  Root ( ['MQROOT' : 0xee3a90]
	(0x01000000:Name):Properties = ( ['MQPROPERTYPARSER' : 0xae4370]
		(0x03000000:NameValue):myProperty1 = 'propertyData1' (CHARACTER)
		(0x03000000:NameValue):myProperty2 = 'propertyData2' (CHARACTER)
	)
	(0x01000000:Name):Collection = ( ['COLLECTION' : 0x58d0b08]
		(0x03000000:NameValue):CollectionName = 'myCollectionName' (CHARACTER)
		(0x03000000:NameValue):NAME1          = 'Value1' (CHARACTER)
		(0x03000000:NameValue):NAME2          = 12345 (INTEGER)
		(0x01000000:Name     ):Folder1     = ( ['COLLECTIONFOLDER' : 0xee42e8]
			(0x01000000:Name ):Properties = ( ['MQPROPERTYPARSER' : 0xae39e8]
				(0x03000000:NameValue):myFolder1Property1 = 'folder1propertyData1' (CHARACTER)
				(0x03000000:NameValue):myFolder1Property2 = 'folder1propertyData2' (CHARACTER)
			)
			(0x01000021:Name+):MRM        = ( ['mrm' : 0xdce588]
				(0x01000000:Name):msg = (
					(0x03000000:NameValue):data = 'myData' (CHARACTER)
				)
			)
		)
		(0x01000000:Name     ):Folder2     = ( ['COLLECTIONFOLDER' : 0xee3d58]
			(0x01000000:Name  ):Properties = ( ['MQPROPERTYPARSER' : 0xae4cf8]
				(0x03000000:NameValue):myFolder2Property1 = 'folder2propertyData1' (CHARACTER)
				(0x03000000:NameValue):myFolder2Property2 = 'folder2propertyData2' (CHARACTER)
			)
			(0x01000000:Folder):XMLNSC     = ( ['xmlnsc' : 0xee2188]
				(0x01000000:Folder):msg2 = (
					(0x03000000:PCDataField):myData2 = 'myXMLData' (CHARACTER)
				)
			)
		)
	)
)