Bean Extender Guide to Features


The Data Input Wizard

The Data Input Wizard is designed to help developers create Java beans that can read data input streams encoded in a legacy data format. The Data Input Wizard uses graphical user interfaces to allow developers to describe existing data formats and then generate a new bean capable of reading the legacy format.

To start the Data Input Wizard, enter the following on the command line:

java com.ibm.beans.tools.dataFormatWizard.DataInputWizard

Using File Schemas

A file schema is used to describe the structure within a collection of data, such as a file, database, or communication stream. The file schema contains a collection of schema records that describe the actual details of the data format.

The following graphic is an example of a file schema.


* Figure dwiz01 not displayed.

Creating a File Schema

To create a new file schema:

Saving and Restoring a File Schema

To save a file schema, click on the Save item from the Schemas menu. The schema is saved in the file SchemaName.ser, where SchemaName is the current name of the file schema. The file is saved to the current working directory, defined in the BeanSystemProperties class.

To specify an exact file and directory for saving a file schema, click on the Save As item from the Schemas menu. A file selection dialog is displayed. Enter the desired file name and directory, and then click on the OK button. The default values for the file name and directory are the ones used by the Save command.

To open an existing file schema, click on the Open item from the Schemas menu. A file selection dialog is displayed. Choose a file containing the desired file schema, and click on the OK button.

Generating a Reader Class for a File Schema

To generate a reader class for a file schema, click on the Schemas menu and then the Generate item. This selection causes the Java source code for a set of reader classes to be emitted and compiled. Status dialogs are displayed containing the status and any errors generated during the compilation of the reader class.

Each source code file will be named <Item>Reader.java, where Item is the name of the file schema or schema record used to generate that reader class. The source code files and the resulting .class files are placed in the package subdirectory com/ibm/beans/tools/dataFormatWizard/readers of the current working directory, defined in the BeanSystemProperties class.

Using the Reader Class for a File Schema

Each reader class generated by the Data Input Wizard has a readLegacy() method as defined by the com.ibm.beans.tools.dataFormatWizard.LegacyReader interface. The reader class also contains the get and set accessor methods for any fields or subrecords contained by the file schema or schema record used to generate the reader class.

To use the generated schema record class, create an instance of the <SchemaName>Record class, where SchemaName is the name of the file schema. Call the readLegacy() method with a data input stream containing the legacy data to be read. After the stream is read, access the data retrieved from the stream through the get accessor methods of the file schema reader and the schema record readers.

Using Schema Records

A schema record is used to describe the structure of a small set of fields and subrecords within a file schema.

The following graphic depicts an example of a record attributes dialog.


* Figure dwiz02 not displayed.

A schema record has the following properties:
unused If this property is set, the schema record represents unused data. The reader classes read the data from an input stream, but will not store it or provide any get accessor methods to access it.
name The name of the schema record. The record name must be unique within the file schema. This name is used to generate a Java reader class for the schema. If this name is not a valid Java class identifier, it is converted into one. Embedded blanks will be removed, and invalid characters are converted to "x" characters.
blocksize If this property is set, then the reader classes always read this number of bytes when processing this record. Any of the bytes not used by the fields and subrecords of this record are ignored.
repeated This property determines whether the record is expected to appear once or multiple times within the data stream. This property can have the following values:
ONCE The record is expected to appear exactly once. This is the default.
N TIMES The record is expected to appear N times, where N is defined by a Java expression. The expression can use constant values or can refer to the values of other fields in the schema. To refer to values of other field in a schema, it uses their get accessor methods.
WHILE X The record is expected to appear an arbitrary number of times while condition X is true. X is defined by a Java expression that can use constant values or can refer to the values of other schema fields. To refer to a value of other schema fields, it uses their get accessor methods.
UNTIL X The record is expected to appear an arbitrary number of times, but at least once, until condition X is true. X is defined by a Java expression that can use constant values or can refer to the values of other fields. To refer to a value of other schema fields, it uses their get accessor methods.
UNTIL END-OF-BLOCK The record is expected to appear an arbitrary number of times until the end of the current block is reached. This value is not valid unless this record is contained within another record that defines the block size.
UNTIL END-OF-FILE The record is expected to appear an arbitrary number of times until the end of the input stream is reached.
Note:If the record is repeated, all get accessor methods for the record will return an array instead of a single object. These methods have the name "get<RecordName>Array" instead of "get<RecordName>".
if This property determines whether a record is always expected to appear in the data stream or only under certain conditions. If the record is not always expected, a boolean Java expression must be supplied, using constants or other schema values, to determine when the record should be expected. By default, the record is expected to appear in the data stream.

Creating a New Schema Record

To create a new schema record:

  1. Click on an existing schema item to mark the point where the new record should be inserted into the schema.
  2. Click on the Items menu and then the New Record item to display the record attributes dialog.
  3. Enter the desired property values for the new schema record.
  4. Click on the OK button.

See "Using Schema Records" for an explanation of the schema record properties used in this dialog.

Modifying a Schema Record

To modify an existing schema record:

  1. Click on the schema record to modify
  2. Click on the Edit menu and then the Item Attributes item to display the record attributes dialog.
  3. Enter the desired property values for the new schema record.
  4. Click on the OK button.

See "Using Schema Records" for an explanation of the schema record properties used in this dialog.

Changing the Background Color

You can change the background color of the schema record to improve ease-of-viewing. However, the new background color is chosen randomly. To change the background color, click on the Edit menu and then the Record Color item.

Collapsing and Expanding Views

If you do not need to see the contents of the schema record, you can collapse the record view to get more screen space for other records. To collapse the record view, click on the triangular icon beside the record name.

To expand a collapse record view, you can click on the triangular icon that was originally beside the record name again.

Using Schema Fields

A schema field describes a basic set of information, such as a numeric value, a text string, or a constant value contained within a file schema. Schema fields are always contained within a parent schema record.

Using Primitive Fields

A primitive field is a schema field that can be interpreted as a Java primitive type, such as a single byte or single floating-point value. The reader class uses one of the predefined methods in class java.io.DataInputStream to read the value and to define the get accessor method that returns the specified Java primitive type.

The following graphic is an example of the primitive field attributes dialog.


* Figure dwiz03 not displayed.

A primitive field has the following properties:
unused If this property is set, the primitive field represents unused data. The reader class reads the data from an input stream, but it does not store this data or provide any get accessor methods to access it.
name The name of the primitive field. The field name must be unique within the parent schema record. This name is used to declare a field within a Java reader class for the parent schema record. If the specified name is not a valid Java field identifier, it is converted into one. Embedded blanks are removed and invalid characters are converted to "x" characters.
primitive type The type of the primitive field. It can have one of the following values:
  • byte
  • boolean
  • character
  • double
  • float
  • integer
  • short
repeated This property determines whether the field is expected to appear once or multiple times in the data stream. This property can have the following values:
ONCE The field is expected to appear exactly once. This is the default.
N TIMES The field is expected to appear N times, where N is defined by a Java expression. The expression can use constant values or can refer to the values of other fields in the schema. To refer to values of other fields in a schema, it uses their get accessor methods.
WHILE X The field is expected to appear an arbitrary number of times while condition X is true. X is defined by a Java expression that can use constant values or can refer to the values of other schema fields. To refer to a value of other schema fields, it uses their get accessor methods.
UNTIL X The field is expected to appear an arbitrary number of times, but at least once, until condition X is true. X is defined by a Java expression that can use constant values or can refer to the values of other fields. To refer to a value of other schema fields, it uses their get accessor methods.
UNTIL END-OF-BLOCK The field is expected to appear an arbitrary number of times until the end of the current block is reached. This value is not valid unless this record is contained within another record that defines the block size.
UNTIL END-OF-FILE The field is expected to appear an arbitrary number of times until the end of the input stream is reached.

Creating Primitive Fields

To create a new primitive field:

  1. Click on the existing schema item to mark the point where the new field should be inserted into the schema.
  2. Click on the Items menu and then the New Primitive Field item.
  3. Enter the desired property values for the new primitive field.
  4. Click on the OK button.

See "Using Primitive Fields" for an explanation of the field properties used in this dialog.

Modifying Primitive Fields

To modify an existing primitive field:

  1. Click on the field to be modified.
  2. Click the Edit menu and then the Item Attributes item to display the field attribute dialog.
  3. Modify the desired property values for the primitive field.
  4. Click on the OK button.

See "Using Primitive Fields" for an explanation of the field properties used in this dialog.

Using Class Fields

A class field is a schema field that is managed by a separate Java class. For example, the ASCII_Integer class in the com.ibm.beans.tools.dataFormatWizard.readers package reads a series of ASCII digits and automatically converts them to an integer value.

The following graphic is an example of the class field dialog.


* Figure dwiz04 not displayed.

The class field has the following properties:
unused If this property is set, the class field represents unused data. The reader classes read the data from an input stream, but does not store it or provide any get accessor methods to access it.
name The name of the class field. This name is used to declare a field within the Java reader class for the parent schema record. The field name must be unique within the file schema. If this specified name is not a valid Java field identifier, it is converted into one. Embedded blanks are removed, and invalid characters are converted to "x" characters.
classname The name of the external Java reader class used to read the data for this class field. This class must implement the com.ibm.beans.tools.dataFormatWizard.LegacyReader interface and should also provide get accessor methods to access the data it reads. Any settings needed by this class should be provided in the form of constructor arguments.
arguments The constructor arguments to be passed to the external Java reader class for this field.
repeated This property determines whether the record is expected to appear once or multiple times within the data stream. This property can have the following values:
ONCE The field is expected to appear exactly once. This is the default.
N TIMES The field is expected to appear N times, where N is defined by a Java expression. The expression can use constant values or can refer to the values of other fields in the schema. To refer to values of other fields in a schema, it uses their get accessor methods.
WHILE X The field is expected to appear an arbitrary number of times while condition X is true. X is defined by a Java expression that can use constant values or can refer to the values of other schema fields. To refer to a value of other schema fields, it uses their get accessor methods.
UNTIL X The field is expected to appear an arbitrary number of times, but at least once, until condition X is true. X is defined by a Java expression that can use constant values or can refer to the values of other fields. To refer to a value of other schema fields, it uses their get accessor methods.
UNTIL END-OF-BLOCK The field is expected to appear an arbitrary number of times until the end of the current block is reached. This value is not valid unless this record is contained within another record that defines the block size.
UNTIL END-OF-FILE The field is expected to appear an arbitrary number of times until the end of the input stream is reached.
if This property determines whether a field is always expected to appear in the data stream or only under certain conditions. If the field is not always expected, a boolean Java expression must be supplied, using constants or other schema values, to determine when the field should be expected. By default, the field is expected to appear in the data stream.

Creating Class Fields

To create a class field:

  1. Click on an existing schema item to mark the point where the new class field should be inserted into the schema.
  2. Click on the Items menu and then the New Class Field item to display the class field dialog.
  3. Enter the desired property values for the new class field.
  4. Click on the OK button.

See "Using Class Fields" for an explanation of the property values used in the class field dialog.

Modifying Class Fields

To modify an existing class field:

  1. Click on the field.
  2. Click on the Edit menu and then the Item Attributes item to display the field dialog.
  3. Modify the property values for the class field.
  4. Click on the OK button.

See "Using Class Fields" for an explanation of the property values used in the class field dialog.

Using Assertions

An assertion is a schema field that represents a boolean test to be performed on the data while it is being read from the stream. If the test is true; an exception is thrown, and the input stops.

The following graphic is an example of the assertion dialog.


* Figure dwiz05 not displayed.

An assertion has only the if property. The if property determines whether the assertion should be performed. A boolean Java expression must be supplied, using constants or other schema field values, to determine when this assertion should be performed.

Creating an Assertion

To create an assertion:

  1. Click on an existing schema item to mark the point where the new assertion should be inserted into the schema.
  2. Click on the Items menu and then the New Assertion item to display the assertion dialog.
  3. Enter the test property for the new assertion.
  4. Click on the OK button.

See "Using Assertions" for an explanation of the test property used in the assertion dialog.

Modifying an Assertion

To modify the test for an existing assertion:

  1. Click on the field.
  2. Click on the Edit menu and then the Item Attributes item to display the field dialog.
  3. Modify the test property for the assertion.
  4. Click on the OK button.

See "Using Assertions" for an explanation of the test property used in the assertion dialog.


[ Top of Page | Previous Page | Next Page | Table of Contents | Documentation Homepage ]