Using connector configuration property values

This section provides the following information about connector configuration properties:

What is a connector configuration property?

A connector configuration property (sometimes called just a connector property) allows you to create named place holders (similar to variables) that the connector can use to access information it needs. Connectors have two categories of configuration properties:

Standard connector configuration properties

Standard configuration properties provide information that is typically used by the connector framework. These properties are usually common to all connectors and usually represent well-defined behavior that is the WebSphere business integration system enforces.

Connector-specific configuration properties

Connector-specific configuration properties provide information needed by a particular connector at runtime. These configuration properties provide a way of changing static information or logic within the connector's application-specific component without having to recode and rebuild it. For example, configuration properties can be used to:

You can create any number of connector-specific configuration properties for your connector. When you have identified needed connector-specific properties, you define them as part of the connector configuration process. Use Connector Configurator to specify connector configuration properties as part of the information stored in the local repository.

You can also add configuration properties later on as needed. In general, your connector code needs only to query for the values of the connector-specific properties such as ApplicationUserID and ApplicationPassword.

Defining and setting connector configuration properties

The Connector Configurator tool provides you with the ability to perform the following tasks on connector configuration properties:

WebSphere InterChange Server

If WebSphere InterChange Server is your integration broker, refer to the Implementation Guide for WebSphere InterChange Server for information about the Connector Configurator tool.

Other integration brokers

If a WebSphere message broker (WebSphere MQ Integrator, WebSphere MQ Integrator Broker, or WebSphere Business Integration Message Broker) is your integration broker, refer the Implementation Guide for WebSphere Message Brokers for information about Connector Configurator. If WebSphere Application Server is your integration broker, refer to the Implementation Guide for WebSphere Application Server for information about Connector Configurator.

Retrieving connector configuration properties

Connector configuration properties are downloaded to the connector as part of the connector initialization (For more information, see "Starting up a connector"). Your connector application-specific component retrieves the values of any configuration properties that it needs for initialization based on the type of the connector property.

A connector can use a connector configuration property that has one of the following types:

Note:
For the IBMWebSphere Business Integration Adapters product, single-valued simple connector configuration properties are the only kind of connector properties that a C++ connector supports. C++ connectors do not support hierarchical properties.
Note:
In previous versions of the product, connector configuration properties were only single-valued and simple. That is, a connector property could contain only one string value. With this release, a Java connector can support hierarchical properties. As noted above, hierarchical properties can contain other properties and multiple values. Hierarchical properties are supported starting with version 2.2.0. For the IBM WebSphere InterChange Server product, this support starts with version 4.2.

Retrieving single-valued simple connector configuration properties

In previous versions of the product, connector configuration properties were only single-valued and simple. That is, a connector property could contain only one string value. To retrieve a single-valued simple connector configuration property, you can use the getConfigProp() method.

Note:
For the IBMWebSphere Business Integration Adapters product, single-valued simple connector configuration properties were the only kind of connector properties supported in all releases before version 2.2.0. For the IBM WebSphere InterChange Server product, single-valued simple connector configuration properties were the only kind of connector properties supported in all releases before version 4.2. For backward compatibility, the mechanism described here to access single-valued simple connector properties is still supported by a Java connector. However, IBM recommends that new connector development use the mechanism described in Retrieving hierarchical connector configuration properties to access connector configuration properties as hierarchical properties.

The Java connector library provides the two methods in Table 25 for retrieving the value of a simple connector configuration property.

Table 25. Methods for retrieving value of a simple connector configuration property

Connector library method Description
getConfigProp()
Retrieves the value of a specified simple connector configuration property
getAllConnectorAgentProperties()
Retrieves the values of all connector configuration properties. However, if the method retrieves a multiple value connector property, it only retrieves the first of the connector-property values.

These methods are both defined in the CWConnectorUtil class and function as follows:

The code fragment in Figure 26 uses the getAllConnectorAgentProperties() method to retrieve all connector configuration properties into a Java Hashtable object called connectorProperties. The code fragment then uses the get() method of the Hashtable class to retrieve the value of each connector configuration property.

Figure 26. Retrieving all Connector Configuration Properties

    connectorProperties =
         CWConnectorUtil.getAllConnectorAgentProperties();
  
     // get Connector Configuration Properties to establish Connection
     String connectString =
         (String)connectorProperties.get("ConnectString");
     String userName =
         (String)connectorProperties.get("ApplicationUserName");
     String userPassword =
         (String)connectorProperties.get("ApplicationPassword");
  
     if(connectString == null || connectString.equals("") 
             || userName==null || userPassword==null )
 

Retrieving hierarchical connector configuration properties

A hierarchical connector configuration property can contain any of the following values:

A hierarchical connector property with more than one string value is called a multi-valued property. A property with only one string value is called a single-valued property.

The Java connector library represents a hierarchical connector configuration property with the CWProperty class. An object of this class is called a connector-property object and it can represent a simple or hierarchical, single- or multi-valued connector configuration property.

Table 26 lists the metadata for a hierarchical connector configuration property that a connector-property object provides.

Table 26. Metadata in a connector-property object

Connector-property information Description CWProperty method
Name
The name of the connector property getName()
Cardinality

Indicates the number of values that the connector property contains:

  • single-valued
  • multi-valued

getCardinality()
Property type

Indicates whether the connector property contains any child properties:

  • simple : contains no child properties, only string values
  • hierarchical: contains one or more child properties

getPropType()
Encryption flag
Indicates whether the property value is to be encrypted. getEncryptionFlag() , setEncryptionFlag()

As Table 26 indicates, retrieving metadata about the connector property is done with the methods indicated. However, retrieving the property value is a two-step process, as follows:

  1. Retrieve the top-level connector-property object for one or all of the connector configuration properties.
  2. Retrieve the desired property value from a connector-property object.
Retrieving the top-level connector-property object

To retrieve the top-level connector-property object for a connector property, you can use either of the methods in Table 27..

Table 27. Methods for retrieving top-level connector-property objects

Connector library method Description

getHierarchicalConfigProp()

Retrieves the top-level connector-property object of a specified hierarchical connector configuration property

getAllConfigProperties()

Retrieves the top-level connector-properties objects for all connector configuration properties, regardless of whether the property is simple, hierarchical, or multi-valued.

The methods inTable 27 are both defined in the CWConnectorUtil class and function as follows:

Retrieving the connector-property value

Once you have retrieved the top-level connector-property object for a connector property, you can retrieve the values from this connector-property object. As discussed above, a hierarchical connector property can have one or more of the following kinds of values:

Retrieving child properties

The CWProperty class provides the methods in Table 28 to retrieve child properties from a connector-property object.

Table 28.

Methods for retrieving values child properties from a connector-property object
Description CWProperty method
To obtain all child properties of the hierarchical connector property getHierChildProps()
To obtain all child properties of the hierarchical connector property that has a specified prefix getChildPropsWithPrefix()
To obtain a single specified child property from the hierarchical connector property getHierChildProp()

You can use the hasChildren() method to determine whether the current connector-property object contains any child properties.

Retrieving string values

The CWProperty class provides the methods in Table 29 to retrieve string values from a connector-property object.

Table 29. Methods for retrieving values string values from a connector-property object

Description CWProperty method
To obtain all string values of the hierarchical connector property getStringValues()
To obtain all string values of a specified child property getChildPropValue()

You can use the hasValue() method to determine whether the current connector-property object contains any string values.

Copyright IBM Corp. 1997, 2004