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.
Member methods of the CWConnectorUtil classMember 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() |
Creates a CWConnectorUtil object.
Syntax
public CWConnectorUtil();
Parameters
None.
Return values
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
Return values
A byte array that contains the serialized business object in the specified MIME type.
Exceptions
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 boToByteArray() specifies a BOPrefix and a mimeType, 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. However, when a BOPrefix is specified, the instantiation process interprets this value as a MIME subtype. It searches the top-level meta-object for an attribute whose name includes both the MIME type and subtype.
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.
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()
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
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
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 boToStream() specifies a BOPrefix and a mimeType, 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. However, when a BOPrefix is specified, the instantiation process interprets this value as a MIME subtype. It searches the top-level meta-object for an attribute whose name includes both the MIME type and subtype.
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.
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()
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
Return values
A String object that contains the serialized business object in the specified MIME type.
Exceptions
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 boToString() specifies a BOPrefix and a mimeType, 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. However, when a BOPrefix is specified, the instantiation process interprets this value as a MIME subtype. It searches the top-level meta-object for an attribute whose name includes both the MIME type and subtype.
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.
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()
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
Return values
A CWConnectorBusObj object that contains the business object for the serialized data.
Exceptions
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 byteArrayToBo() specifies a BOPrefix and a mimeType, 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. However, when a BOPrefix is specified, the instantiation process interprets this value as a MIME subtype. It searches the top-level meta-object for an attribute whose name includes both the MIME type and subtype.
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.
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()
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
Return values
A CWConnectorBusObj object containing the newly created business object.
Exceptions
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.
Creates a new business object, assigning default values to all its attributes.
Syntax
public static CWConnectorBusObj createAndSetDefaults( String busObjName)
Parameters
Return values
A CWConnectorBusObj object containing the newly created business object.
Exceptions
Notes
The createAndSetDefaults() method performs the following tasks:
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
Return values
A CWConnectorBusObj object containing the newly created business object.
Exceptions
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
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
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);
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()
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
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.
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()
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
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.
CWConnectorLogAndTrace.XRD_WARNING CWConnectorLogAndTrace.XRD_ERROR CWConnectorLogAndTrace.XRD_FATAL CWConnectorLogAndTrace.XRD_INFO CWConnectorLogAndTrace.XRD_TRACE
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:
You can use the generateAndTraceMsg() method to combine the message generation and tracing steps.
You can use the generateAndLogMsg() method to combine the message generation and logging steps.
See also
generateAndLogMsg(),, generateAndTraceMsg(),, logMsg(),, traceWrite()
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()
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.
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()
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
Retrieves the value of a connector configuration property.
Syntax
public final static String getConfigProp(String propName);
Parameters
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()
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
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:
WebSphere InterChange Server |
---|
If a local configuration file exists, the setting of the CharacterEncoding connector configuration property in this local file takes precedence. If no local configuration file exists, the setting of the CharacterEncoding property is one from the set of connector configuration properties downloaded from the InterChange Server repository at connector startup. |
This method is useful when the connector needs to perform character-encoding processing, such as character conversion.
See also
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:
WebSphere InterChange Server |
---|
If a local configuration file exists, the setting of the Locale connector configuration property in this local file takes precedence. If no local configuration file exists, the setting of the Locale property is the one from the set of connector configuration properties downloaded from the InterChange Server repository at connector startup. |
This method is useful when the connector needs to perform locale-sensitive processing.
See also
createBusObj(),, getGlobalEncoding(),, getLocale()
Retrieves the top-level connector-object for a specified hierarchical connector configuration property.
Syntax
public static CWProperty getHierarchicalConfigProp(String propName);
Parameters
Return values
A CWProperty object that contains the top-level connector-property object for the specified hierarchical connector property.
Exceptions
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.
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()
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
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
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.
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.
Initializes attributes that do not have values set, but are marked as required, with their
Syntax
public static final void initAndValidateAttributes( CWConnectorBusObj theBusObj) ;
Parameters
Return values
None.
Exceptions
Notes
The initAndValidateAttributes() method has two purposes:
In case of failure, no value exists some attributes (those without default values) after initAndValidateAttributes() finishes default-value processing. You might want to code your connector's application-specific component to catch this exception and return CWConnectorConstant.FAIL.
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.
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:
Determines if an attribute value is the special Blank value.
Syntax
public static boolean isBlankValue(Object value);
Parameters
Return values
Returns true if the specified attribute value is the Blank attribute value; otherwise, returns false.
Exceptions
None.
See also
Determines if an attribute value is the special Ignore value.
Syntax
public static boolean isIgnoreValue(Object value);
Parameters
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
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
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.
Logs a message to the connector's log destination.
Syntax
public final static void logMsg(String msg, int severity);
Parameters
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.
Connector messages logged with logMsg() are viewable using LogViewer if the message strings were generated with generateMsg().
See also
generateAndLogMsg(),, generateMsg()
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
Return values
A CWConnectorBusObj object that contains the business object for the serialized data.
Exceptions
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 readerToBO() specifies a BOPrefix and a mimeType, 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. However, when a BOPrefix is specified, the instantiation process interprets this value as a MIME subtype. It searches the top-level meta-object for an attribute whose name includes both the MIME type and subtype.
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.
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()
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
Return values
A CWConnectorBusObj object that contains the business object for the serialized data.
Exceptions
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 streamToBO() specifies a BOPrefix and a mimeType, 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. However, when a BOPrefix is specified, the instantiation process interprets this value as a MIME subtype. It searches the top-level meta-object for an attribute whose name includes both the MIME type and subtype.
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.
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()
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
Return values
A CWConnectorBusObj object that contains the business object for the serialized data.
Exceptions
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 stringToBo() specifies a BOPrefix and a mimeType, 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. However, when a BOPrefix is specified, the instantiation process interprets this value as a MIME subtype. It searches the top-level meta-object for an attribute whose name includes both the MIME type and subtype.
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.
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()
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
Writes a trace message to the trace destination.
Syntax
public final static void traceWrite(int traceLevel, String msg);
Parameters
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.
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