Connector configuration

Connectors have two types of configuration properties: standard configuration properties and adapter-specific configuration properties. You must set the values of these properties before running the adapter.

You use Connector Configurator Express to configure connector properties:

A connector obtains its configuration values at startup. During a runtime session, you may want to change the values of one or more connector properties. Changes to some connector configuration properties, such as AgentTraceLevel, take effect immediately. Changes to other connector properties require component restart or system restart after a change. To determine whether a property is dynamic (taking effect immediately) or static (requiring either connector component restart or system restart), refer to the Update Method column in the Connector Properties window of Connector Configurator Express.

Standard connector properties

Standard configuration properties provide information that all connectors use. See Appendix A, Standard configuration properties for connectors for documentation of these properties.

Note:
When you set configuration properties in Connector Configurator, you specify your broker using the BrokerType property. Once this is set, the properties relevant to your broker will appear in the Connector Configurator window.

Connector-specific properties

Connector-specific configuration properties provide information needed by the connector at runtime. Connector-specific properties also provide a way of changing static information or logic within the connector without having to recode and rebuild the agent.

The table below lists the connector-specific configuration properties for the adapter. See the sections that follow for explanations of the properties.
Name Possible values Default value Required
ApplicationPassword Login password
No
ApplicationUserName Login user ID
No
ArchiveQueue Queue to which copies of successfully processed messages are sent queue://crossworlds. queuemanager/MQCONN.ARCHIVE No
CCSID Character set for queue manager connection null No
Channel MQ server connector channel
Yes
ConfigurationMetaObject Name of configuration meta-object
Yes
DataHandlerClassName Data handler class name com.crossworlds.DataHandlers. text.xml No
DataHandlerConfigMO Data handler meta-object MO_DataHandler_ Default Yes
DataHandlerMimeType MIME type of file text/xml No
DefaultVerb Any verb supported by the connector. Create
ErrorQueue Queue for unprocessed messages queue://crossworlds. queuemanager/MQCONN.ERROR No
FeedbackCodeMappingMO Feedback code meta-object
No
HostName WebSphere MQ server
Yes
InDoubtEvents FailOnStartup Reprocess IgnoreLogError Reprocess No
InputQueue Poll queues queue://crossworlds. queuemanager/MQCONN.IN No
InProgressQueue In-progress event queue queue://crossworlds. queuemanager/MQCONN.IN_PROGRESS No
PollQuantity Number of messages to retrieve from each queue specified in the InputQueue property 1 No
Port Port established for the WebSphere MQ listener
Yes
ReplyToQueue Queue to which response messages are delivered when the connector issues requests queue://crossworlds. queuemanager/MQCONN.REPLYTO No
UnsubscribedQueue Queue to which unsubscribed messages are sent queue://crossworlds. queuemanager/MQCONN.UNSUBSCRIBE No
UseDefaults true or false false

ApplicationPassword

Password used with UserID to log in to WebSphere MQ.

Default = None.

If the ApplicationPassword is left blank or removed, the connector uses the default password provided by WebSphere MQ.*

ApplicationUserName

User ID used with Password to log in to WebSphere MQ.

Default = None.

If the ApplicationUserName is left blank or removed, the connector uses the default user ID provided by WebSphere MQ.*

ArchiveQueue

Queue to which copies of successfully processed messages are sent.

Default = queue://crossworlds.queue.manager/MQCONN.ARCHIVE

CCSID

The character set for the queue manager connection. The value of this property should match that of the CCSID property in the queue URI; see Queue Uniform Resource Identifiers (URI)

Default = null.

Channel

MQ server connector channel through which the connector communicates with WebSphere MQ.

Default = none.

If the Channel is left blank or removed, the connector uses the default server channel provided by WebSphere MQ.*

ConfigurationMetaObject

Name of static meta-object containing configuration information for the connector.

Default = none.

DataHandlerClassName

Data handler class to use when converting messages to and from business objects.

Default = com.crossworlds.DataHandlers.text.xml

DataHandlerConfigMO

Meta-object passed to data handler to provide configuration information.

Default = MO_DataHandler_Default

DataHandlerMimeType

Allows you to request a data handler based on a particular MIME type.

Default = text/xml

DefaultVerb

Specifies the verb to be set within an incoming business object, if it has not been set by the data handler during polling.

Default= Create

ErrorQueue

Queue to which messages that could not be processed are sent.

Default = queue://crossworlds.queue.manager/MQCONN.ERROR

FeedbackCodeMappingMO

Allows you to override and reassign the default feedback codes used to synchronously acknowledge receipt of messages to InterChange Server Express. This property enables you to specify a meta-object in which each attribute name is understood to represent a feedback code. The corresponding value of the feedback code is the return status that is passed to InterChange Server Express. For a listing of the default feedback codes, see "Synchronous delivery".. The connector accepts the following attribute values representing WebSphere MQ-specific feedback codes:

The connector accepts the following WebSphere business integration system-specific status codes as attribute values in the meta-object:

The table below shows a sample meta-object.
Attribute name Default value
MQFB_APPL_FIRST SUCCESS
MQFB_APPL_FIRST + 1 FAIL
MQFB_APPL_FIRST + 2 UNABLE_TO_LOGIN

Default = none.

HostName

The name of the server hosting WebSphere MQ.

Default = none.

InDoubtEvents

Specifies how to handle in-progress events that are not fully processed due to unexpected connector shutdown. Choose one of four actions to take if events are found in the in-progress queue during initialization:

Default = Reprocess.

InputQueue

Message queues that will be polled by the connector for new messages. The connector accepts multiple semi-colon delimited queue names. For example, to poll the following three queues: MyQueueA, MyQueueB, and MyQueueC, the value for connector configuration property InputQueue would equal: MyQueueA;MyQueueB;MyQueueC.

If the InputQueue property is not supplied, the connector will start up properly, print a warning message, and perform request processing only. It will perform no event processing.

The connector polls the queues in a round-robin manner and retrieves up to pollQuantity number of messages from each queue. For example, if pollQuantity equals 2, and MyQueueA contains 2 messages, MyQueueB contains 1 message and MyQueueC contains 5 messages, the connector retrieves messages in the following manner:

Since we have a PollQuantity of 2, the connector will retrieve at most 2 messages from each queue per call to pollForEvents. For the first cycle (1 of 2), the connector retrieves the first message from each of MyQueueA, MyQueueB, and MyQueueC. That completes the first round of polling and if we had a PollQuantity of 1, the connector would stop. Since we have a PollQuantity of 2, the connector starts a second round of polling (2 of 2) and retrieves one message each from MyQueueA and MyQueueC--it skips MqQueueB since it is now empty. After polling all queues 2x each, the call to the method pollForEvents is complete. Here's the sequence of message retrieval:

  1. 1 message from MyQueueA
  2. 1 message from MyQueueB
  3. 1 message from MyQueueC
  4. 1 message from MyQueueA
  5. Skip MyQueueB since it's now empty
  6. 1 message from MyQueueC

Default = queue://crossworlds.queue.manager/MQCONN.IN

InProgressQueue

Message queue where messages are held during processing. You can configure the connector to operate without this queue by using System Manager to remove the default InProgressQueue name from the connector-specific properties. Doing so prompts a warning at startup that event delivery may be compromised if the connector is shut down while are events pending.

Default= queue://crossworlds.queue.manager/MQCONN.IN_PROGRESS

PollQuantity

Number of messages to retrieve from each queue specified in the InputQueue property during a pollForEvents scan.

Default =1

Port

Port established for the WebSphere MQ listener.

Default = None.

ReplyToQueue

Queue to which response messages are delivered when the connector issues requests. You can also use attributes in the child dynamic meta-object to ignore a response. For more information on the these attributes, see JMS headers, WebSphere MQ message properties, and dynamic child meta-object attributes.

Default = queue://crossworlds.queue.manager/MQCONN.REPLYTO

UnsubscribedQueue

Queue to which messages that are not subscribed are sent.

Default = queue://crossworlds.queue.manager/MQCONN.UNSUBSCRIBED

Note:
*Always check the values WebSphere MQ provides since they may be incorrect or unknown. If so, please implicitly specify values.

UseDefaults

On a Create operation, if UseDefaults is set to true, the connector checks whether a valid value or a default value is provided for each isRequired business object attribute. If a value is provided, the Create operation succeeds. If the parameter is set to false, the connector checks only for a valid value and causes the Create operation to fail if it is not provided. The default is false.

Enabling guaranteed event delivery

You can configure the guaranteed-event-delivery feature for a JMS-enabled connector in one of the following ways:

Guaranteed event delivery for connectors with JMS event stores

If the JMS-enabled connector uses JMS queues to implement its event store, the connector framework can act as a "container" and manage the JMS event store (the JMS source queue). In a single JMS transaction, the connector can remove a message from a source queue and place it on the destination queue. This section provides the following information about use of the guaranteed-event-delivery feature for a JMS-enabled connector that has a JMS event store:

Enabling the feature for connectors with JMS event stores

To enable the guaranteed-event-delivery feature for a JMS-enabled connector that has a JMS event store, set the connector configuration properties to values shown in Table 1.

Table 1. Guaranteed-event-delivery connector properties for a connector with a JMS event store
Connector property Value
DeliveryTransport
JMS
ContainerManagedEvents
JMS
PollQuantity
The number of events to processing in a single poll of the event store
SourceQueue

Name of the JMS source queue (event store) which the connector framework polls and from which it retrieves events for processing

Note:
The source queue and other JMS queues should be part of the same queue manager. If the connector's application generates events that are stored in a different queue manager, you must define a remote queue definition on the remote queue manager. WebSphere MQ can then transfer the events from the remote queue to the queue manager that the JMS-enabled connector uses for transmission to the integration broker. For information on how to configure a remote queue definition, see your IBM WebSphere MQ documentation.

In addition to configuring the connector, you must also configure the data handler that converts between the event in the JMS store and a business object. This data-handler information consists of the connector configuration properties that Table 2 summarizes.

Table 2. Data-handler properties for guaranteed event delivery
Data-handler property Value Required?
MimeType
The MIME type that the data handler handles. This MIME type identifies which data handler to call. Yes
DHClass
The full name of the Java class that implements the data handler Yes
DataHandlerConfigMOName
The name of the top-level meta-object that associates MIME types and their data handlers Optional

Note:
The data-handler configuration properties reside in the connector configuration file with the other connector configuration properties.

If you configure a connector that has a JMS event store to use guaranteed event delivery, you must set the connector properties as described in Table 1 and Table 2. To set these connector configuration properties, use the Connector Configurator tool. Connector Configurator displays the connector properties in Table 1 on its Standard Properties tab. It displays the connector properties in Table 2 on its Data Handler tab.

Note:
Connector Configurator activates the fields on its Data Handler tab only when the DeliveryTransport connector configuration property is set to JMS and ContainerManagedEvents is set to JMS.

For information on Connector Configurator, see Appendix B, Connector Configurator Express.

Effect on event polling

If a connector uses guaranteed event delivery by setting ContainedManagedEvents to JMS, it behaves slightly differently from a connector that does not use this feature. To provide container-managed events, the connector framework takes the following steps to poll the event store:

  1. Start a JMS transaction.
  2. Read a JMS message from the event store.

    The event store is implemented as a JMS source queue. The JMS message contains an event record. The name of the JMS source queue is obtained from the SourceQueue connector configuration property.

  3. Call the data handler to convert the event to a business object.

    The connector framework calls the data handler that has been configured with the properties in Table 2.

  4. When WebSphere MQ Integrator Broker is the integration broker, convert the business object to a message based on the configured wire format (XML).
  5. Send the resulting message to the JMS destination queue.
    If you are using the WebSphere InterChange Server Express integration broker, the message sent to the JMS destination queue is the business object. If you are using WebSphere MQ Integrator broker, the message sent to the JMS destination queue is an XML message (which the data handler generated).
  6. Commit the JMS transaction.

    When the JMS transaction commits, the message is written to the JMS destination queue and removed from the JMS source queue in the same transaction.

  7. Repeat step 1 through 6 in a loop. The PollQuantity connector property determines the number of repetitions in this loop.

Important:
A connector that sets the ContainerManagedEvents property is set to JMS does not call the pollForEvents() method to perform event polling. If the connector's base class includes a pollForEvents() method, this method is not invoked.

Guaranteed event delivery for connectors with non-JMS event stores

If the JMS-enabled connector uses a non-JMS solution to implement its event store (such as a JDBC event table, Email mailbox, or flat files), the connector framework can use duplicate event elimination to ensure that duplicate events do not occur. This section provides the following information about use of the guaranteed-event-delivery feature with a JMS-enabled connector that has a non-JMS event store:

Enabling the feature for connectors with non-JMS event stores

To enable the guaranteed-event-delivery feature for a JMS-enabled connector that has a non-JMS event store, you must set the connector configuration properties to values shown in Table 3.

Table 3. Guaranteed-event-delivery connector properties for a connector with a non-JMS event store
Connector property Value
DeliveryTransport
JMS
DuplicateEventElimination
true
MonitorQueue

Name of the JMS monitor queue, in which the connector framework stores the ObjectEventId of processed business objects

If you configure a connector to use guaranteed event delivery, you must set the connector properties as described in Table 3. To set these connector configuration properties, use the Connector Configurator tool. It displays these connector properties on its Standard Properties tab. For information on Connector Configurator, see Appendix B, Connector Configurator Express.

Effect on event polling

If a connector uses guaranteed event delivery by setting DuplicateEventElimination to true, it behaves slightly differently from a connector that does not use this feature. To provide the duplicate event elimination, the connector framework uses a JMS monitor queue to track a business object. The name of the JMS monitor queue is obtained from the MonitorQueue connector configuration property.

After the connector framework receives the business object from the application-specific component (through a call to gotApplEvent() in the pollForEvents() method), it must determine if the current business object (received from gotApplEvents()) represents a duplicate event. To make this determination, the connector framework retrieves the business object from the JMS monitor queue and compares its ObjectEventId with the ObjectEventId of the current business object:

For a JMS-enabled connector to support duplicate event elimination, you must make sure that the connector's pollForEvents() method includes the following steps:

Copyright IBM Corp. 1997, 2003