Methods

The CWConnectorUtil class contains miscellaneous utility methods for use in a Java connector. These utility methods fall into the following general categories:

Table 138 summarizes the methods in the CWConnectorUtil class.

Table 138.

Member methods of the CWConnectorUtil class
Member method Description Page
CWConnectorUtil() Creates a CWConnectorUtil object. CWConnectorUtil()
boToByteArray() Calls a data handler to convert a business object to serialized data of a specified MIME type. This serialized data can be accessed through a byte array. boToByteArray()
boToStream() Calls a data handler to convert a business object to serialized data of a specified MIME type. This serialized data can be accessed through an input stream. boToStream()
boToString() Calls a data handler to convert a business object to serialized data of a specified MIME type. This serialized data can be accessed as a string. boToString()
byteArrayToBo() Calls a data handler to convert serialized data of a specified MIME type to a business object. This serialized data is accessed through a byte array. byteArrayToBo()
createAndCopyKeyVals() Creates a new business object, assigning it the specified key values and verb and default values to the remaining attributes. createAndCopyKeyVals()
createAndSetDefaults() Creates a new business object, assigning default values to all its attributes. createAndSetDefaults()
createBusObj() Creates a new business object. createBusObj()
generateAndLogMsg() Generates a message and sends it to the log destination. generateAndLogMsg()
generateAndTraceMsg() Generates a trace message and sends it to the log destination. generateAndTraceMsg()
generateMsg() Generates a message from a set of predefined messages in a message file. generateMsg()
getAllConfigProperties() Retrieves a list of all connector configuration properties, regardless of whether the property is simple, hierarchical, or multi-valued. getAllConfigProperties()
getAllConnectorAgentProperties() Retrieves a list of all connector configuration properties for the current connector. However, it retrieves them as single-valued properties. getAllConnectorAgentProperties()
getBlankValue() Retrieves the value for the special Blank attribute value. getBlankValue()
getConfigProp() Retrieves the value of a connector configuration property. getConfigProp()
getCWConnectorAPIVersion() Retrieves the version of the Java connector library. getCWConnectorAPIVersion()
getGlobalEncoding() Retrieves the character encoding that the connector framework is using. getGlobalEncoding()
getGlobalLocale() Retrieves the locale of the connector framework. getGlobalLocale()
getHierarchicalConfigProp() Retrieves the value of a hierarchical connector configuration property. getHierarchicalConfigProp()
getIgnoreValue() Retrieves the value for the special "Ignore" attribute value. getIgnoreValue()
getSupportedBONames() Retrieves a list of supported business objects for the current connector. getSupportedBONames()
getVersion() Retrieves the version of the connector. getVersion()
initAndValidateAttributes() Initializes attributes by setting them to their default values and for each attribute and then validates the attributes. initAndValidateAttributes()
isBlankValue() Determines if an attribute value is the special Blank value. isBlankValue()
isIgnoreValue() Determines if an attribute value is the special Ignore value. isIgnoreValue()
isTraceEnabled() Determines if the trace level is greater than or equal to the trace level for which it is looking, if tracing is enabled at this level. isTraceEnabled()
logMsg() Logs a message to the connector's log destination. logMsg()
readerToBO() Calls a data handler to convert serialized data of a specified MIME type to a business object. This serialized data is accessed with a Reader object. readerToBO()
streamToBO() Calls a data handler to convert serialized data of a specified MIME type to a business object. This serialized data is accessed through an input stream. streamToBO()
stringToBo() Calls a data handler to convert serialized data of a specified MIME type to a business object. This serialized data is accessed as a string. stringToBo()
traceCWConnectorAPIVersion() Traces the Java connector library version at a trace level 1. traceCWConnectorAPIVersion()
traceWrite() Writes a trace message to the log destination. traceWrite()

CWConnectorUtil()

Creates a CWConnectorUtil object.

Syntax

public CWConnectorUtil();
 

Parameters

None.

Return values

A CWConnectorUtil object.

boToByteArray()

Calls a data handler to convert a business object to serialized data of a specified MIME type. This serialized data can be accessed as a byte array.

Syntax

public static byte[] boToByteArray(CwConnectorBusObj theBusObj, String mimeType,
       String BOPrefix, String encoding, Locale locale, Object config);
 

Parameters

BOPrefix
Is the optional business-object prefix, which is combined with mimeType to form the key of the child meta-object. This argument can be used to specify a MIME subtype. It can also be used to specify a value for the BOPrefix data-handler configuration property.
config
Is an Object that contains additional configuration information for the data handler.
encoding
Specifies the character encoding for the serialized data in the byte array. If you specify null, the method uses the character encoding of the machine.
locale
Is a java.util.Locale object that specifies the locale for the serialized data in the byte array. If you specify null, the method uses the connector-framework locale.
mimeType
Is the MIME type that identifies the serialized format to which to convert the business object.
theBusObj
Is the business object to serialize to the specified MIME type and return a byte array.

Return values

A byte array that contains the serialized business object in the specified MIME type.

Exceptions

DataHandlerCreateException
Thrown when the boToByteArray() method cannot instantiate a data handler for the specified MIME type.
ParseException
Thrown when the data handler encounters some error during the conversion of the business object to the specified MIME type.
PropertyNotSetException
Thrown when the DataHandlerMetaObjectName connector configuration property is not set.

The boToByteArray() method can also throw the general Java exception NullPointerException if the data handler returns a null pointer instead of a byte array.

Notes

The boToByteArray() method provides the connector with the ability to call a data handler to perform business-object-to-string conversion. With this method, the resulting serialized data can be accessed through a Java byte array. The method identifies which data handler to invoke based on the specified mimeType argument. It instantiates a data handler whose class name is identified in the child meta-object associated with this MIME type in the the top-level meta-object, as follows:

If the data handler cannot be instantiated, boToByteArray() throws the DataHandlerCreateException. For more information on how the arguments of boToByteArray() identify which data handler to instantiate, see Identifying the data handler to instantiate.

Once instantiated, the data handler converts the specified business object to the serialized format that the MIME type indicates. If boToByteArray() specifies the encoding and locale arguments, the data handler uses the specified character encoding and locale when it creates the serialized data. The data handler returns this serialized data to the boToByteArray() method as a byte array, through which the calling method can access the returned serialized data.

Note:
If the data handler cannot convert the business object, boToByteArray() throws the ParseException exception.

You can specify a config option if you need to provide the data handler with more configuration information than is available in its meta-object. This argument can be used to specify a template file or a string to a URL for a schema that is used to build an XML document from a business object.

See also

boToStream(), boToString(), byteArrayToBo()

boToStream()

Calls a data handler to convert a business object to serialized data of a specified MIME type. This serialized data can be accessed through an input stream.

Syntax

public static InputStream boToStream(CWConnectorBusObj theBusObj, String mimeType);
 public static InputStream boToStream(CwConnectorBusObj theBusObj, String mimeType, 
       Object config);
 
public static InputStream boToStream(CwConnectorBusObj theBusObj, String mimeType, 
       String BOPrefix, String encoding, Locale locale, Object config);
 

Parameters

BOPrefix
Is the optional business-object prefix, which is combined with mimeType to form the key of the child meta-object. This argument can be used to specify a MIME subtype. It can also be used to specify a value for the BOPrefix data-handler configuration property.
config
Is an Object that contains additional configuration information for the data handler.
encoding
Specifies the character encoding for the serialized data in the input stream. If you specify null, the method uses the character encoding of the machine.
locale
Is a java.util.Locale object that specifies the locale for the serialized data in the input stream. If you specify null, the method uses the connector-framework locale.
mimeType
Is the MIME type that identifies the serialized format to which to convert the business object.
theBusObj
Is the business object to serialize tothe specified MIME type and return an input stream.

Return values

An object of the Java java.io.InputStream class (or one of its subclasses) that contains the serialized business object in the specified MIME type.

Exceptions

DataHandlerCreateException
Thrown when the boToStream() method cannot instantiate a data handler for the specified MIME type.
ParseException
Thrown when the data handler encounters some error during the conversion of the business object to the specified MIME type.
PropertyNotSetException
Thrown when the DataHandlerMetaObjectName connector configuration property is not set.

The boToStream() method can also throw the general Java exception NullPointerException if the data handler returns a null pointer instead of an InputStream object.

Notes

The boToStream() method provides the connector with the ability to call a data handler to perform business-object-to-string conversion. With this method, the resulting serialized data can be accessed through a Java input stream (based on the InputStream class). The method identifies which data handler to invoke based on the specified mimeType argument. It instantiates a data handler whose class name is identified in the child meta-object associated with this MIME type in the the top-level meta-object, as follows:

If the data handler cannot be instantiated, boToStream() throws the DataHandlerCreateException. For more information on how the arguments of boToStream() identify which data handler to instantiate, see Identifying the data handler to instantiate.

Once instantiated, the data handler converts the specified business object to the serialized format that the MIME type indicates. If boToStream() specifies the encoding and locale arguments, the data handler uses the specified character encoding and locale when it creates the serialized data. The data handler returns this serialized data to the boToStream() method as an input stream, through which the calling method can access the returned serialized data.

Note:
If the data handler cannot convert the business object, boToStream() throws the ParseException exception.

You can specify a config option if you need to provide the data handler with more configuration information than is available in its meta-object. This argument can be used to specify a template file or a string to a URL for a schema that is used to build an XML document from a business object.

See also

boToByteArray(), boToString(), streamToBO()

boToString()

Calls a data handler to convert a business object to serialized data of a specified MIME type. This serialized data can be accessed as a string.

Syntax

public static String boToString(CWConnectorBusObj theBusObj, String mimeType);
 public static String boToString(CwConnectorBusObj theBusObj, String mimeType, 
       Object config);
 
public static String boToString(CwConnectorBusObj theBusObj, String mimeType, 
       String BOPrefix, String encoding, Object config);
 

Parameters

BOPrefix
Is the business-object prefix, which is combined with mimeType to form the key of the child meta-object. This argument can be used to specify a MIME subtype. It can also be used to specify a value for the BOPrefix data-handler configuration property.
config
Is an Object that contains additional configuration information for the data handler.
encoding
Specifies the character encoding for the serialized data in the String. If you specify null, the method uses the character encoding of the machine.
locale
Is a java.util.Locale object that specifies the locale for the serialized data in the String. If you specify null, the method uses the connector-framework locale.
mimeType
Is the MIME type that identifies the serialized format to which to convert the business object.
theBusObj
Is the business object to serialize to the specified MIME type and return a string.

Return values

A String object that contains the serialized business object in the specified MIME type.

Exceptions

DataHandlerCreateException
Thrown when the boToString() method cannot instantiate a data handler for the specified MIME type.
ParseException
Thrown when the data handler encounters some error during the conversion of the business object to the specified MIME type.
PropertyNotSetException
Thrown when the DataHandlerMetaObjectName connector configuration property is not set.

The boToString() method can also throw the general Java exception NullPointerException if the data handler returns a null pointer instead of a String object.

Notes

The boToString() method provides the connector with the ability to call a data handler to perform business-object-to-string conversion. With this method, the resulting serialized data can be accessed through a Java String. The method identifies which data handler to invoke based on the specified mimeType argument. It instantiates a data handler whose class name is identified in the child meta-object associated with this MIME type in the the top-level meta-object, as follows:

If the data handler cannot be instantiated, boToString() throws the DataHandlerCreateException. For more information on how the arguments of boToString() identify which data handler to instantiate, see Identifying the data handler to instantiate.

Once instantiated, the data handler converts the specified business object to the serialized format that the MIME type indicates. If boToString() specifies the encoding and locale arguments, the data handler uses the specified character encoding and locale when it creates the serialized data. The data handler returns this serialized data to the boToString() method as a String object, through which the calling method can access the returned serialized data.

Note:
If the data handler cannot convert the business object, boToString() throws the ParseException exception.

You can specify a config option if you need to provide the data handler with more configuration information than is available in its meta-object. This argument can be used to specify a template file or a string to a URL for a schema that is used to build an XML document from a business object.

See also

boToByteArray(), boToStream(), stringToBo()

byteArrayToBo()

Calls a data handler to convert serialized data of a specified MIME type to a business object. This serialized data is accessed as a byte array.

Syntax

public static CWConnectorBusObj byteArrayToBo(CWConnectorBusObj theBusObj,
       byte[] serializedData, String mimeType, String BOPrefix, 
       String encoding, Locale locale, Object config);
 

Parameters

BOPrefix
Is the business-object prefix, which is combined with mimeType to form the key of the child meta-object. This argument can be used to specify a MIME subtype. It can also be used to specify a value for the BOPrefix data-handler configuration property.
config
Is an Object that contains additional configuration information for the data handler.
encoding
Specifies the character encoding for the serialized data in the byte array. If you specify null, the method uses the character encoding of the machine.
locale
Is a java.util.Locale object that specifies the locale for the serialized data in the byte array. If you specify null, the method uses the connector-framework locale.
mimeType
Is the MIME type that identifies the format of the serialized data.
serializedData
Is a byte array that contains the serialized data to convert to a business object.
theBusObj
Identifies the type of business object (business object definition) to which the method converts the serialized data.

Return values

A CWConnectorBusObj object that contains the business object for the serialized data.

Exceptions

DataHandlerCreateException
Thrown when the byteArrayToBo() method cannot instantiate a data handler for the specified MIME type.
ParseException
Thrown when the data handler encounters some error during the conversion of the serialized data to the specified business object.
PropertyNotSetException
Thrown when the DataHandlerMetaObjectName connector configuration property is not set.

The byteArrayToBo() method can also throw the general Java exception NullPointerException if the data handler returns a null pointer instead of a business object.

Notes

The byteArrayToBo() method provides the connector with the ability to call a data handler to perform string-to-business-object conversion. With this method, the incoming serializedData is accessed through a Java byte array. The method identifies which data handler to invoke based on the specified mimeType argument. It instantiates a data handler whose class name is identified in the child meta-object associated with this MIME type in the the top-level meta-object, as follows:

If the data handler cannot be instantiated, byteArrayToBo() throws the DataHandlerCreateException. For more information on how the arguments of byteArrayToBo() identify which data handler to instantiate, see Identifying the data handler to instantiate.

Once instantiated, the data handler converts the specified serialized data to a business object of the type that theBusObj indicates. If byteArrayToBo() specifies the encoding and locale arguments, the data handler uses the specified character encoding and locale when it interprets the serialized data. The data handler returns this business object to the byteArrayToBo() method, which in turn returns it to the calling method.

Note:
If the data handler cannot convert the serialized data, byteArrayToBo() throws the ParseException exception.

You can specify a config option if you need to provide the data handler with more configuration information than is available in its meta-object. This argument can be used to specify a template file or a string to a URL for a schema that is used to build an XML document from a business object.

See also

boToByteArray(), readerToBO(), streamToBO(), stringToBo()

createAndCopyKeyVals()

Creates a new business object, assigning it the specified key values and verb and default values to the remaining attributes.

Syntax

public static CWConnectorBusObj createAndCopyKeyVals(String busObjName, 
         String keyVals, String verb, String delimiter)
 

Parameters

busObjName
Is the name of the business object to create.
keyVals
Is the key-value string, which is an ordered list of primary-key values separated by the delimiter.
verb
Is the verb to assign to the new business object.
delimiter
Is the key delimiter.

Return values

A CWConnectorBusObj object containing the newly created business object.

Exceptions

SpecNameNotFoundException
Thrown when the business object definition is not found for the name specified.
AttributeNotFoundException
Thrown when an attribute cannot be found.
AttributeValueException
Thrown when an attribute is set to an invalid value.
WrongAttributeException
Thrown when the attribute's value does not match its data type.
InvalidVerbException
Thrown when the verb value is invalid.

Notes

The createAndCopyKeyVals() method performs the following tasks:

This method is useful in the pollForEvents() method to build the business objedt that is to be sent to the integration broker for further processing.

createAndSetDefaults()

Creates a new business object, assigning default values to all its attributes.

Syntax

public static CWConnectorBusObj createAndSetDefaults(
    String busObjName)
 

Parameters

busObjName
Is the name of the business object to create.

Return values

A CWConnectorBusObj object containing the newly created business object.

Exceptions

SpecNameNotFoundException
Thrown when the business object definition is not found for the name specified.
AttributeNotFoundException
Thrown when one of the business object's attributes (as defined by the business object definition) cannot be found.

Notes

The createAndSetDefaults() method performs the following tasks:

createBusObj()

Creates a new business object.

Syntax

public static final CWConnectorBusObj createBusObj(String busObjName);
 
public static final CWConnectorBusObj createBusObj(String busObjName, 
     Locale localeObject);
 
public static final CWConnectorBusObj createBusObj(String busObjName, 
     String localeName);
 

Parameters

busObjName
Specifies the name of the business object to create.
localeObject
Is the Java Locale object that identifies the locale to associate with the business object.
localeName
Is the name of the locale to associate with the business object.

Return values

A CWConnectorBusObj object containing the newly created business object.

Exceptions

SpecNameNotFoundException
Thrown when the business object definition is not found for the name specified.

Notes

The createBusObj() method creates a new business object instance whose type is the business object definition you specify in busObjName. If you specify a localeObject or localeName, this business-object locale applies to the data in the business object, not to the name of the business object definition or its attributes (which must be characters in the code set associated with the U.S. English locale, en_US). For a description of the format for localeName, see "Design Considerations for an Internationalized Connector," on page 54.

See also

getLocale()

generateAndLogMsg()

Generates a message and sends it to the log destination.

Syntax

public static void generateAndLogMsg(int msgNum, int msgType, int isGlobal);
  
 public static void generateAndLogMsg(int msgNum, int msgType, int isGlobal,
       msgParameters);
 

Parameters

isGlobal
Is the CONNECTOR_MESSAGE_FILE message-file constant defined in the CWConnectorUtil class to indicate that the message file is the connector message file.
msgNum
Specifies the message number (identifier) in the message file.
msgParameters
Is an optional list of String parameter values, each corresponding to a parameter in the message list, for a maximum of ten parameters.
msgType
Is one of the following message-type constants defined in the CWConnectorLogAndTrace class to identify the message severity:
                        
 
 CWConnectorLogAndTrace.XRD_WARNING 
                         
 
 CWConnectorLogAndTrace.XRD_ERROR 
                         
 
 CWConnectorLogAndTrace.XRD_FATAL 
                         
 
 CWConnectorLogAndTrace.XRD_INFO 
                         
 
 CWConnectorLogAndTrace.XRD_TRACE 
 

Return values

None.

Exceptions

None.

Notes

The generateAndLogMsg() method combines the message generating and logging functionality of generateMsg() and logMsg(), respectively. It generates a message from a message file and then sends it to the log destination. You establish the name of a connector's log destination through the Logging section in the Trace/Log File tab of Connector Configurator.

The method can take in variable number of string arguments. It supports up to a total of ten parameter values. That is, you can provide up to ten String values as arguments to generateAndLogMsg(). The following call provides values for seven parameters in error message 3223, which is defined in the connector message file:

generateAndLogMsg(3223, CWConnectorLogAndTrace:XRD_ERROR, 
      CWConnectorUtil.CONNECTOR_MESSAGE_FILE,    
      value1, value2, value3, value4, value5, value6, value7);
 
WebSphere InterChange Server

If severity is XRD_ERROR or XRD_FATAL and the connector configuration property LogAtInterchangeEnd is set, the error message is logged and an email notification is sent when email notification is on. See the System Administration Guide in the IBM WebSphere InterChange Server documentation set for information on how to set up email notification for errors.

IBM recommends that log messages be contained in a message file and extracted with the generateAndLogMsg() method. This message file should be the connector message file, which contains messages specific to your connector.

Connector messages logged with generateAndLogMsg() are viewable using LogViewer.

See also

generateAndTraceMsg(),, generateMsg(),, logMsg()

generateAndTraceMsg()

Generates a trace message and sends it to the trace destination.

Syntax

public static void generateAndTraceMsg(int traceLevel, int msgNum, 
     int isGlobal);
  
 public static void generateAndTraceMsg(int traceLevel, int msgNum, 
     int isGlobal, msgParameters);
 

Parameters

isGlobal
Is the CONNECTOR_MESSAGE_FILE message-file constant defined in the CWConnectorUtil class to indicate that the message file is the connector message file.
msgNum
Specifies the message number (identifier) in the message file.
msgParameters
Is an optional list of String parameter values, each corresponding to a parameter in the message list, with a maximum of ten parameters.
traceLevel
Is one of the following trace-level constants defined in the CWConnectorLogAndTrace class to identify the trace level used to determine which trace messages are output:
                        
 
 CWConnectorLogAndTrace.LEVEL1
                         
 
 CWConnectorLogAndTrace.LEVEL2
                         
 
 CWConnectorLogAndTrace.LEVEL3
                         
 
 CWConnectorLogAndTrace.LEVEL4
                         
 
 CWConnectorLogAndTrace.LEVEL5
 

The method writes the trace message when the current trace level is greater than or equal to traceLevel.

Note:
Do not specify a trace level of zero (LEVEL0) with a tracing message. A trace level of zero indicates that tracing is turned off. Therefore, any trace message associated with a traceLevel of LEVEL0 will never print.

Return values

None.

Exceptions

None.

Notes

The generateAndTraceMsg() method combines the message generating and tracing functionality of generateMsg() and traceWrite(), respectively. It generates a message from a message file and then sends it to the trace destination. You establish the name of a connector's trace destination through the Tracing section in the Trace/Log File tab of Connector Configurator.

The method can take in variable number of string arguments. It supports up to a total of ten parameter values. That is, you can provide up to ten String values as arguments in the msgParameters parameter of generateAndTraceMsg(). The following call provides values for seven parameters in trace message 668, which is defined in the connector message file:

generateAndTraceMsg(CWConnectorLogAndTrace.LEVEL3, 668,
         CWConnectorUtil.CONNECTOR_MESSAGE_FILE,
         value1, value2, value3, value4, value5, value6, value7);
 

Because trace messages are usually needed only during debugging, whether trace messages are contained in a message file is left at the discretion of the developer:

Connector messages logged with generateAndTraceMsg() are not viewable using LogViewer.

See also

generateAndLogMsg(),, generateMsg(),, traceWrite()

generateMsg()

Generates a message from a set of predefined messages in a message file.

Syntax

public final static String generateMsg(int traceLevel, int msgNum, 
     int msgType, int isGlobal, int argCount, 
     Vector msgParams);
  
 public final static String generateMsg(int msgNum, int msgType, 
     int isGlobal, int argCount, Vector msgParams);
 

Parameters

traceLevel
Is one of the following trace-level constants defined in the CWConnectorLogAndTrace class to specify the trace level at which to generate the message:
                        
 
 CWConnectorLogAndTrace.LEVEL1 
                         
 
 CWConnectorLogAndTrace.LEVEL2 
                         
 
 CWConnectorLogAndTrace.LEVEL3 
                         
 
 CWConnectorLogAndTrace.LEVEL4 
                         
 
 CWConnectorLogAndTrace.LEVEL5 
 

When this parameter is omitted, the method generates the message regardless of the trace level. The message is generated only if the traceLevel value is equal to or less than the current trace level of the connector.

msgNum
Specifies the message number (identifier) in the message file.
msgType
Is one of the following message-type constants defined in the CWConnectorLogAndTrace class to identify the message:
                        
 
 CWConnectorLogAndTrace.XRD_WARNING 
                         
 
 CWConnectorLogAndTrace.XRD_ERROR 
                         
 
 CWConnectorLogAndTrace.XRD_FATAL 
                         
 
 CWConnectorLogAndTrace.XRD_INFO 
                         
 
 CWConnectorLogAndTrace.XRD_TRACE 
 
isGlobal
Is the CONNECTOR_MESSAGE_FILE message-file constant defined in the CWConnectorUtil class to indicate that the message file is the connector message file.
argCount
Is an integer that specifies the number of parameters within the message text. To determine the number, refer to the message in the message file.
msgParams
Is a list of parameters for the message text.

Return values

A String containing the generated message. For the first form of the method, the method returns null if the trace level is greater than the trace level of the connector.

Exceptions

None.

Notes

The generateMsg() method provides two forms:

See also

generateAndLogMsg(),, generateAndTraceMsg(),, logMsg(),, traceWrite()

getAllConfigProperties()

Retrieves a list of all configuration properties, as hierarchical connector properties, for the current connector.

Syntax

public static CWProperty[] getAllConfigProperties();
 

Parameters

None.

Return values

A reference to an array of CWProperty objects, each of which contains one connector property for the current connector.

Exceptions

None.

Notes

The getAllConfigProperties() method retrieves the connector configuration properties as an array of CWProperty objects. Each connector-property (CWProperty) object contains a single connector property and can hold a single value, another property, or a combination of values and child properties. Use methods of the CWProperty class (such as getHierChildProps() and getStringValues()) to obtain the values from a connector-property object.

See also

getConfigProp(),, getAllConnectorAgentProperties()

getAllConnectorAgentProperties()

Retrieves a list of all configuration properties for the current connector.

Syntax

public static Hashtable getAllConnectorAgentProperties();
 

Parameters

None.

Return values

A reference to a java.util.Hashtable object that contains the connector properties for the current connector.

Exceptions

None.

Notes

The getAllConnectorAgentProperties() method retrieves the connector configuration properties as a Java Hashtable object, which maps keys to values. The keys are the names of the properties and values are the associated property values. Use methods of the Hashtable class (such as keys() and elements()) to obtain the information from this structure.

Note:
This method does not retrieve hierarchical or multi-valued properties. If it attempts to retrieve a multi-valued property, it returns only the first of the values. To retrieve hierarchical or multi-valued properties, use the getAllConfigProperties() method.

Examples

Hashtable ht = new Hastable();
 ht = CWConnectorUtil.getAllConnectorAgentProperties();
 int size = ht.size();
 Enumeration properties = ht.keys();
 Enumeration values = ht.elements();
  
 while (properties.hasMoreElements()) {
     System.out.print((String)properties.nextElement());
     System.out.print("=");
     System.out.println((String)values.nextElement());
     System.out.println("Property set");
 }
 

See also

getConfigProp(),, getAllConfigProperties()

getBlankValue()

Retrieves the value for the special Blank attribute value.

Syntax

public static String getBlankValue();
 

Return values

A String object containing the Blank attribute value.

Notes

The Blank value, which getBlankValue() retrieves, is a special attribute value that represents a "null" or zero-length value. Although the Java connector library does provide the CWConnectorAttrType.CxBlank constant for the Blank attribute value, it is recommended that you use the getBlankValue() method to obtain the Blank value when you want to assign it to an attribute.

See also

getIgnoreValue()

getConfigProp()

Retrieves the value of a connector configuration property.

Syntax

public final static String getConfigProp(String propName);
 

Parameters

propName
Is the name of the property to retrieve.

Return values

A String object containing the property value. If the property name is not found, the method returns null.

Exceptions

None.

Notes

Values of connector configuration properties are downloaded to the connector during its initialization.

When you call getConfigProp("ConnectorName") in a parallel-process connector (one that has the ParallelProcessDegree connector property set to a value greater than 1), the method always returns the name of the connector-agent master process, regardless of whether it is called in the master process or a slave process.

See also

getAllConnectorAgentProperties(),, getHierarchicalConfigProp()

getCWConnectorAPIVersion()

Retrieves the version of the Java connector library.

Syntax

public static String getCWConnectorAPIVersion()
 

Parameters

None.

Return values

A String that contains the version of the Java connector library.

Exceptions

None.

Notes

The getCWConnectorAPIVersion() method retrieves the Java connector library version from the manifest file in the package. A manifest file is a standard Java file that stores version information for a product.

See also

traceCWConnectorAPIVersion()

getGlobalEncoding()

Retrieves the character encoding that the connector framework is using.

Syntax

public String getGlobalEncoding();
 

Parameters

None.

Return values

A String object containing the connector framework's character encoding.

Exceptions

None.

Notes

The getGlobalEncoding() method retrieves the connector framework's character encoding, which is part of the locale. The locale specifies cultural conventions for data according to language, country (or territory), and a character encoding. The connector framework's character encoding should indicate the character encoding of the connector application. The connector framework's character encoding using the following hierarchy:

This method is useful when the connector needs to perform character-encoding processing, such as character conversion.

See also

getGlobalLocale()

getGlobalLocale()

Retrieves the locale of the connector framework.

Syntax

public static String getGlobalLocale();
 

Parameters

None.

Return values

A String object containing the connector framework's locale setting.

Exceptions

None.

Notes

The getGlobalLocale() method retrieves the connector framework's locale, which defines cultural conventions for data according to language, country (or territory), and a character encoding. The connector framework's locale should indicate the locale of the connector application. The connector framework's locale is set using the following hierarchy:

This method is useful when the connector needs to perform locale-sensitive processing.

See also

createBusObj(),, getGlobalEncoding(),, getLocale()

getHierarchicalConfigProp()

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

Syntax

public static CWProperty getHierarchicalConfigProp(String propName);
 

Parameters

propName
Is the name of the hierarchical connector property to retrieve.

Return values

A CWProperty object that contains the top-level connector-property object for the specified hierarchical connector property.

Exceptions

WrongPropertyException
Thrown if the specified connector-property name does not exist for this connector or it is not a hierarchical connector property.

Notes

The getHierarchicalConfigProp() method obtains the top-level connector-property (CWProperty) object. From this retrieved object, you can use methods of the CWProperty class to obtain the desired values of the connector property.

Note:
Values of connector configuration properties are downloaded to the connector during its initialization. If you specify a propName for a connector property that has not been downloaded, getHierarchicalConfigProp() throws the WrongPropertyException exception.

When you call getHierarchicalConfigProp("ConnectorName") in a parallel-process connector (one that has the ParallelProcessDegree connector property set to a value greater than 1), the method always returns the name of the connector-agent master process, regardless of whether it is called in the master process or a slave process.

See also

getAllConfigProperties(),, getConfigProp()

getIgnoreValue()

Retrieves the value for the special Ignore attribute value.

Syntax

public static String getIgnoreValue();
 

Parameters

None.

Return values

A String object containing the Ignore attribute value.

Exceptions

None.

Notes

The Ignore value, which getIgnoreValue() retrieves, is a special attribute value that represents an attribute value that the connector can ignore. Although the Java connector library does provide the CWConnectorAttrType.CxIgnore constant for the Ignore attribute value, it is recommended that you use the getIgnoreValue() method to obtain the Ignore value when you want to assign it to an attribute.

See also

getBlankValue()

getSupportedBONames()

Retrieves a list of supported business objects for the current connector.

WebSphere InterChange Server

The getSupportedBusObjNames() method is valid only when the integration broker is InterChange Server (ICS). It can provide supported business objects only with ICS version 4.0 and later. For ICS versions earlier than 4.0, this method throws the FunctionalityNotImplementedException exception.

Syntax

public static String[] getSupportedBONames()
 

Parameters

None.

Return values

A String array that contains a list of the names of the supported business objects for the connector.

Exceptions

NotSupportedException
Thrown if this method is called within a connector that has a version 3.x InterChange Server as its integration broker.

Notes

The getSupportedBONames() method returns a list of top-level supported business objects for the current connector; that is, if the connector supports business objects that contain child business objects, getSupportedBONames() includes only the name of the parent object in its list.

Note:
The getSupportedBONames() method is only supported when the connector is using a version 4.0 or later InterChange Server as its integration broker. If the connector is using an earlier version of InterChange Server, the method returns the NotSupportedException exception.

getVersion()

Retrieves the version of the connector.

Syntax

public static String getVersion();
 

Return values

A String containing the version of the connector.

Exceptions

None.

Notes

The getVersion() method returns the version of the Java connector library. It obtains this version from the manifest file that is present in the Java package.

Note:
The CWConnectorAgent class also provides a getVersion() method. However, this method retrieves the version of the connector itself.

initAndValidateAttributes()

Initializes attributes that do not have values set, but are marked as required, with their

default values.

Syntax

public static final void initAndValidateAttributes(
    CWConnectorBusObj theBusObj) ;
 

Parameters

theBusObj
Is the business object whose attributes this method sets.

Return values

None.

Exceptions

SpecNameNotFoundException
Thrown when the name of the specified business object does not match any of the business object definitions in the repository.
DefaultSettingFailedException
Thrown when the attribute's default value could not be set and there is no default value specified for the attribute in the business object definition.

Notes

The initAndValidateAttributes() method has two purposes:

The initAndValidateAttributes() method looks at every attribute in all levels of a business object and determines the following:

If an attribute is required and UseDefaults is true, initAndValidateAttributes() sets the value of any unset attribute to its default value. To have initAndValidateAttributes() set the attribute value to the special Blank value (CxBlank), you can set the attribute's default value to the string "CxBlank". If the attribute does not have a default value, initAndValidateAttributes() throws the DefaultSettingFailedException exception.

Note:
If an attribute is a key or other attribute whose value is generated by the application, the business object definition should not provide default values, and the Required property for the attribute should be set to false.

The initAndValidateAttributes() method is usually called from the business-object-handler doVerbFor() method to ensure that required attributes have values before a Create operation is performed in an application. In the doVerbFor() method, you can call initAndValidateAttributes() for the Create verb. You can also call it for the Update verb, before it performs a Create.

To use initAndValidateAttributes(), you must also do the following:

isBlankValue()

Determines if an attribute value is the special Blank value.

Syntax

public static boolean isBlankValue(Object value);
 

Parameters

value
Is the value to compare with the special Blank value.

Return values

Returns true if the specified attribute value is the Blank attribute value; otherwise, returns false.

Exceptions

None.

See also

isIgnoreValue()

isIgnoreValue()

Determines if an attribute value is the special Ignore value.

Syntax

public static boolean isIgnoreValue(Object value);
 

Parameters

value
Is the value to compare with the special Ignore value.

Return values

Return true if the specified attribute value is the Ignore value; otherwise, returns false.

Exceptions

None.

Notes

The Ignore attribute value signifies that this attribute is to be ignored while processing the business object.

See also

isBlankValue()

isTraceEnabled()

Determines if the trace level is greater than or equal to the trace level for which it is looking, if tracing is enabled at this level.

Syntax

public final static boolean isTraceEnabled(int traceLevel);
 

Parameters

traceLevel
is the trace level to check.

Return values

Returns true if the agent trace level is greater than or equal to the trace level passed in.

Exceptions

None.

Notes

Use this method before generating a message.

logMsg()

Logs a message to the connector's log destination.

Syntax

public final static void logMsg(String msg, int severity);
 

Parameters

msg
Is the message text to be logged.
severity
Is one of the following message-type constants to identify the message:
                        
 
 CWConnectorUtil.XRD_WARNING
                         
 
 CWConnectorUtil.XRD_ERROR
                         
 
 CWConnectorUtil.XRD_FATAL
                         
 
 CWConnectorUtil.XRD_INFO
 
  
 CWConnectorUtil.XRD_TRACE
 

Return values

None.

Exceptions

None.

Notes

The logMsg() method sends the specified msg text to the log destination. You establish the name of a connector's log destination through the Logging section in the Trace/Log File tab of Connector Configurator.

IBM recommends that log messages be contained in a message file and extracted with the generateMsg() method. This message file should be the connector message file, which contains messages specific to your connector. The generateMsg() method generates the message string for logMsg(). It retrieves a predefined message from a message file, formats the text, and returns a generated message string.

Note:
You can use the generateAndLogMsg() method to combine the message generation and logging steps.
WebSphere InterChange Server

If severity is XRD_ERROR or XRD_FATAL and the connector configuration property LogAtInterchangeEnd is set, the error message is logged and an email notification is sent when email notification is on. See the System Administration Guide in the IBM WebSphere InterChange Server documentation set for information on how to set up email notification for errors.

Connector messages logged with logMsg() are viewable using LogViewer if the message strings were generated with generateMsg().

See also

generateAndLogMsg(),, generateMsg()

readerToBO()

Calls a data handler to convert serialized data of a specified MIME type to a business object. This serialized data is accessed as a Reader object.

Syntax

public static CWConnectorBusObj readerToBO(CWConnectorBusObj theBusObj,
       Reader serializedData, String mimeType, String BOPrefix, 
       String encoding, Locale locale, Object config);
 

Parameters

BOPrefix
Is the business-object prefix, which is combined with mimeType to form the key of the child meta-object. This argument can be used to specify a MIME subtype. It can also be used to specify a value for the BOPrefix data-handler configuration property.
config
Is an Object that contains additional configuration information for the data handler.
encoding
Specifies the character encoding for the serialized data in the Reader object. If you specify null, the method uses the character encoding of the machine.
locale
Is a java.util.Locale object that specifies the locale for the serialized data in the Reader object. If you specify null, the method uses the connector-framework locale.
mimeType
Is the MIME type that identifies the format of the serialized data.
serializedData
Is an object of the Java java.io.Reader class (or one of its subclasses) that accesses the serialized data to convert to a business object.
theBusObj
Identifies the type of business object (business object definition) to which the method converts the serialized data.

Return values

A CWConnectorBusObj object that contains the business object for the serialized data.

Exceptions

DataHandlerCreateException
Thrown when the readerToBO() method cannot instantiate a data handler for the specified MIME type.
ParseException
Thrown when the data handler encounters some error during the conversion of the serialized data to the specified business object.
PropertyNotSetException
Thrown when the DataHandlerMetaObjectName connector configuration property is not set.

The readerToBO() method can also throw the general Java exception NullPointerException if the data handler returns a null pointer instead of a business object.

Notes

The readerToBO() method provides the connector with the ability to call a data handler to perform string-to-business-object conversion. With this method, the incoming serializedData is accessed through a Java Reader object. The method identifies which data handler to invoke based on the specified mimeType argument. It instantiates a data handler whose class name is identified in the child meta-object associated with this MIME type in the the top-level meta-object, as follows:

If the data handler cannot be instantiated, readerToBO() throws the DataHandlerCreateException. For more information on how the arguments of readerToBO() identify which data handler to instantiate, see Identifying the data handler to instantiate.

Once instantiated, the data handler converts the specified serialized data to a business object of the type that theBusObj indicates. If readerToBO() specifies the encoding and locale arguments, the data handler uses the specified character encoding and locale when it interprets the serialized data. The data handler returns this business object to the readerToBO() method, which in turn returns it to the calling method.

Note:
If the data handler cannot convert the serialized data, readerToBO() throws the ParseException exception.

You can specify a config option if you need to provide the data handler with more configuration information than is available in its meta-object. This argument can be used to specify a template file or a string to a URL for a schema that is used to build an XML document from a business object.

See also

byteArrayToBo(), streamToBO(), stringToBo()

streamToBO()

Calls a data handler to convert serialized data of a specified MIME type to a business object. This serialized data is accessed through an input stream.

Syntax

public static CWConnectorBusObj streamToBO(CWConnectorBusObj theBusObj,
       InputStream serializedData, String mimeType, String BOPrefix, 
       String encoding, Locale locale, Object config);
 

Parameters

BOPrefix
Is the business-object prefix, which is combined with mimeType to form the key of the child meta-object. This argument can be used to specify a MIME subtype. It can also be used to specify a value for the BOPrefix data-handler configuration property.
config
Is an Object that contains additional configuration information for the data handler.
encoding
Specifies the character encoding for the serialized data in the input stream. If you specify null, the method uses the character encoding of the machine.
locale
Is a java.util.Locale object that specifies the locale for the serialized data in the input stream. If you specify null, the method uses the connector-framework locale.
mimeType
Is the MIME type that identifies the format of the serialized data.
serializedData
Is an object of the Java java.io.InputStream class (or one of its subclasses) that accesses the serialized data to convert to a business object.
theBusObj
Identifies the type of business object (business object definition) to which the method converts the serialized data.

Return values

A CWConnectorBusObj object that contains the business object for the serialized data.

Exceptions

DataHandlerCreateException
Thrown when the streamToBO() method cannot instantiate a data handler for the specified MIME type.
ParseException
Thrown when the data handler encounters some error during the conversion of the serialized data to the specified business object.
PropertyNotSetException
Thrown when the DataHandlerMetaObjectName connector configuration property is not set.

The streamToBO() method can also throw the general Java exception NullPointerException if the data handler returns a null pointer instead of a business object.

Notes

The streamToBO() method provides the connector with the ability to call a data handler to perform string-to-business-object conversion. With this method, the incoming serializedData is accessed through a Java input stream (derived from the InputStream class). The method identifies which data handler to invoke based on the specified mimeType argument. It instantiates a data handler whose class name is identified in the child meta-object associated with this MIME type in the the top-level meta-object, as follows:

If the data handler cannot be instantiated, streamToBO() throws the DataHandlerCreateException. For more information on how the arguments of streamToBO() identify which data handler to instantiate, see Identifying the data handler to instantiate.

Once instantiated, the data handler converts the specified serialized data to a business object of the type that theBusObj indicates. If streamToBO() specifies the encoding and locale arguments, the data handler uses the specified character encoding and locale when it interprets the serialized data. The data handler returns this business object to the streamToBO() method, which in turn returns it to the calling method.

Note:
If the data handler cannot convert the serialized data, streamToBO() throws the ParseException exception.

You can specify a config option if you need to provide the data handler with more configuration information than is available in its meta-object. This argument can be used to specify a template file or a string to a URL for a schema that is used to build an XML document from a business object.

See also

boToStream(), byteArrayToBo(), readerToBO(), stringToBo()

stringToBo()

Calls a data handler to convert serialized data of a specified MIME type to a business object. This serialized data is accessed as a string.

Syntax

public static CWConnectorBusObj stringToBo(CWConnectorBusObj theBusObj, 
       String serializedData,     String mimeType);
 public static CWConnectorBusObj stringToBo(CWConnectorBusObj theBusObj,
       String serializedData, String mimeType, Object config);
 
public static CWConnectorBusObj stringToBo(CWConnectorBusObj theBusObj,
       String serializedData, String mimeType, String BOPrefix, 
       String encoding, Locale locale, Object config);
 

Parameters

BOPrefix
Is the business-object prefix, which is combined with mimeType to form the key of the child meta-object. This argument can be used to specify a MIME subtype. It can also be used to specify a value for the BOPrefix data-handler configuration property.
config
Is an Object that contains additional configuration information for the data handler.
encoding
Specifies the character encoding for the serialized data in the String. If you specify null, the method uses the character encoding of the machine.
locale
Is a java.util.Locale object that specifies the locale for the serialized data in the String. If you specify null, the method uses the connector-framework locale.
mimeType
Is the MIME type that identifies the format of the serialized data.
serializedData
Is the string representation of the serialized data to convert to a business object.
theBusObj
Identifies the type of business object (business object definition) to which the method converts the serialized data.

Return values

A CWConnectorBusObj object that contains the business object for the serialized data.

Exceptions

DataHandlerCreateException
Thrown when the stringToBo() method cannot instantiate a data handler for the specified MIME type.
ParseException
Thrown when the data handler encounters some error during the conversion of the serialized data to the specified business object.
PropertyNotSetException
Thrown when the DataHandlerMetaObjectName connector configuration property is not set.

The stringToBo() method can also throw the general Java exception NullPointerException if the data handler returns a null pointer instead of a business object.

Notes

The stringToBo() method provides the connector with the ability to call a data handler to perform string-to-business-object conversion. With this method, the incoming serializedData is accessed through a Java String. The method identifies which data handler to invoke based on the specified mimeType argument. It instantiates a data handler whose class name is identified in the child meta-object associated with this MIME type in the the top-level meta-object, as follows:

If the data handler cannot be instantiated, stringToBo() throws the DataHandlerCreateException. For more information on how the arguments of stringToBo() identify which data handler to instantiate, see Identifying the data handler to instantiate.

Once instantiated, the data handler converts the specified serialized data to a business object of the type that theBusObj indicates. If stringToBo() specifies the encoding and locale arguments, the data handler uses the specified character encoding and locale when it interprets the serialized data. The data handler returns this business object to the stringToBo() method, which in turn returns it to the calling method.

Note:
If the data handler cannot convert the serialized data, stringToBo() throws the ParseException exception.

You can specify a config option if you need to provide the data handler with more configuration information than is available in its meta-object. This argument can be used to specify a template file or a string to a URL for a schema that is used to build an XML document from a business object.

See also

boToString(), byteArrayToBo(), readerToBO(), streamToBO()

traceCWConnectorAPIVersion()

Writes the version of the Java connector library to the trace destination.

Syntax

public static void traceCWConnectorAPIVersion();
 

Parameters

None.

Return values

None.

Exceptions

None.

Notes

The traceCWConnectorAPIVersion() method sends the version of the Java connector library to the trace destination when the trace level is at level 1 and higher. It obtains the version of Java connector library from the manifest file in the package. A manifest file is a standard Java file that stores version information for a product.

You establish the name of a connector's trace destination through the TraceFileName connector configuration property.

See also

getCWConnectorAPIVersion()

traceWrite()

Writes a trace message to the trace destination.

Syntax

public final static void traceWrite(int traceLevel, String msg);
 

Parameters

traceLevel
Is one of the following trace-level constants to identify the trace level used to determine which trace messages are output:
                        
 
 CWConnectorUtil.LEVEL1
                         
 
 CWConnectorUtil.LEVEL2
                         
 
 CWConnectorUtil.LEVEL3
                         
 
 CWConnectorUtil.LEVEL4
                         
 
 CWConnectorUtil.LEVEL5
 

The method writes the trace message when the current trace level is greater than or equal to traceLevel.

Note:
Do not specify a trace level of zero (LEVEL0) with a tracing message. A trace level of zero indicates that tracing is turned off. Therefore, any trace message associated with a traceLevel of LEVEL0 will never print.
msg
Is the message text to use for the trace message.

Return values

None.

Exceptions

None.

Notes

You can use the traceWrite() method to write your own trace messages for a connector. Tracing is turned on for the connector when the TraceLevel connector configuration property is set to a nonzero value (any trace-level constant except LEVEL0).

The traceWrite() method sends the specified msg text to the trace destination when the current trace level is greater than or equal to traceLevel. You establish the name of a connector's trace destination through the Tracing section in the Trace/Log File tab of Connector Configurator.

Because trace messages are usually needed only during debugging, whether trace messages are contained in a message file is left at the discretion of the developer:

Connector messages logged with traceWrite() are not viewable using LogViewer.

See also

generateAndTraceMsg(),, generateMsg()

Copyright IBM Corp. 1997, 2004