Creating Custom Data Types

 

The data integration component of WebLogic Integration uses a metadata language called Message Format Language (MFL), based on XML, to describe binary data structure. Format Builder creates and maintains this metadata as a data file, or an MFL document in the repository. MFL uses the following metadata information to describe a binary field:

• Data type

• Length/Delimiter

• Optional/Mandatory

• Default value

• Code Page encoding

Of this information, the data type is the most critical. The selected data type dictates which metadata attributes are valid and how they are interpreted.

The data integration component of WebLogic Integration includes a User Defined Type feature that allows you to create custom data types specific to your unique data type requirements. The User Defined Type feature allows these custom data types to be plugged in to the data translation run-time engine. Once a user defined data type is plugged-in, it is indistinguishable from a built-in data type in both features and function.

Instructions on how to use User Defined Type are contained in the following topics:

• User Defined Types Sample Files

• Registering User Defined Types

• Creating User Defined Types

• Configuring User Defined Types for the Data Integration Plug-In

• User Defined Type Coding Requirements

• Class com.bea.wlxt.mfl.MFLField

 

---

User Defined Types Sample Files

The following table provides a listing and description of the sample files installed for use with User Defined Types. All directory names are relative to the WebLogic Integration installation directory.

Table B-1 User Defined Types Sample Files

Directory	File	Description
samples\di\ userdef	CapString.java	Source for a user data type that converts strings to upper case.
samples\di\ userdef	Dddmmyy.java	Source for a User Defined Type that supports a European date format.
samples\di\ userdef	Makefile	Make file for building the sample source.
samples\di\ userdef	ParseUserDef.java	Source that shows installing the sample User Defined Type and using them with the runtime engine.
samples\di\ userdef	readme.txt	Explains how to compile and run the sample.
samples\di\ userdef	sample.data	Data for the ParseUserData sample.
samples\di\ userdef	sample.mfl	The Message Format Language (MFL) file for the ParseUserData sample.

 

 

---

Registering User Defined Types

Perform the following steps to register a new User Defined Type:

1. Start Format Builder by choosing Start—>Programs—>BEA WebLogic E-Business Platform—>WebLogic Integration 2.1—>Format Builder. The Format Builder main window displays.

2. Choose Tools—>User Defined Types. The Add/Remove User Defined Types dialog box displays.

   Figure B-1 Add/Remove User Defined Types Dialog Box

   
    

3. Enter the class name implementing the type in the Class Name field.

   Note: The class name entered must include any package name present in the definition of the module. Additionally, the named class must be found in the Format Builder CLASSPATH. The WebLogic Integration installation of Format Builder creates a <wli home>/ext directory specifically for containing User Defined Types. The <wli home> directory is where WebLogic Integration is installed.

4. Click View. Information about the requested class populates the following display-only fields as follows.

   Figure B-2 Add/Remove User Defined Types Dialog Box

   
    

   • Type Name - returned by a call to getTypeName()

   • Display Name - return value of getDisplayName() prefixed by the literal User Defined:.

   • Description - returned by getDescriptionText()

   If the requested class cannot be loaded or does not conform to the requirements for a User Defined Type, an error message displays. Click OK to return to the Add/Remove User Defined Types dialog box. Refer to the User Defined Type Coding Requirements for required and optional interface methods, and available utility methods used for User Defined Types.

5. Once a valid User Defined Type is displayed, click Add to make it available for use within Format Builder.

Now that you have defined the new data type, the new Display Name appears in Format Builder along with the built-in data types. All User Defined Types displayed in the Data Type drop-down list box are prefixed with User Defined:, as in DisplayName text field.

Note: Because Format Builder cannot know the exact type of data represented by a User Defined Type, all generated XML Schema documents describing the XML generated by the data translation run-time component of WebLogic Integration for a particular transformation will use type of xsd::string to represent User Defined Type fields. This also affects Format Tester. When generating data for an MFL document containing User Defined Types, String data is generated for the corresponding fields. You must adjust the generated data so it will parse according to the User Defined Type.

 

---

Creating User Defined Types

The interface to the data translation engine is an API called by a Java program. Creating a new User Defined Type for the process engine is accomplished via static method of the com.bea.wlxt.WLXT class.

Installation of a User Defined Type into the data translation engine is not persistent. At termination of the current JVM process, the User Defined Type configuration information is discarded. As a result, clients using the stand-alone engine must install all User Defined Types at the start of each program.

The following public functions are defined for User Defined Types:

public static void addNewDataType(String name, Bintype binType)

name

specifies the name of the new data type in MFL.

binType

specifies a reference to a new User Defined Type object.

public static void removeDataType (String name)

name

specifies the name of the data type to remove.

The following example illustrates using theses APIs to install and remove the CapString User Defined Type.

import com.bea.wlxt.WLXT;
import com.bea.wlxt.binType.BinType;

// create data type object and install it
Bintype udt = new CapString();
WLXT.addNewDataType("UpperCaseString", udt);
			.
			.
			.

//remove the udt installed above
WLXT.removeDataType("UpperCaseString");

 

---

Configuring User Defined Types for the Data Integration Plug-In

User Defined Types used by the Data Integration Plug-In for business process management (BPM) are stored in the WebLogic Integration repository as CLASS documents. At runtime, the Data Integration Plug-In loads User Defined Type classes from the repository as required. In addition, the Data Integration Plug-In will export the MFL and class files required to support the active template allowing a template to be imported on another BPM instance intact.

At runtime, the Data Integration Plug-In will retrieve both MFL documents and required User Defined Type classes from the repository. Class documents may be placed in the repository using one of the following methods:

• Publish User Defined Types to repository from Format Builder

• Use the Repository Import utility

Publishing User Defined Types to the Repository from Format Builder

Perform the following steps to publish a User Defined Type to the repository.

1. Start Format Builder by choosing Start—>Programs—>BEA WebLogic E-Business Platform—>WebLogic Integration 2.1—>Format Builder. The Format Builder main window displays.

2. Choose Repository—>Log In. The WebLogic Integration Repository Login window opens.

   Figure B-3 WebLogic Integration Repository Login Window

   
    

3. Enter the userid specified for the connection in the User Name field.

4. Enter the password specified for the connection in the Password field.

5. Enter the server name and Port number in the Server[:port] field.

   Note: The WebLogic Integration Repository Login window allows up to three unsuccessful login attempts, after which, a login failure message is displayed. If you experience three login failures, choose Repository—>Log In to repeat the login procedure.

6. Click Connect. If your login is successful, the Login window closes and the Format Builder Title bar displays the server name and port number entered on the WebLogic Integration Repository Login window. You may now choose any of the active repository menu items to access.

7. Choose Tools—>User Defined Types. The Add/Remove User Defined Types dialog box opens.

   With a repository connection established, the Add/remove User Defined Types dialog box displays the status of each registered User Defined Type and allows for its publication to the repository. The User Defined Type repository status is reflected by an icon of a ball preceding the type name of each installed User Defined Type.

   Figure B-4 Add/Remove User Defined Types Dialog Box

   
    

   The color of the icon associated with each User Defined Type indicates its status:

   • Green - The User Defined Type has been published to the repository.

   • Yellow - The User Defined Type has been published to the repository, however, the local version of the class differs from the repository version.

   • Red - The User Defined Type does not exist in the repository.

8. Select the class you want to publish from the list of Installed Types and click Publish. The icon for the selected entry should become green indicating the class was successfully placed in the repository.

Publishing User Defined Types to the Repository Using the Repository Import Utility

The repository import utility may be used to import Java class files including data translation User Defined Types. This is accomplished by passing the class file name on the Import command line. For example, to import all the class files in the current directory:

java com.bea.wlxt.repository.Import *.class

It must be noted that any Java class file can be imported to the repository. This is not the case for Format Builder User Defined Type class files. This capability can be useful if, for example, a User Defined Type relies on additional class files that do not extend the com.bea.wlxt.bintype.Bintype class. Using the repository import utility allows these utility classes to be placed in the repository where they can be loaded by the repository class loader.

 

---

User Defined Type Coding Requirements

User Defined Types are required to extend the com.bea.wlxt.bintype.Bintype abstract class or one of its derived classes. The Bintype class provides the basic framework the data integration component of WebLogic Integration uses to interface with a data type and also provides utility routines useful in processing binary data types. In addition, two subclasses of Bintype, BintypeDate and BintypeString, offer additional utility routines for date and string types respectively.

The following classes and their required and optional interface methods are used for User Defined Types.

Class com.bea.wlxt.bintype.Bintype

Class com.bea.wlxt.bintype.Bintype consists of the following required, optional, and utility methods.

Required Interface Routines

The following interface methods are required when using the WebLogic Integration user defined data types utility.

public String read(InputStream byteStream, MFLField mflField)throws BintypeException

This routine is called to read a data value from a binary data stream. The read method should read the appropriate number of bytes for the data type, convert them to string representation, and return the string value. The mflField parameter is a reference to a com.bea.wlxt.mfl.MFLField object that describes the attributes of the data field.

If a User Defined Type is unable to successfully read the requested data element, it should throw a com.bea.wlxt.bintype.BintypeException with a text string that describes the error encountered.

public void write(BintypeOutputStream byteStream, MFLField mflField, String value)throws BintypeException

The write method is responsible for converting a string value into the data representation of the binary data type and writing it to a binary output stream.

If a User Defined Type is unable to successfully write the requested data element, it should throw a com.bea.wlxt.bintype.BintypeException with a text string that describes the error encountered.

Optional Interface Routines

The following interface routines are optional when using the data translation user defined data types utility.

public boolean canBeFieldType()

Returns true if the user defined data type may be used as the type for a data field.

Default: true

public boolean canBeLenFieldType()

Returns true if the User Defined Type may be used as the data type of a Length Field.

Default: true

public boolean canBeTagFieldType()

Returns true if the User Defined Type may be used as the type of a Tag Field.

Default: true

public boolean canBeDelimited()

Returns true if the User Defined Type supports delimited data values.

Default: false

public boolean isFixedSize()

Returns true if the User Defined Type represents a fixed size data value. Returning true from this method implies that the data type has an inherent fixed size.

Default: true

public boolean isDateType()

Returns true if the User Defined Type represents a date data type.

Default: flase

public boolean isCutoffRequired()

Returns true if the User Defined Type is a date data type and requires a cutoff value for adjusting a two digit year. This method is not used unless isDateType() returns true.

Default: false

public boolean isCodepageOK()

Returns true if the User Defined Type supports code pages.

Default: false

public boolean isValueOK()

Returns true if the User Defined Type supports an initial value attribute.

Default: false

public boolean canHaveDecimalPlaces()

Returns true if the User Defined Type represents a number which may have decimal places.

Default: false

public boolean canBePadded()

Returns true if the User Defined Type padding a fixed length data value.

Default: false

public boolean canBeTrimmed()

Returns true if the User Defined Type supports leading and trailing trimming.

Default: false

public String getDescriptiontext()

Returns a String that contains a text description of this data types function. This method should be implemented in a User Defined Types for documentation purposes.

Default: Empty String

public String getTypeName()

Returns a String containing the data type name. This function is used with User Defined Types and its return value is the type name used in MFL documents.

Default: The class name of the class implementing the User Defined Type.

public String getDisplayName()

Returns a String containing the Display Name for a data type name. This value appears in the Format Builder Types combo box.

Default: The class name of the class implementing the User Defined Type.

Utility Interface Routines

The following utility interface routines are available when using the data translation user defined data types utility.

public static byte[] getBinaryBytes (String str)

Converts a Java String into an array of binary bytes by taking the low order eight bits of each String character. No conversions are performed based on code pages.

public static String makeString(byte[] b)

Converts an array of binary bytes into a Java String value. No conversions are performed based on code pages.

protected void reverseBytes (byte[] data)

Reverses the order of bytes and an array of binary values.

protected String readTag(InputStream byteStream, MFLField fld) throws BinTypeexception

Reads and returns a tag value associated with a data field. This routine compares the tag value read with the expected value in the fld object and throws a Bintypeexception if they fail to match. If called for a fld that does not support tagged values, this method simply returns an empty string.

protected int readlength(InputStream byteStream, MFLField fld) thorws BintypeException

Reads and returns the length field associated with a data field. If called for a field that does not support a length field, it simply returns a zero.

protected void writeTag(BintypeOutputStream byteStream, MFLField fld) throws Bintypeexception

Writes the tag field associated with fld to the ByteStream supplied. If fld does not support a tag value this method simply returns without writing anything.

protected void writeLength(BintypeOutputStream byteStream, MFLField fld, int fldLen) thorws BintypeException

Writes the length field associated with fld to the byteStream supplied. If fld does not support a length field this method simply returns without writing anything.

protected byte[] readDelimitedField(InputStream byteStream, MFLField mflField) throws BintypeException

Reads data from the supplied input stream until encountering one of the delimiters for field mflField. The value returned is the binary data read excluding the delimiter value. If mflField is defined as not having a delimiter this method returns a null without reading any data.

protected String applyPadAndTrim(String value, MFLField fld, boolean applyPad, boolean applyTrim

Applies pad and trim functions as defined for fld to the data passed as value. The applyPad and applyTrim parameters control whether padding, trimming, or both are performed. The return value is the result data after having the requested operations performed.

Class com.bea.wlxt.bintype.BintypeString

Class com.bea.wlxt.bintype.BintypeString consists of the following required, optional, and utility routines.

Required Interface Routines

Same as class com.bea.wlxt.bintype.Bintype.

Optional Interface Routines

Same as class com.bea.wlxt.bintype.Bintype.

Utility Interface Routines

Same as class com.bea.wlxt.bintype.Bintype, plus the following utility interface routines.

protected String makeString(byte[] data, MFLField mflField) throws BintypeException

This method converts an array of binary data into a Java String respecting any code page defined in mflField.

protected byte[ ] readField(InputStream byteStream, MFLField mflField) throws Bintypeexception

This method reads a value representing a String data type from a binary input string. All length/delimiter attributes defined in mflField are respected in extracting the returned data value.

protected void writeField (BintypeOutputStream byteStream, MFLField mflField, String value, String codepage) throws BintypeException

Writes a data value to the supplied byteStream respecting the attributes defined for mflField and the passed codepage. If codepage is passed as null, the default system code page is used.

protected String trimBoth (String data, char trimChar)

Trims a specific character from both ends of the supplied data and returns the resulting string.

protected String trimLeading (String data, char trimChar)

Trims a specific character from the front of the supplied data and returns the resulting string.

protected String trimTrailing(String data, char trimChar)

Trims a specific character from the end of the supplied data and returns the resulting string.

Class com.bea.wlxt.bintype.BintypeDate

Class com.bea.wlxt.bintype.BintypeDate consists of the following required, optional, and utility routines.

Required Interface Routines

Same as class com.bea.wlxt.bintype.Bintype.

Optional Interface Routines

Same as class com.bea.wlxt.bintype.Bintype.

Utility Interface Routines

Same as class com.bea.wlxt.bintype.Bintype, plus the following utility interface routines.

protected static String readDate(String date, SimpleDateFormat fmt)

Parses a date from string parameter date according to format fmt. The return value is a valid date in string format.

protected static String readDate(String date, SimpleDateFormat fmt, MFLField fld, int yearpos

Parses a date containing a two digit year from string parameter date according to format fmt.

protected static String writeDate(String date, SimpleDateFormat fmt)

Returns a date string suitable for output from the string parameter date using date format fmt.

protected static String rawDateToString(byte[ ] data, String baseType)

Converts a date in raw binary format into a Java String using the base data type specified.

protected static byte[ ] stringDateToRaw(String date, String baseType)

Converts a date in Java String format into a binary array of bytes using the supplied base data type.

 

---

Class com.bea.wlxt.mfl.MFLField

The MFLField class is passed into all User Defined Type read and write methods. It encapsulates all the defined attributes for the field being read or written. MFLField supplies various methods that allows these attributes to be queried, and their respective values returned. Attributes that the User Defined Type does not support will never be present. For example, if the User Defined Type returned false to the isValueOK() method, it would never be passed to an MFLField object which returned true for the MFLField.hasValue() method.

Class com.bea.wlxt.mfl.MFLField supports the following MFLField methods.

public String getName()

Returns the name of the data field.

public String getType()

Returns the data type name of the field. This will be the name returned by the User Defined Type's getTypeName() method.

public boolean hasBaseType()

Returns true if a base type is defined for the field. This method will only return true for date data types.

public String getBaseType

Returns the base data type name for this field.

public boolean hasDelimRef()

Returns true if a delimiter reference is defined for the field.

public String getDelimRef()

Returns the field name of the field containing the delimiter value for this field.

public boolean hasdelimRefValue()

Returns true if the delimiter reference field contains a value.

public boolean hasDefaultValue()

Returns true if this field has a default value.

public String getDefaultValue()

Returns the default value for this field.

public boolean hasPad()

Returns true if this field has a defined pad value.

public String getPad()

Returns the pad value for this field.

public boolean hasTrimLeading()

Returns true if this field has a leading trim value defined.

public String getTrimLeading()

Returns the leading trim value for this field.

public boolean hasTrimTrailing()

Returns true if this field has a trailing trim value defined.

public String getTrimTrailing()

Returns the trailing trim value for this field.

public boolean isOptional()

Returns true if this field is defined as being optional.

public boolean hasCutoff()

Returns true if the field is defined as having a date cutoff value.

public int getCutoff()

Returns the date cutoff value defined for this field.

public boolean hasLength()

Returns true if an exact length is defined for this field.

public int getLength()

Returns the exact length defined for this field.

public boolean hasDelim()

Returns true if a delimiter value is defined for this field.

public String getDelim()

Returns the delimiter value defined for this field.

public boolean hasValue()

Returns true if an initial value has been defined for this field.

public String getValue()

Returns the initial value defined for this field.

public boolean hasCodepage()

Returns true if a code page has been defined for this field.

public String getCodepage()

Returns the name of the codepage defined for this field.

public boolean hasTagField()

Returns true if a tag field is defined for this field.

public boolean hasLenField()

Returns true if a length field is defined for this field.

public boolean isTagBeforeLength()

Returns true if the field tag value, if present, occurs before the length field.

public boolean hasDecimalPlaces()

Returns true if this field has decimal places defined.

public int getDecimalPLaces()

Returns the number of decimal places defined for this field.