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_Authoritative Constant that holds the name of the environment property for specifying the authoritativeness of the service requested. No
CTX_Batchsize Constant that holds the name of the environment property for specifying the batch size to use when returning data via the service's protocol. No
CTX_DNS_URL Constant that holds the name of the environment property for specifying the DNS host and domain names to use for the JNDI URL context (for example, "dns://somehost/wiz.com"). No
CTX_InitialContextFactory Name of factory class to be used to establish an initial JNDI context. Yes
CTX_Language Constant that holds the name of the environment property for specifying the preferred language to use with the service. No
CTX_ObjectFactories Constant that holds the name of the environment property for specifying the list of object factories to use. No
CTX_ProviderURL URL identifying the JNDI context where the connection factory is located. Yes
CTX_Referral Constant that holds the name of the environment property for specifying how referrals encountered by the service provider are to be processed. No
CTX_SecurityAuthentication Constant that holds the name of the environment property for specifying the security level to use. No
CTX_SecurityCredentials Constant that holds the name of the environment property for specifying the credentials of the principal for authenticating the caller to the service. No
CTX_SecurityPrincipal Constant that holds the name of the environment property for specifying the identity of the principal for authenticating the caller to the service. No
CTX_SecurityProtocol Constant that holds the name of the environment property for specifying the security protocol to use. No
CTX_URLPackagePrefixes Constant that holds the name of the environment property for specifying the list of package prefixes to use when loading in URL context factories. No
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
DataHandlerPoolSize Maximum number of DataHandler instances to be cached for a particular type of DataHandler 30 No
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
UnsubscribeOnTerminate Specify removed topics from InputDestination. No
UseDefaults
true
or
false
false
No
UseDurableSubscriptions
true
or
false
false
No
WorkerThreadCount Maximum number of parallel threads for polling.
1
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.

Format of specifying this property is

connection_factory_name:<msg_system_type>

where connection_factory_name is mandatory and the second parameter, which takes the value of Topics or Queues (<msg_system_type>:), is optional. The second parameter tells the adapter to determine the messaging system type based on the user configuration.

For example, to specify pub/sub messaging, configure the ConnectionFactoryName as follows:

<connection_factory_name>:Topics

For point-to-point messaging, configure the ConnectionFactoryName as follows:

<connection_factory_name>:Queues

If you leave the second parameter (either Topics or Queues) blank, the adapter will attempt to identify the messaging system based on the instance of the factory object.

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.

Format of specifying this property is

connection_factory_name:<msg_system_type>

where connection_factory_name is mandatory and the second parameter, which takes the value of Topics or Queues (<msg_system_type>:), is optional. The second parameter tells the adapter to determine the messaging system type based on the user configuration.

For example, to specify pub/sub messaging, configure the ConnectionFactoryName as follows:

<connection_factory_name>:Topics

For point-to-point messaging, configure the ConnectionFactoryName as follows:

<connection_factory_name>:Queues

If you leave the second parameter (either Topics or Queues) blank, the adapter will attempt to identify the messaging system based on the instance of the factory object.

Default = none.

CTX_Authoritative

Constant that holds the name of the environment property for specifying the authoritativeness of the service requested. If the value of the property is the string "true", it means that the access the most authoritative source (i.e. bypass any cache or replicas). If the value is anything else, the source need not be (but can be) authoritative.

If unspecified, this property defaults to "false".

CTX_Batchsize

Constant that holds the name of the environment property for specifying the batch size to use when returning data via the service's protocol. This is a hint to the provider to return the results of operations in batches of the specified size, so the provider can optimize its performance and usage of resources. The value of the property is the string representation of an integer. If unspecified, the batch size is determined by the provider.

CTX_DNS_URL

Constant that holds the name of the environment property for specifying the DNS host and domain names to use for the JNDI URL context (for example, "dns://somehost/wiz.com"). If the property is not specified in the environment, the system property by the same name is used. If not specified as a system property either and the program attempts to use a JNDI URL containing a DNS name, ConfigurationException is thrown.

CTX_InitialContextFactory

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

Default = none.

CTX_Language

Constant that holds the name of the environment property for specifying the preferred language to use with the service. The value of the property is a colon-separated list of language tags defined in RFC 1766. If unspecified, the language preference is determined by the service provider.

CTX_ObjectFactories

Constant that holds the name of the environment property for specifying the list of object factories to use. The value of the property should be a colon-separated list of the fully qualified class names of factory classes that will create an object given information about the object. If the property is not specified in the environment, the system property by the same name is used. If not specified as a system property either, NamingManager.getObjectInstance() will use means to attempt to create the object.

CTX_ProviderURL

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

Default = none.

CTX_Referral

Constant that holds the name of the environment property for specifying how referrals encountered by the service provider are to be processed. The value of the property is one of the following strings:

CTX_SecurityAuthentication

Constant that holds the name of the environment property for specifying the security level to use. Its value is one of the following strings: "none", "simple", "strong". If unspecified, the behaviour is determined by the service provider.

CTX_SecurityCredentials

Constant that holds the name of the environment property for specifying the credentials of the principal for authenticating the caller to the service. The value of the property depends on the authentication scheme. For example, it could be a hashed password, clear-text password, key, certificate, and so on. If unspecified, the behaviour is determined by the service provider.

CTX_SecurityPrincipal

Constant that holds the name of the environment property for specifying the identity of the principal for authenticating the caller to the service. The value of the property depends on the authentication scheme . If unspecified, the behaviour is determined by the service provider.

CTX_SecurityProtocol

Constant that holds the name of the environment property for specifying the security protocol to use. Its value is a string determined by the service provider (e.g. "ssl"). If unspecified, the behaviour is determined by the service provider.

CTX_URLPackagePrefixes

Constant that holds the name of the environment property for specifying the list of package prefixes to use when loading in URL context factories. The value of the property should be a colon-separated list of package prefixes for the class name of the factory class that will create a URL context factory. If the property is not specified in the environment, the system property by the same name is used. The prefix com.sun.jndi.url is always added to the end of the possibly empty list of package prefixes.

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.

DataHandlerPoolSize

Set this optional property if you would like the adapter to pool previously created instances of data handlers for future use. The maximum number of DataHandler instances you would like to be cached for a particular type of DataHandler.

Default=30

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.

WorkerThreadCount

Maximum number of parallel threads for polling. While concurrently processing the events, the adapter will not be able to submit events to the broker in the order it received. If the sequence needs to be maintained WorkerThreadCount should always be set to 1.

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 Corporation 2003, 2005. All Rights Reserved.