com.ibm.as400.access
Class RecordFormat

java.lang.Object
  com.ibm.as400.access.RecordFormat

All Implemented Interfaces:

Serializable

public class RecordFormat
extends Object
implements Serializable

The RecordFormat class represents the format of data returned from an IBM i system. It contains FieldDescription objects that describe the data returned from a system. The RecordFormat class is used to generate a Record object that can be used to access the data returned from the system as Java objects or as byte arrays of IBM i data. For instance, the entries on a data queue may have a specific format. This format could be represented by a RecordFormat object. The RecordFormat object could be used to generate a Record object containing the data read from the data queue. Based on the description of the data contained in the RecordFormat object, the Record object could be used by the Java program to handle the data as Java objects. As another example, a parameter for a program may be an array of bytes representing several different types of data. Such a parameter could be described by a RecordFormat object.

The RecordFormat class is also used to describe the record format of a file when using the record-level database access classes. The record format of the file must be set prior to invoking the open() method on an AS400File object.

The RecordFormat class is also used to describe the record format of a record when using the LineDataRecordWriter class. The following record format attributes are required to be set.

• Record format ID
• Record format type
• Field descriptions that make up the record format
• The delimiter, when the record format type is VARIABLE_LAYOUT_LENGTH
• Field description layout attributes,length and alignment, when the record format is FIXED_LAYOUT_LENGTH

The RecordFormat class allows the user to do the following:

• Describe the data returned from a system.
• Retrieve a Record object containing data that is described by the RecordFormat.

RecordFormat objects generate the following events:

• RecordDescriptionEvent
  The events fired are:
  • fieldDescriptionAdded()
  • keyFieldDescriptionAdded()
• PropertyChangeEvent
• VetoableChangeEvent

Examples

• Using the RecordFormat class with the Data queue classes
• Using the RecordFormat class with the record-level database access classes
• Using the RecordFormat class with the LineDataRecordWriter class

See Also:

AS400FileRecordDescription, Serialized Form

Field Summary

Modifier and Type	Field and Description
static int	FIXED_LAYOUT_LENGTH This constant is only used for record level writing.
static int	VARIABLE_LAYOUT_LENGTH This constant is only used for record level writing.

Constructor and Description

RecordFormat()
Constructs a RecordFormat object.

RecordFormat(String name)
Constructs a RecordFormat object.

Method Summary

Modifier and Type	Method and Description
void	addFieldDescription(FieldDescription field) Adds a field description to this record format.
void	addKeyFieldDescription(int index) Adds a key field description to this record format.
void	addKeyFieldDescription(String name) Adds a key field description to this record format.
void	addPropertyChangeListener(PropertyChangeListener listener) Adds a listener to be notified when the value of any bound property is changed.
void	addRecordDescriptionListener(RecordDescriptionListener listener) Adds a listener to be notified when a RecordDescriptionEvent is fired.
void	addVetoableChangeListener(VetoableChangeListener listener) Adds a listener to be notified when the value of any constrained property is changed.
char	getDelimiter() Returns the delimiter.
FieldDescription	getFieldDescription(int index) Returns the field description at the specified index.
FieldDescription	getFieldDescription(String name) Returns the field description with the specified name.
FieldDescription[]	getFieldDescriptions() Returns the field descriptions that make up this object.
String[]	getFieldNames() Returns the names of the field descriptions that make up this record format.
int	getIndexOfFieldName(String name) Returns the index of the field description named name.
int	getIndexOfKeyFieldName(String name) Returns the index of the field description of the key field named name.
FieldDescription	getKeyFieldDescription(int index) Returns the field description of the key field at the specified index.
FieldDescription	getKeyFieldDescription(String name) Returns the field description of the key field with the specified name.
FieldDescription[]	getKeyFieldDescriptions() Returns the key field descriptions that make up this object.
String[]	getKeyFieldNames() Returns the names of the field descriptions of the keys that make up this record format.
int	getLengthDependency(int index) Returns the index of the field description on which the field description at the specified index depends.
int	getLengthDependency(String name) Returns the index of the field description on which the field description with the specified name depends.
String	getName() Returns the name of this record format.
Record	getNewRecord() Returns a new record based on this record format, which contains default values for the contents of the fields.
Record	getNewRecord(byte[] contents) Returns a new record based on this record format, which contains data from the specified byte array.
Record	getNewRecord(byte[] contents, int offset) Returns a new record based on this record format, which contains data from the specified byte array.
Record	getNewRecord(byte[] contents, int offset, String recordName) Returns a new record based on this record format, which contains data from the specified byte array.
Record	getNewRecord(byte[] contents, String recordName) Returns a new record based on this record format, which contains data from the specified byte array.
Record	getNewRecord(String recordName) Returns a new record based on this record format, which contains default values for the contents of the fields.
int	getNumberOfFields() Returns the number of field descriptions in this record format.
int	getNumberOfKeyFields() Returns the number of key field descriptions in this record format.
int	getOffsetDependency(int index) Returns the index of the field description on which the field description at the specified index depends.
int	getOffsetDependency(String name) Returns the index of the field description on which the field description with the specified name depends.
String	getRecordFormatID() Returns the record format ID.
int	getRecordFormatType() Returns the record format type.
void	removePropertyChangeListener(PropertyChangeListener listener) Removes a listener from the change list.
void	removeRecordDescriptionListener(RecordDescriptionListener listener) Removes a listener from the record description listeners list.
void	removeVetoableChangeListener(VetoableChangeListener listener) Removes a listener from the veto change listeners list.
void	setDelimiter(char delimiter) Sets the delimiter.
void	setLengthDependency(int dependentField, int fieldDependedOn) Sets the field on which a dependent field depends.
void	setLengthDependency(String dependentField, String fieldDependedOn) Sets the field on which a dependent field depends.
void	setName(String name) Sets the name of this record format.
void	setOffsetDependency(int dependentField, int fieldDependedOn) Sets the field on which a dependent field depends.
void	setOffsetDependency(String dependentField, String fieldDependedOn) Sets the field on which a dependent field depends.
void	setRecordFormatID(String id) Sets the record format ID.
void	setRecordFormatType(int type) Sets the record format type.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

FIXED_LAYOUT_LENGTH

public static final int FIXED_LAYOUT_LENGTH

This constant is only used for record level writing.

See Also:

Constant Field Values

VARIABLE_LAYOUT_LENGTH

public static final int VARIABLE_LAYOUT_LENGTH

This constant is only used for record level writing.

See Also:

Constant Field Values

Constructor Detail

RecordFormat

public RecordFormat()

Constructs a RecordFormat object.
Note: When using this object with the record level access classes, the version of the constructor that takes name must be used.

See Also:

RecordFormat(java.lang.String)

RecordFormat

public RecordFormat(String name)

Constructs a RecordFormat object. It uses the name specified.
Note: Use this version of the constructor when the object is being used with the record level access classes.

Parameters:

name - The name of the record format. The name is converted to uppercase by this method. When using this object with the record level access classes, the name must be the name of the record format for the file that is being described.

Method Detail

addFieldDescription

public void addFieldDescription(FieldDescription field)

Adds a field description to this record format. The field description is added to the end of the field descriptions in this object.

Parameters:

field - The field description to be added.

addKeyFieldDescription

public void addKeyFieldDescription(int index)

Adds a key field description to this record format. The key field description is determined by the index of a field description that was already added to this object. The key field description is added to the end of the key field descriptions in this object. The order in which the key field descriptions are added must match the order of the key fields in the files for which this record format is meant.

Parameters:

index - The index of a field description that was already added to this object via addFieldDescription(). The index must be in the range zero to getNumberOfFields() - 1.

addKeyFieldDescription

public void addKeyFieldDescription(String name)

Adds a key field description to this record format. The key field description is determined by the name of a field description that was already added to this object. The key field description is added to the end of the key field descriptions in this object. The order in which the key field descriptions are added must match the order of the key fields in the files for which this record format is meant.

Parameters:

name - The name of a field description that was already added to this object via addFieldDescription(). The name is case sensitive.

addPropertyChangeListener

public void addPropertyChangeListener(PropertyChangeListener listener)

Adds a listener to be notified when the value of any bound property is changed. The propertyChange method will be called.

Parameters:

listener - The PropertyChangeListener.

See Also:

removePropertyChangeListener(java.beans.PropertyChangeListener)

addRecordDescriptionListener

public void addRecordDescriptionListener(RecordDescriptionListener listener)

Adds a listener to be notified when a RecordDescriptionEvent is fired.

Parameters:

listener - The RecordDescriptionListener.

See Also:

removeRecordDescriptionListener(com.ibm.as400.access.RecordDescriptionListener)

addVetoableChangeListener

public void addVetoableChangeListener(VetoableChangeListener listener)

Adds a listener to be notified when the value of any constrained property is changed. The vetoableChange method will be called.

Parameters:

listener - The VetoableChangeListener.

See Also:

removeVetoableChangeListener(java.beans.VetoableChangeListener)

getDelimiter

public char getDelimiter()

Returns the delimiter. The delimiter is the character used to separate variable length fields when the record is written using the line data record writer class. This value is only valid when the record format type is VARIABLE_LAYOUT_LENGTH.

Returns:

The delimiter.

getFieldDescription

public FieldDescription getFieldDescription(int index)

Returns the field description at the specified index.

Parameters:

index - The index of the field description. The index must be in the range zero to getNumberOfFields() - 1.

Returns:

The field description.

getFieldDescription

public FieldDescription getFieldDescription(String name)

Returns the field description with the specified name.

Parameters:

name - The name of the field description. The name is case sensitive.

Returns:

The field description.

getFieldDescriptions

public FieldDescription[] getFieldDescriptions()

Returns the field descriptions that make up this object.

Returns:

The field descriptions. An array of size zero is returned if no fields have been added to this object.

getFieldNames

public String[] getFieldNames()

Returns the names of the field descriptions that make up this record format.

Returns:

The names of the field descriptions. An array of size zero is returned if no fields have been added to this object.

getIndexOfFieldName

public int getIndexOfFieldName(String name)

Returns the index of the field description named name.

Parameters:

name - The name of the field description. The name is case sensitive.

Returns:

The index of the field description.

getIndexOfKeyFieldName

public int getIndexOfKeyFieldName(String name)

Returns the index of the field description of the key field named name.

Parameters:

name - The name of the key field description. The name is case sensitive.

Returns:

The index of the key field description. This is the index of the key field description in the key field descriptions for this object. It is not the index of the field description in the field descriptions for this object.

getKeyFieldDescription

public FieldDescription getKeyFieldDescription(int index)

Returns the field description of the key field at the specified index.

Parameters:

index - The index of the key field description in the key field descriptions for this object.

Returns:

The key field description.

getKeyFieldDescription

public FieldDescription getKeyFieldDescription(String name)

Returns the field description of the key field with the specified name.

Parameters:

name - The name of the key field description. The name is case sensitive.

Returns:

The key field description.

getKeyFieldDescriptions

public FieldDescription[] getKeyFieldDescriptions()

Returns the key field descriptions that make up this object.

Returns:

The key field descriptions.

getKeyFieldNames

public String[] getKeyFieldNames()

Returns the names of the field descriptions of the keys that make up this record format.

Returns:

The names of the key field descriptions. If no key field descriptions exist, an array of size 0 is returned.

getLengthDependency

public int getLengthDependency(int index)

Returns the index of the field description on which the field description at the specified index depends.

Parameters:

index - The index of the field description. The index must be in the range 0 to getNumberOfFields() - 1.

Returns:

The index of the field description on which the field description at the specified index depends. If index is not the index of a dependent field, -1 is returned.

getLengthDependency

public int getLengthDependency(String name)

Returns the index of the field description on which the field description with the specified name depends.

Parameters:

name - The name of the field description. The name is case sensitive.

Returns:

The index of the field description on which the field description with the specified name depends. If name is not the name of a dependent field, -1 is returned.

getName

public String getName()

Returns the name of this record format.

Returns:

The name of this record format. If the name has not been set, an empty string is returned.

getNewRecord

public Record getNewRecord()

Returns a new record based on this record format, which contains default values for the contents of the fields. The default values are determined as follows:

1. Use the value specified for the DFT keyword on the field description object for a particular field.
2. If no value was specified for the DFT keyword, use the default value from the AS400DataType object specified when constructing the field description object for a particular field.

Returns:

A record based on this record format. If no field descriptions have been added to this object, null is returned.

getNewRecord

public Record getNewRecord(String recordName)

Returns a new record based on this record format, which contains default values for the contents of the fields. The default values are determined as follows:

1. Use the value specified for the DFT keyword on the field description object for a particular field.
2. If no value was specified for the DFT keyword, use the default value from the AS400DataType object specified when constructing the field description object for a particular field.

Parameters:

recordName - The name to assign to the Record object being returned.

Returns:

A record based on this record format. If no field descriptions have been added to this object, null is returned.

getNewRecord

public Record getNewRecord(byte[] contents)
                    throws UnsupportedEncodingException

Returns a new record based on this record format, which contains data from the specified byte array.

Parameters:

contents - The data with which to initialize the contents of the record. The length of contents must be greater than zero.

Returns:

A record based on this record format. If no field descriptions have been added to this object, null is returned.

Throws:

UnsupportedEncodingException - If an error occurs during conversion.

getNewRecord

public Record getNewRecord(byte[] contents,
                           String recordName)
                    throws UnsupportedEncodingException

Returns a new record based on this record format, which contains data from the specified byte array.

Parameters:

contents - The data with which to initialize the contents of the record. The length of contents must be greater than zero.

recordName - The name to assign to the Record object being returned.

Returns:

A record based on this record format. If no field descriptions have been added to this object, null is returned.

Throws:

UnsupportedEncodingException - If an error occurs during conversion.

getNewRecord

public Record getNewRecord(byte[] contents,
                           int offset)
                    throws UnsupportedEncodingException

Returns a new record based on this record format, which contains data from the specified byte array.

Parameters:

contents - The data with which to initialize the contents of the record. The length of contents must be greater than zero.

offset - The offset in contents at which to start. The offset cannot be less than zero.

Returns:

A record based on this record format. If no field descriptions have been added to this object, null is returned.

Throws:

UnsupportedEncodingException - If an error occurs during conversion.

getNewRecord

public Record getNewRecord(byte[] contents,
                           int offset,
                           String recordName)
                    throws UnsupportedEncodingException

Returns a new record based on this record format, which contains data from the specified byte array.

Parameters:

contents - The data with which to initialize the contents of the record. The length of contents must be greater than zero.

offset - The offset in contents at which to start. The offset cannot be less than zero.

recordName - The name to assign to the Record object being returned.

Returns:

A record based on this record format. If no field descriptions have been added to this object, null is returned.

Throws:

UnsupportedEncodingException - If an error occurs during conversion.

getNumberOfFields

public int getNumberOfFields()

Returns the number of field descriptions in this record format.

Returns:

The number of field descriptions in this record format.

getNumberOfKeyFields

public int getNumberOfKeyFields()

Returns the number of key field descriptions in this record format.

Returns:

The number of key field descriptions in this record format.

getOffsetDependency

public int getOffsetDependency(int index)

Returns the index of the field description on which the field description at the specified index depends.

Parameters:

index - The index of the field description. The index must be in the range 0 to getNumberOfFields() - 1.

Returns:

The index of the field description on which the field description at the specified index depends. If index is not the index of a dependent field, -1 is returned.

getOffsetDependency

public int getOffsetDependency(String name)

Returns the index of the field description on which the field description with the specified name depends.

Parameters:

name - The name of the field description. The name is case sensitive.

Returns:

The index of the field description on which the field description with the specified name depends. If name is not the name of a dependent field, -1 is returned.

getRecordFormatID

public String getRecordFormatID()

Returns the record format ID. The record format ID corresponds to a record format ID within a page definition defined on the system.

Returns:

The record format ID.

getRecordFormatType

public int getRecordFormatType()

Returns the record format type.

Returns:

The record format type.

removePropertyChangeListener

public void removePropertyChangeListener(PropertyChangeListener listener)

Removes a listener from the change list. If the listener is not on the list, do nothing.

Parameters:

listener - The PropertyChangeListener.

See Also:

addPropertyChangeListener(java.beans.PropertyChangeListener)

removeRecordDescriptionListener

public void removeRecordDescriptionListener(RecordDescriptionListener listener)

Removes a listener from the record description listeners list. If the listener is not on the list, do nothing.

Parameters:

listener - The RecordDescriptionListener.

See Also:

addRecordDescriptionListener(com.ibm.as400.access.RecordDescriptionListener)

removeVetoableChangeListener

public void removeVetoableChangeListener(VetoableChangeListener listener)

Removes a listener from the veto change listeners list. If the listener is not on the list, do nothing.

Parameters:

listener - The VetoableChangeListener.

See Also:

addVetoableChangeListener(java.beans.VetoableChangeListener)

setDelimiter

public void setDelimiter(char delimiter)

Sets the delimiter. The delimiter is the character used to separate variable length fields when the record is written using the line data record writer class. This value is only valid when the record format type is VARIABLE_LAYOUT_LENGTH.

Parameters:

delimiter - The delimiter.

setLengthDependency

public void setLengthDependency(int dependentField,
                                int fieldDependedOn)

Sets the field on which a dependent field depends. Both fields must have been added already to this RecordFormat. The fieldDependedOn must have been added prior to adding the dependentField.

Parameters:

dependentField - The index of the dependent field. The dependentField must be in the range 1 to getNumberOfFields() - 1.

fieldDependedOn - The index of a field on which this field depends. The fieldDependedOn must be in the range 0 to dependentField.

setLengthDependency

public void setLengthDependency(String dependentField,
                                String fieldDependedOn)

Sets the field on which a dependent field depends. Both fields must have been added already to this RecordFormat. The fieldDependedOn must have been added prior to adding the dependentField. The names of the fields are case sensitive.

Parameters:

dependentField - The name of the dependent field.

fieldDependedOn - The name of a field on which this field depends. The index of fieldDependedOn in this RecordFormat must be less than the index of dependentField.

setName

public void setName(String name)
             throws PropertyVetoException

Sets the name of this record format.

Parameters:

name - The name of this record format. The name is converted to uppercase by this method.

Throws:

PropertyVetoException - If a change is vetoed.

setOffsetDependency

public void setOffsetDependency(int dependentField,
                                int fieldDependedOn)

Sets the field on which a dependent field depends. Both fields must have been added already to this RecordFormat. The fieldDependedOn must have been added prior to adding the dependentField.

Parameters:

dependentField - The index of the dependent field. The dependentField must be in the range 1 to getNumberOfFields() - 1.

fieldDependedOn - The index of a field on which this field depends. The fieldDependedOn must be in the range 0 to dependentField.

setOffsetDependency

public void setOffsetDependency(String dependentField,
                                String fieldDependedOn)

Sets the field on which a dependent field depends. Both fields must have been added already to this RecordFormat. The fieldDependedOn must have been added prior to adding the dependentField. The names of the fields are case sensitive.

Parameters:

dependentField - The name of the dependent field.

fieldDependedOn - The name of a field on which this field depends. The index of fieldDependedOn in this RecordFormat must be less than the index of dependentField.

setRecordFormatID

public void setRecordFormatID(String id)

Sets the record format ID. The length of the record format ID must be 10 characters or less. The record format ID corresponds to a record format ID within a page definition on the system. If the record format ID is less than 10 characters, it is padded to 10 characters in length with spaces.

Parameters:

id - The record format ID.

setRecordFormatType

public void setRecordFormatType(int type)

Sets the record format type. Valid values are FIXED_LAYOUT_LENGTH and VARIABLE_LAYOUT_LENGTH. This attribute is only valid when using the line record writer class.

Parameters:

type - The record format type.