Creating Custom Data Types

WebLogic Integration uses a metadata language called Message Format Language (MFL), based on XML, to describe the structure of binary data when data is being integrated. The Format Builder creates and maintains metadata as a data file, or an MFL document in the repository.

In MFL, the following metadata is used 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 for using user-defined types are provided in the following sections:

• Samples of User-Defined Types

• 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

 

---

Samples of User-Defined Types

The following table provides describes the sample files installed with user-defined types. All directory names are relative to the WebLogic Integration samples directory (SAMPLES_HOME\integration) where SAMPLES_HOME is the samples directory in your WebLogic Platform installation..

Table B-1 Sample User-Defined Types  

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 run-time 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 Platform 7.0—>WebLogic Integration 7.0—>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. In the Class Name field, enter the name of the class implementing the specified type.

   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 the Format Builder creates a WLI_HOME/ext directory specifically for containing user-defined types. The WLI_HOME directory is the directory in which WebLogic Integration is installed.

4. Click View. Information about the requested class populates several 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 a requested class cannot be loaded or does not conform to the requirements for a user-defined type, an error message is displayed. Click OK to return to the Add/Remove User Defined Types dialog box.

   For lists of the required and optional interface methods, and utility methods available for use with user-defined types, see the user-defined type coding requirements.

5. Once a valid user-defined type is displayed, click Add to make it available for use within the Format Builder.

After you define the new data type, the new Display Name is shown in the Type drop-down list on the detail window for a field. All user-defined types displayed in the Type drop-down list are prefixed with User Defined:, as shown in the DisplayName text field.

Because the Format Builder cannot know the exact type of data represented by a user-defined type, the xsd::string type is used to represent the user-defined type in the XML Schema generated to describe the content model of the XML output.

Use of this data type also affects the Format Tester. When data is being generated for an MFL document containing user-defined types, String data is generated for the corresponding fields. You must adjust the generated data so it can be parsed 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 a static method of the com.bea.wlxt.WLXT class.

Installation of a user-defined type in the data translation engine is not persistent. When the current JVM process terminates, 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 refers to a new user-defined type object.

• public static void removeDataType (String name)

  name specifies the name of the data type to be removed.

The following example shows how to use these 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

The 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 run time, the data integration plug-in loads user-defined type classes from the repository as required. In addition, the data integration plug-in exports the MFL and class files required to support the active template, allowing a template to be imported, intact, on another BPM instance.

At run time, the data integration plug-in retrieves both MFL documents and required user-defined type classes from the repository. Class documents may be placed in the repository by using one of the following methods:

• Publishing user-defined types to the repository from the Format Builder

• Using the Repository Import utility

Publishing User-Defined Types to the Repository from the Format Builder

To publish a user-defined type to the repository, complete the following procedure:

1. Start the Format Builder by choosing Start—>Programs—>BEA WebLogic Platform 7.0—>WebLogic Integration 7.0—>Format Builder. The Format Builder main window is displayed.

2. Choose Repository—>Log In. The WebLogic Integration Repository Login dialog box is displayed.

   Figure B-3 WebLogic Integration Repository Login Dialog Box

   
    

3. In the User Name field, enter the user ID specified for the connection.

4. In the Password field, enter the password specified for the connection.

5. In the Server[:port] field, enter the server name and port number.

   Note: After three unsuccessful login attempts, the WebLogic Integration Repository Login dialog box is dismissed and a login failure message is displayed. To try again after a failure, choose Repository—>Log In to redisplay the Repository Login dialog box.

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 in the WebLogic Integration Repository Login dialog box. You may now access any of the active repository menu items.

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 a ball-shaped icon before the name of each installed user-defined type.

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

   
    

   The status of each user-defined type is indicated by the color of the icon.

   Table B-2 Icon Color Description

   If the icon is . . .	Then . . .
   Green	The user-defined type has been published to the repository.
   Yellow	The user-defined type has been published to the repository, but the local and repository versions of the class do not match.
   Red	The user-defined type does not exist in the repository.

   
    

8. From the list of installed types, select the class you want to publish 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. To use the import utility for this purpose, pass the name of the class file on the Import command line. For example, to import all the class files in the current directory:

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

Please note that any Java class file can be imported to the repository. This is not the case for user-defined type class files created in the Format Builder. 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. By using the repository import utility, you can put these utility classes in the repository, where they can be accessed 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 the classes derived from it. The Bintype class provides the basic framework used by the data integration component of WebLogic Integration to interface with a data type. This class also provides utility routines that are useful for 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, along with the required and optional interface methods they provide, are available 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 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

When you use the data translation user-defined data types utility, the following interface routines are optional:

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. A return of 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: false

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 that may include 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 type 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 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 Type drop-down list on the detail window for a field.

Default: The name of the class implementing the user-defined type.

Utility Interface Routines

When you use the data translation user-defined data types utility, the following utility interface routines are available:

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) throws 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) throws BintypeException

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. By default this method does not do any truncation of the fields.

protected String applyPadTrimAndTruncate(String value, MFLField fld, boolean applyPad, boolean applyTrim boolean applyTruncate) throws BintypeException

Applies pad, trim, and truncate functions as defined for fld to the data passed as value. The applyPad, applyTrim, and applyTruncate parameters control whether padding, trimming, and truncation 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 the string parameter date according to the fmt format. 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 the string parameter date, according to the fmt format.

protected static String writeDate(String date, SimpleDateFormat fmt)

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

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 read and write methods for user-defined types. It encapsulates all the attributes defined for the field being read or written. MFLField supplies various methods that allow these attributes to be queried, and their respective values returned. Attributes that are not supported by a user-defined type are never included. For example, if a user-defined type returns false to the isValueOK() method, it is never passed to an MFLField object that returns 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 name of the data type for this field. This name is returned by the getTypeName() method of the user-defined type.

public boolean hasBaseType()

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

public String getBaseType

Returns the name of the base data type for this field.

public boolean hasDelimRef()

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

public String getDelimRef()

Returns the name of the field that contains 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 a default value is defined for this field.

public String getDefaultValue()

Returns the default value for this field.

public boolean hasPad()

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

public String getPad()

Returns the pad value for this field.

public boolean hasTrimLeading()

Returns true if a leading trim value is defined for this field.

public String getTrimLeading()

Returns the leading trim value for this field.

public boolean hasTrimTrailing()

Returns true if a trailing trim value is defined for this field.

public String getTrimTrailing()

Returns the trailing trim value for this field.

public boolean isOptional()

Returns true if this field is defined as optional.

public boolean hasCutoff()

Returns true if a date cutoff value is defined for this field.

public int getCutoff()

Returns the value of the date cutoff 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 is defined for this field.

public String getValue()

Returns the initial value defined for this field.

public boolean hasCodepage()

Returns true if a code page is 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 any) appears before the length field.

public boolean hasDecimalPlaces()

Returns true if decimal places are defined in this field.

public int getDecimalPLaces()

Returns the number of decimal places defined for this field.

public String getPadType() { return(padType); }

Returns the type of padding set for this field (leading or trailing)

public boolean hasTruncateFirst() { return(0 != truncateFirst); }

Returns true if n number of truncate characters at the start of the field are defined.

public int getTruncateFirst() { return(truncateFirst); }

Returns the number of truncate characters defined at the start of this field.

public boolean hasTruncateAfter() { return(0 != truncateAfter); }

Returns true if n number of truncate characters at the end of the field are defined.

public int getTruncateAfter() { return(truncateAfter); }

Returns the number of truncate characters defined at the end of this field.