Configuring connector properties

Connectors have two types of configuration properties that are described in the following sections:

You must set the values of these properties before running the adapter.

You use Connector Configurator to configure connector properties:

Configuring 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. Then, for a step-by-step procedure describing how to set these properties see Appendix B, Connector Configurator.

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.

Configuring connector-specific properties

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

Table 9 lists the connector-specific configuration properties for the connector. See the sections that follow for explanations of the properties.

Table 9. Connector-specific configuration properties

Name Possible values Default value Required
ArchivalConnectionFactoryName Name of object in JNDI store to retrieve and use for archiving events; supports both publishing styles-- PTP (queue-based) and Pub/Sub (topic-based).
No
ArchiveDestination Destination to which copies of successfully processed messages are sent
No
ConfigurationMetaObject Configuration meta-object
See property description
ConnectionFactoryName JMS queue or topic connection factory defined in JNDI store.
Yes
CTX_InitialContextFactory Name of factory class to be used to establish an initial JNDI context.
Yes
CTX_ProviderURL URL identifying the JNDI context where the connection factory is located.
Yes
DataHandlerClassName Name of data handler class to instantiate.
See property description
DataHandlerConfigMO Name of data handler meta-object containing configuration information for DataHandlerMimeType
MO_DataHandler_
Default
See property description
DataHandlerMimeType Mime type to use when selecting default data handler
text/delimited
See property description
DefaultVerb Specifies the verb to be set within an incoming business object Create No
EnableMessageProducerCache true or false true No
ErrorDestination Destination for unprocessed messages
No
InDoubtEvents
FailOnStartup
Reprocess
Ignore
LogError
Reprocess
No
InProgressDestination Temporary storage destination
No
InputDestination Name of poll destination(s)
No
LookupDestinationsUsingJNDI true or false
false
No
MessageFormatProperty Property name specifying message format
JMSType
No
MessageResponseResultProperty Property in response message that indicates the result of the request operation WBI_Result Yes, for synchronous processing.
PollQuantity Number of messages to retrieve from each destination specified in the InputDestination property
1
No
ReplyToDestination Destination to which response messages are delivered when the connector issues requests
Yes, for synchronous processing.
SessionPoolSizeForRequests Maximum pool size for caching the sessions used during request processing. 10 No
UnsubscribedDestination Destination to which copies of inbound messages are put if the message is unrecognized or if the business object to which it maps is not supported.
No
UnsubscribeOnTerminate Specify removed topics from InputDestination.
No
UseDefaults
true

or

false
false
No
UseDurableSubscriptions
true

or

false
false
No

ArchivalConnectionFactoryName

This property enables the connector to support event archival in either point-to-point or topic-based styles. The property names the JMS queue or topic connection factory object, defined in the JNDI store, that the connector should retrieve and use for establishing a connection to the JMS provider. This connection object is then used to create publisher references to the archive destinations. The connector properties that define archival destinations are:

If this property is undefined, the connector uses the factory specified in the ConnectionFactoryName property to create references to archival destinations.

Default = none.

ArchiveDestination

Destination to which copies of successfully processed messages are sent.

The default value is CWLD_ARCHIVE.

ConfigurationMetaObject

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

There is no default value.

ConnectionFactoryName

Name of JMS queue or topic connection factory object defined in JNDI store that the connector should retrieve and use for establishing a connection to the JMS provider. When looking up this name, the connector uses the initial JNDI context established by the CTX_InitialContextFactory and CTX_ProviderURL properties.

Default = none.

CTX_InitialContextFactory

The name of the factory class that is used to establish an initial JNDI context.

Default = none.

CTX_ProviderURL

Fully-qualified URL identifying JNDI context where the connection factor is located. This value is passed to the context factor.

Default = none.

DataHandlerClassName

Data handler class to use when converting messages to and from business objects. Specify either both DataHandlerConfigMO and DataHandlerMimeType or DataHandlerClassName only. Do not specify all three properties.

Note:
A DataHandlerClassName value in a static or dynamic meta-object takes precedence over a one specified in this connector configuration property. If you do not provide a DataHandlerClassName value in a meta-object, then the connector obtains the value from this connector-configuration property.

Default = none.

DataHandlerConfigMO

Name of meta-object that contains configuration information for the mimetype specified in the DataHandlerMimeType property. Provides configuration information for the data handler. Specify either DataHandlerConfigMO and DataHandlerMimeType or DataHandlerClassName only. Do not specify all three properties.

Note:
A DataHandlerConfigMO value in a static or dynamic meta-object takes precedence over a one specified in this connector configuration property. If you do not provide a DataHandlerConfigMO value in a meta-object, then the connector obtains the value from this connector-configuration property.

The default value is MO_DataHandler_Default.

DataHandlerMimeType

Allows you to request a data handler based on a particular MIME type. Specify either DataHandlerConfigMO and DataHandlerMimeType or DataHandlerClassName only. Do not specify all three properties.

Note:
A DataHandlerMimeType value in a static or dynamic meta-object takes precedence over a one specified in this connector configuration property. If you do not provide a DataHandlerMimeType value in a meta-object, then the connector obtains the value from this connector-configuration property.

Default = text/delimited.

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

EnableMessageProducerCache

Boolean property to specify that the adapter should enable a message producer cache for sending request messages.

Default= true

ErrorDestination

Destination to which copies of inbound messages are sent when the connector encounters errors while processing.

The default value is CWLD_ERROR.

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:

The default value is Reprocess.

Note:
You must specify a value for this property if you configure the InProgressDestination property.

InProgressDestination

Temporary destination where messages are held during processing.

Default = none.

InputDestination

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

If the InputDestination property is not supplied, the connector will not poll.

Default = none.

LookupDestinationsUsingJNDI

If this property is true, the connector will look up all JMS destination names in the JNDI store. This requires that any specified destination is defined in the JNDI store.

By default, the connector skips this step and allows the JMS provider to resolve the name to the appropriate destination at run-time.

Default = false.

MessageFormatProperty

The field in a JMS message that contains the input or output format for the message. By default, the connector checks the JMSType field of inbound messages for the message format and writes the message format to the JMSType field of outbound messages.

Default =JMSType.

MessageResponseResultProperty

Required for synchronous request processing, this property specifies the field in a response JMS message that the connector should check to determine the result of the request. This property is not used for asynchronous processing.

If the JMS header property specified by the MessageResponseResultProperty does not exist, the connector interprets the return code as VALCHANGE, passes whatever is in the response message to the data handler, and then updates the business object.

The default value is WBI_Result.

PollQuantity

Maximum umber of messages to retrieve from each destination specified in the InputDestination property during a pollForEvents cycle.

The default value is 1.

ReplyToDestination

Destination to which response messages are delivered when the connector issues requests. This is, by default, the destination that the connector uses to coordinate the exchange of request messages with the target application. Specify this property for synchronous processing only.

Default = none.

SessionPoolSizeForRequests

Maximum pool size for caching the sessions used during request processing.

Default = 10

UnsubscribedDestination

Destination to which copies of inbound messages are put if the message is unrecognized or if the business object to which it maps is not supported. If this property is defined and valid, the connector will put a copy of unsubscribed messages in this destination; otherwise, the message is discarded.

Default = none.

UnsubscribeOnTerminate

Applicable only when UserDurableSubscriptions is set to true. The use of durable subscriptions creates a problem if you remove topics from the connector configuration. The JMS provider will continue to store messages for the durable subscriptions even though the connector will never again check those subscriptions.

Whenever you remove topics from the list specified in InputDestination, specify those removed topics (delimited by semicolons) for this property value. To destroy the existing durable subscriptions, follow these steps:

  1. Move those topic names to which you no longer want to subscribe from InputDestination to UnsubscribeOnTerminate.
  2. Start and stop the connector (This destroys durable subscription).
  3. Clear any topics specified for UnsubscribeOnTerminate.

This action does not change any of the InputDestination values.

Failing to perform the above steps will not impact the connector but will cause the JMS provider to store unnecessary messages.

Default = none.

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.

Default = false.

UseDurableSubscriptions

Use this with Pub/Sub topic-style messaging only. If this property is set to true, the connector will act as a durable subscriber for applicable destinations. At the cost of higher overhead, the connector will instruct the JMS provider to store all messages for those topics to which it subscribes even while the connector is off-line. When brought back on-line, the connector will reprocess any published messages it missed.

Default = false.

Configuring message style

The adapter supports both the point-to-point (PTP) messaging and publish-and-subscribe (Pub/Sub) messaging interfaces defined by the JMS standard. The messaging style used by the adapter is determined by the type of administered object specified by the user in connector-specific property ConnectionFactoryName. See ConnectionFactoryName before proceeding with these procedures:

Configuring PTP message style

To configure an instance of the adapter in PTP message style:

  1. Open Connector Configurator.
  2. Click the Connector-Specific Properties tab.
  3. Specify a name for ConnectionFactoryName that maps to an instance of a JMS QueueConnectionFactory in your JNDI store. The adapter will work in PTP style and assume that all connector and meta-object properties identifying destinations (for example, the OutputDestination property) represent queues.

Configuring Pub/Sub style

To configure an instance of the adapter in Pub/Sub message style:

  1. Open Connector Configurator.
  2. Click the Connector-Specific Properties tab.
  3. Specify a name for ConnectionFactoryName that maps to an instance of a JMS TopicConnectionFactory in your JNDI store. The adapter will work in publish/subscribe style and assume that all connector and meta-object properties identifying destinations (for example, the OutputDestination property) represent topics.

Configuring JNDI

To establish a connection to the JMS provider, the connector needs access to a JMS connection factory. JMS defines the interface for the factory. But each individual JMS provider must supply its own implementation. Once the connector has a reference to this factory implementation, the connector can establish a connection to, and communicate with, the JMS provider without any knowledge of proprietary protocols or even the identify of the provider.

To be portable, the connector requires that the connection factory be located in a JNDI store. During implementation, the user or system administrator must create and configure a connection factory and place it in the JNDI store under a user-defined name. At run-time, the connector will establish a connection to the JNDI store, lookup the connection factory and use it to establish a connection to the JMS provider.

Some JMS providers provide their own JNDI implementations containing any connection factories or other administered JMS objects that you create; this approach makes it fairly straight-forward for you to configure the JMS adapter. For other JMS providers, users may need to install and configure an external JNDI provider, create the connection factory and make it available to the adapter. See your JNDI provider documentation for further information.

For more information on JNDI environment variables and configuration, see www.javasoft.com. For information on configuring JNDI with the MA88 Patch, see Configuring JNDI with WebSphere MQ Java client libraries.

Configuring JNDI with WebSphere MQ Java client libraries

For a tutorial that shows how to configure JNDI with WebSphere MQ Java client libraries, see Configuring for queue-based messagingand Configuring for topic-based messaging.

Copyright IBM Corp. 1997, 2004