Overview of Changes
- changes were made to the C-API to add XA support.
New methods were added to the C-API to allow clients to use XA. This now allows client applications to be integrated with a third party transaction manager such as Tuxedo. This feature affects only the C-API.
- Support for using wildcards in destination names were added (including administration changes)
This feature allows destinations to be of the form <element>.<element>.<element>. Wildcards can then be used by Topic publishers or subscribers to sent to or receive from multiple destinations. For example:
Topic t = session.createTopic("stock.*.quotes"); TopicPublisher publisher = session.createPublisher(t); publisher.send (message);This functionality requires changes to the admin CLI (both arguments and output), additions to the JMX api and expands the allowed syntax for destination names. - Supoprt for automatically validating the content of XML messages
This feature validates the content of TEXT messages against an XSD located in a central location or against the DTD included in the message. Support requires changes to the admin CLI, additions to the JMX api and added a dependency on JAXP for clients that use it.
- Enhancements to the installation tool to support registration.
Service Tags support is used to register existing products with sun Before this change, MQ only supported Service tags when it was integrated with JESMF. For this release, a customer can chose to register using a Sun Online Account during installation. This change:
- Added dependencies on some new jar files.
- Adds new screens to the installer
- Adds a new "registration only" function to the installer
Specific interface Changes
- The C-API defined in WSARC-2002-714
- MQ C-API public headers and libmqcrt
- Added a new interface, the name of the xa_switch_t
- Modification of syntax used for Destination Names.
- must be compatible with Well Known Destination Names For Monitoring (WSARC-2002-714)
- Additions to the content of messages placed in the broker logs: (last modified WSARC-2006-536)
- Broker Log Format
- The administration CLI (imqcmd), last modified in WSARC-2006-536
- imqcmd CLI
- imqcmd Ouput
- Changes to the installation GUI, introduced in WSARC-2006-536
- Several jar files were added to imported interfaces for the registration functionality
- CLI of installer/uninstaller
- installer/uninstaler output
- The JMX (administration) API defined in WSARC-2004-283
- MQ MBean Attribute names
- MQ MBean Operation names
- MQ MBean Notification type names
- JAXP was added as an import for XMLValidation support.
Additional changes have been made to private protocols:
- Client/Broker Protocol (Committed Private) - last modified in WSARC-2006-536
Note:For additional detail about these changes, see the associated functional specifications.
C-API and C Client Runtime
The following modifications are being made to the MQ C-API to address XA functionality that was not implemented during the initial API design.
- New Function (Callback): MQMessageListenerBAFunc
/** * This callback is called before and after MQMessageListenerFunc call * for a XA session. The sessionHandle, consumerHandle, messageHandle * are for 'read-only' purpose only. Please do not call MQFreeMessage * for the messageHandle or MQCloseSession for the sessionHandle or * MQCloseMessageConsumer for the consumerHandle in this callback * function or any fuctions called by this callback. Restrictions in * MQMessageListenerFunc callback also applies to this callback type. * * @param sessionHandle a handle to the session * @param consumerHandle a handle to the message consumer * @param messageHandle a handle to the message * @param errorCode processing status of the current message * @param callbackData whatever void * pointer that was passed to * MQCreateAsyncMessageConsumer or MQCreateAsyncDurableMessageConsumer * @see MQCreateAsyncMessageConsumer and MQCreateAsyncDurableMessageConsumer. */ typedef MQError (*MQMessageListenerBAFunc)(const MQSessionHandle sessionHandle, const MQConsumerHandle consumerHandle, const MQMessageHandle messageHandle, MQError errorCode, void * callbackData); - New Function: MQGetXAConnection
/** * Get a XA connection * * @param connectionHandle the output parameter that contains the * newly opened connection. * @return the status of the function call. Pass this value to * MQStatusIsError to determine if the call was * successful. */ EXPORTED_SYMBOL MQStatus MQGetXAConnection(MQConnectionHandle *connectionHandle); - Modified (private) Function: MQCreateConnectionExt
A new isXA parameter was added to MQCreateConnectionExt (a private method) - New Function: MQGetConnectionProperties
/** * Get the properties of a connection * * @param connectionHandle the connection handle * @param propertiesHandle the output parameter for the properties * of this connection * @return the status of the function call. Pass this value to * MQStatusIsError to determine if the call was * successful. */ EXPORTED_SYMBOL MQStatus MQGetConnectionProperties(const MQConnectionHandle connectionHandle, MQPropertiesHandle * propertiesHandle); - New Function: MQCreateXASession
/** * Creates a new XA session on a XA connection * * For MQ_SESSION_SYNC_RECEIVE receiveMode, pass NULL for * beforeMessageListener, afterMessageListener and callbackData. * * @param connectionHandle the handle to the XA connection on which * to create a session * @param receiveMode synchronous or asynchronous message receiving * @param beforeMessageListener callback function before asynchronous message * delivery * @param afterMessageListener callback function after asynchronous message * delivery * @param callbackData data pointer to be passed to the beforeDelivery * and afterDelivery functions * @param sessionHandle the output parameter that contains the * newly created session. * @return the status of the function call. Pass this value to * MQStatusIsError to determine if the call was * successful. */ EXPORTED_SYMBOL MQStatus MQCreateXASession(const MQConnectionHandle connectionHandle, MQReceiveMode receiveMode, MQMessageListenerBAFunc beforeMessageListener, MQMessageListenerBAFunc afterMessageListener, void * callbackData, MQSessionHandle * sessionHandle); - Declared the name of the xa_switch_t structure: sun_mq_xa_switch
- New Error Codes:
- MQ_THREAD_OUTSIDE_XA_TRANSACTION
- MQ_XA_SESSION_NO_TRANSACTION
- MQ_XA_SESSION_IN_PROGRESS
- MQ_CALLBACK_RUNTIME_ERROR
- MQ_NOT_XA_CONNECTION
- MQ_ILLEGAL_CLOSE_XA_CONNECTION
Destination Name Syntax
Extends the syntax of supported destination names for topics by:
- Allows . to be used in normal (non-metric) destinations.
- Allows the use of .*. to match a single element
- Allows the use of .**. to match multiple elements
- Allows the use of > to match any number of elements
Broker Log Format
The syntax of an individual log message has not changes, and the logs have not been moved. The only changes are new error, warning and info level messages which are associated with the new features.
Administration (CLI) changes
Highlighted sections are new additions.
- imqcmd list dst
Adds two new columns, Wildcard Producers and Wildcard Consumers.
Listing all the destinations on the broker specified by: ------------------------- Host Primary Port ------------------------- localhost 7676 ------------------------------------------------------------------------------------ Name Type State Producers Consumers Msgs Total Wildcard Total Wildcard Count UnAck Avg Size ------------------------------------------------------------------------------------ mq.sys.dmq Queue RUNNING 0 - 0 - 0 0 0.0 sun.stock Topic RUNNING 1 1 2 2 0 0 0.0 Successfully listed destinations. - imqcmd query dst
Adds:
- new properties for wildcard topics:
- Number of Wildcard Producers
- List of each wildcard producers use with the number of producers using it
- Number of Wildcard Consumers
- List of each wildcard consumers use with the number of consumers using it
- new properties for wildcard topics:
- new properties for XMLValidation:
- is XML schema validation turned on
- The list of locations to search for schema
- Whether the schema should be reloaded (in case it has been updated) if a validation fails
Querying the destination where:
------------------------------------
Destination Name Destination Type
------------------------------------
sun.stock Topic
On the broker specified by:
-------------------------
Host Primary Port
-------------------------
localhost 7676
Destination Name sun.stock
Destination Type Topic
Destination State RUNNING
Created Administratively true
Current Number of Messages
Actual 45
Held in Transaction 0
Current Message Bytes
Actual 6390
Held in Transaction 0
Current Number of Producers 1
Current Number of Producer Wildcards 1
sun.* (1)
Current Number of Consumers 2
Current Number of Consumer Wildcards 2
sun.* (1)
*.stock (1)
Max Number of Messages unlimited (-1)
Max Total Message Bytes unlimited (-1)
Max Bytes per Message unlimited (-1)
Max Number of Producers 100
Limit Behavior REJECT_NEWEST
Consumer Flow Limit 1000
Is Local Destination false
Use Dead Message Queue true
XML schema validation enabled true
XML schema URI List http://foobar/EmployeeInvoice.EmployeeInvoiceInvoiced.xsd
Reload XML schema on failure false
Successfully queried the destination.
- validateXMLSchemaEnabled - have the client validate the XML either from an XSD provided to the broker or from the DTD in the XML message
- XMLSchemaURIList - a space separated list of URIs to use to locate the XSD file (if any)
- reloadXMLSchemaOnFailure - if a failure occurs when processing a message, have the client attempt to reload the XSD (in case it changed)
Installation changes
Installation changes are modifications to the MQ installer to support the optional registration of the product using a Sun Online Account username.
Installation depends on several new imported jar files:
-
sysnet-all.jar: a contract private set of interfaces which:
- create a local Service Tags registry (independent of the one used by 'stclient')
- transfer information in a local Service Tags Registry to the Global Service Tags Registry
- validate a Sun Online Account username and password combination
- create a new Sun Online Account (with specified email, password, and other information)
- send/register information in local Service Tags Registry to Sun Connection Database
- com.sun.scn.client.comm
- com.sun.scn.client.registry
- com.sun.scn.client.resources
- com.sun.scn.client.util
- com.sun.scn.dao
- com.sun.scn.servicetags
- com.sun.scn.util .
- registration-api.jar: a contract private jar which defines the registration module used by SJSAS 9.1UR1.
- registration-impl.jar: a contract private jar which is a wrapper for the classes contained in sysnet-all.jar.
- commons-codec-1.3.jar: a jar file which provides implementations of common encoders and decoders and is required to support sysnet-all.jar. It is available from http://commons.apache.org/codec/ and provides the following packages:
- org.apache.commons.codec
- org.apache.commons.codec.binary.
- org.apache.commons.codec.digest
- org.apache.commons.codec.language
- org.apache.commons.codec.net
The specific exported interface changes are:
- Changes to the XML file used by OpenInstaller when used to install MQ. The changes add the new registration screen (and changes both the GUI and the CUI)
- Addition of a new argument (-r) to run just registration.
installer -h Usage: installer [OPTION] Options: -a
Specify an answer file to be used by installer in non interactive mode. -h Show usage help -s Silent mode. No output will be displayed. -t Select Text mode instead of GUI mode. -n Dry run mode. Does not install anything. Your install responses are saved to and can be used with -a to replicate this install. -r Register product. Does not install anything. Runs the installer's product registration screens. Exit status 0 Success >0 An error occurred - New installer Screens
- Welcome Page:
- Welcome Page (registration only):
- Registration Page:
- Registration Page (GUI):
- Registration Page (CLI):
- Registration Page (GUI):
- Create a Sun Online Account:
- Registration Progress:
- Registration Progress Successful:
- Registration Progress Error:
- Registration Only Page (Summary):
- Welcome Page:
- Destination Config MBean:
Name Set/Get Type Description ValidateXMLSchemaEnabled S,G Boolean If set to true, this destination has XML schema validation enabled. If set to false, this destination does not have XML schema validation enabled.
Default is false.XMLSchemaURIList S,G String Space separated list of schema URIs to use if XML schema validation is enabled for this destination. If this property is not set or null and XML schema validation is enabled, the XML is validated via a DTD specified in the XML document. Example values:
- "http://foobar/EmployeeInvoice.EmployeeInvoiceInvoiced.xsd"
- "http://foobar/EmployeeInvoice.EmployeeInvoiceInvoiced.xsd http://test.com/xmlschema/example/newLoanApplication.xsd"
Note the space in between the 2 URIs in example (2) above.
Default is null (no value).ReloadXMLSchemaOnFailure S,G Boolean If set to true, this destination has XML schema reload on failure enabled. If set to false, this destination does not have XML schema reload on failure enabled. Default is false. - Destination Monitor MBean:
new Attributes
Name Set/Get Type Description NumWildcards G Integer Number of wildcard producers and consumers used on this destination. NumWildcardProducers G Integer Number of wildcard producers used on this destination. NumWildcardConsumers G Integer Number of wildcard consumers used on this destination. new Operations
Operation Name Return Type Parameters Description getWildcards String[] none Returns an array containing the list of all wildcard strings used by consumers and producers on this destination. getConsumerWildcards String[] none Returns an array containing the list of all wildcard strings used by consumers on this destination. getProducerWildcards String[] none Returns an array containing the list of all wildcard strings used by producers on this destination. getNumWildcardConsumers Integer wildcard - String Returns the number of consumers on the destination using the specified wildcard. getNumWildcardProducers Integer wildcard - String Returns the number of producers on the destination using the specified wildcard. - ConsumerManager Monitor MBean:
new keys for CompositeData
Key Value Type Description DestinationNames String[] Array of destination names that match wildcards used by wildcard consumers. Valid for topic consumers only. Wildcard Boolean True if this consumer is a wildcard consumer, false if not. Valid for topic consumers only. New Attributes
Name Set/Get Type Description NumWildcardConsumers G Integer Number of wildcard consumers for the broker. new Operations
Operation Name Return Type Parameters Description getConsumerWildcards String[] none Returns an array containing the list of all wildcard strings used by consumers on the broker. getNumWildcardConsumers Integer wildcard - String Returns the number of consumers using the specified wildcard on the broker. - ProducerManager Monitor MBean:
new keys for CompositeData
Key Value Type Description DestinationNames String[] Array of destination names that match wildcards used by wildcard producers. Valid for topic producers only. Wildcard Boolean True if this producer is a wildcard producer, false if not. Valid for topic producers only. New Attributes
Name Set/Get Type Description NumWildcardProducers G Integer Number of wildcard producers for the broker. New Operations
Operation Name Return Type Parameters Description getProducerWildcards String[] none Returns an array containing the list of all wildcard strings used by producers on the broker. getNumWildcardProducers Integer wildcard - String Returns the number of producers using the specified wildcard on the broker. JAXP use for XML Validation
The XML Validation processing by the client uses the JAXP implementation. If the client is using a JDK1.5 or later JDK, those classes are available as part of the JRE. For client applications using 1.4 JDK's, the jaxp package must be in the clients classpath.
Client-Broker Protocol Changes
The client-Broker protocol is a committed private API. All changes are compatible with earlier versions of the product. See the individual functional specifications for descriptions of the changes.
Compatibility
- MQ 4.2 is compatible with prior 4.X and 3.x releases. The compatibility includes API, protocol level, and administered objects.
For details see the compatibility matrix on:
http://mq.sfbay.sun.com/Wiki.jsp?page=HarrierII
Interfaces
- The following interfaces have been modified as described previously.
- No Classification changes have occurred.
- One new imported interface has been added.
- Five new imported interfaces have been added.
- No interfaces have been removed.
Exported Interfaces
Interface Classification Comments imqcmd Ouput Uncommitted Modified for both XML Validation and Wildcard Topic Support. See changes above. Client/Broker Protocol Committed Private Changes are modifications to an existing interface. See individual functional specifications. Destination Name Syntax Committed Extends existing syntax with the addition of *, **, > and . Broker Log Infomation Uncommitted adds new log messages (no format changes) imqcmd CLI Committed adds new destination attributes MQ MBean Attributes names Committed adds support for wildcard and XMLValidation operation MQ MBean Operation names Committed adds support for wildcard and XMLValidation operation MQ MBean Lookup keys for CompositeData Committed adds support for wildcard and XMLValidation operation sun_mq_xa_switch Committed New Interface.
Name of the provided xa_switch_t to be used for C-API XA supportImported Interfaces
Interface Classification Comments JAXP API Standard JDK1.5 or JAXP package if JDK 1.4 is used (https://jaxp.dev.java.net/) Interface was added in this release.
CLI of installer/uninstaller Uncommitted Arguments/options of installer script. installer/uninstaler output Uncommitted Output of installer script. install-lib Uncommitted Directory on install media that contains files needed for the registration related screens of the installer. When the installer is invoked, the following is added to CLASSPATH:
- install-lib/classes
- jar files under install-lib/registration
sysnet-all.jar Contract Private New Interface.
Code that performs the following tasks:- create a local Service Tags registry (independent of the one used by 'stclient')
- transfer information in a local Service Tags Registry to the Global Service Tags Registry
- validate a Sun Online Account username and password combination
- create a new Sun Online Account (with specified email, password, and other information)
- send/register information in local Service Tags Registry to Sun Connection Database
registration-api.jar Contract Private New Interface
Classes (interfaces, factories, and some supporting classes) that define the registration module for AppServer 9.1 UR1.registration-impl.jar Contract Private New Interface
A wrapper for sysnet-all.jar functionality.commons-codec-1.3.jar Volatile New Interface
This jar provides implementations of common encoders and decoders such as Base64 and is used by sysnet-all.jar. It comes from http://commons.apache.org/codec/Syntax of files for defining - flow/order of installer screens
- labels for screens
- splash screen image
- welcome text
- license page
Uncommitted LSARC/2007/099: Added new screens, including their labels and associated text. Purple Haze engine CLI Uncommitted LSARC/2007/095:Used new CLIs for adding install-lib directory to classpath. References
- Message Queue 4.1 (Harrier) WSARC case: http://sac.sfbay.sun.com/arc/WSARC/2006/536
Message Queue 4.2 (HarrierII) Web Site: http://mq.sfbay.sun.com/Wiki.jsp?page=HarrierII
Message Queue 4.2 (HarrierII) feature functional specifications:
Contracts: - ConsumerManager Monitor MBean: