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:
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.
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.
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 |
trueor false |
false |
No |
UseDurableSubscriptions |
trueor false |
false |
No |
WorkerThreadCount | Maximum number of parallel threads for polling. |
1 |
No |
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.
Destination to which copies of successfully processed messages are sent.
The default value is CWLD_ARCHIVE.
Name of static meta-object containing configuration information for the connector.
There is no default value.
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.
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".
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.
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.
The name of the factory class that is used to establish an initial JNDI context.
Default = none.
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.
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.
Fully-qualified URL identifying JNDI context where the connection factor is located. This value is passed to the context factor.
Default = none.
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:
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.
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.
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.
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.
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.
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.
Default = none.
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.
The default value is MO_DataHandler_Default.
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.
Default = text/delimited.
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
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
Boolean property to specify that the adapter should enable a message producer cache for sending request messages.
Default= true
Destination to which copies of inbound messages are sent when the connector encounters errors while processing.
The default value is CWLD_ERROR.
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.
Temporary destination where messages are held during processing.
Default = none.
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.
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.
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.
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.
Maximum umber of messages to retrieve from each destination specified in the InputDestination property during a pollForEvents cycle.
The default value is 1.
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.
Maximum pool size for caching the sessions used during request processing.
Default = 10
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.
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:
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.
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.
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.
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.
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:
To configure an instance of the adapter in PTP message style:
To configure an instance of the adapter in Pub/Sub message style:
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.
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.