Package com.ibm.as400.access

Class Record

java.lang.Object

com.ibm.as400.access.Record

All Implemented Interfaces:

Serializable

public class Record
extends Object
implements Serializable

The Record class represents the data described by a RecordFormat object. It can represent:

• An entry in a data queue.
• The parameter data provided to or returned by a program call.
• A record to be written to or read from a file on the system.
• Any data returned from the system that needs to be converted between IBM i format and Java format.

Record objects generate the following events:

• RecordDescriptionEvent
  The events fired are:
  • fieldModified()
• PropertyChangeEvent
• VetoableChangeEvent

Examples

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

See Also:

Serialized Form

Constructor Summary

Constructors

Constructor	Description
Record()	Constructs a Record object.
Record(RecordFormat recordFormat)	Constructs a Record object.
Record(RecordFormat recordFormat, byte[] contents)	Constructs a Record object.
Record(RecordFormat recordFormat, byte[] contents, int offset)	Constructs a Record object.
Record(RecordFormat recordFormat, byte[] contents, int offset, String recordName)	Constructs a Record object.
Record(RecordFormat recordFormat, byte[] contents, String recordName)	Constructs a Record object.
Record(RecordFormat recordFormat, String recordName)	Constructs a Record object.

Method Summary

Modifier and Type	Method	Description
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.
boolean	equals(Object obj)	Tests this Record object for equality with the given object.
byte[]	getContents()	Returns the contents of this record as a byte array of IBM i data.
void	getContents(OutputStream out)	Writes the contents of this record to the specified output stream.
Object	getField(int index)	Returns the value of the field by index.
Object	getField(String name)	Returns the value of the field by name.
byte[]	getFieldAsBytes(int index)	Returns the value of the field by index, as an unconverted byte array.
byte[]	getFieldAsBytes(String name)	Returns the value of the field by name, as an unconverted byte array.
Object[]	getFields()	Returns the values of the fields in the record.
Object[]	getKeyFields()	Returns the values of the key fields in the record.
byte[]	getKeyFieldsAsBytes()	Returns the values of the key fields in a byte array.
int	getNumberOfFields()	Returns the number of fields in this record.
int	getNumberOfKeyFields()	Returns the number of key fields in this record.
RecordFormat	getRecordFormat()	Returns the record format for this record.
int	getRecordLength()	Returns the record length of this record.
String	getRecordName()	Returns the record name for this record.
int	getRecordNumber()	Returns the record number of this record.
long	getRecordNumberLong()	Returns the record number in long type of this record.
int	hashCode()	Returns a hash code value for this Record.
boolean	isNullField(int index)	Indicates if the field is null.
boolean	isNullField(String name)	Indicates if the field is null.
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	setContents(byte[] contents)	Sets the contents of this record from the specified byte array.
void	setContents(byte[] contents, int offset)	Sets the contents of this record from the specified byte array.
void	setContents(InputStream in)	Sets the contents of this record from the specified input stream.
void	setField(int index, Object value)	Sets the contents of the field at index to value.
void	setField(String name, Object value)	Sets the contents of the field with the specified name to value.
void	setRecordFormat(RecordFormat recordFormat)	Sets the record format for this record.
void	setRecordName(String name)	Sets the name for this record.
void	setRecordNumber(int recordNumber)	Sets the record number of this record.
void	setRecordNumberLong(long recordNumber)	Sets the record number with long type of this record.
String	toString()	Returns the contents of this record formatted as a String.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

Record

public Record()

Constructs a Record object.

Record

public Record(RecordFormat recordFormat)

Constructs a Record object. It uses the RecordFormat specified. The contents of the record will be initialized to their default values. The default values are determined as follows:

1. Use the value specified for the DFT keyword on the FieldDescription object contained in the RecordFormat 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 FieldDescription object for a particular field.

Parameters:

recordFormat - Describes the contents of this record.

See Also:

RecordFormat

Record

public Record(RecordFormat recordFormat,
              String recordName)

Constructs a Record object. It uses the record's name and RecordFormat specified. The contents of the record will be initialized to their default values. The default values are determined as follows:

1. Use the value specified for the DFT keyword on the FieldDescription 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 FieldDescription object for a particular field.

Parameters:

recordFormat - Describes the contents of this record.

recordName - The name to assign to the record.

Record

public Record(RecordFormat recordFormat,
              byte[] contents)
       throws UnsupportedEncodingException

Constructs a Record object. It uses the specified RecordFormat and a byte array with which to initialize the contents of the record.

Parameters:

recordFormat - Describes the contents of this record.

contents - The contents to which to initialize the record.
Note: When using this object for the record level access classes, if isVariableLength() returns true for a field, the first two bytes of the data provided for that field must contain the length of the valid data. However, the number of bytes provided for the data for the field must equal the maximum field length for the field.

Throws:

UnsupportedEncodingException - If an error occurs when converting the IBM i data to a Java Object.

Record

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

Constructs a Record object. It uses the specified the RecordFormat, a byte array from which to initialize the contents of the record and the name of the record.

Parameters:

recordFormat - Describes the contents of this record.

contents - The contents to which to initialize the record.
Note: When using this object for the record level access classes, if isVariableLength() returns true for a field, the first two bytes of the data provided for that field must contain the length of the valid data. However, the number of bytes provided for the data for the field must equal the maximum field length for the field.

recordName - The name to assign to the record.

Throws:

UnsupportedEncodingException - If an error occurs when converting the IBM i data to a Java Object.

Record

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

Constructs a Record object. It uses the specified RecordFormat and a byte array from which to initialize the contents of the record.

Parameters:

recordFormat - Describes the contents of this record. The recordFormat must contain at least one field description.

contents - The contents to which to initialize the record.
Note: When using this object for the record level access classes, if isVariableLength() returns true for a field, the first two bytes of the data provided for that field must contain the length of the valid data. However, the number of bytes provided for the data for the field must equal the maximum field length for the field.

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

Throws:

UnsupportedEncodingException - If an error occurs when converting the IBM i data to a Java Object.

Record

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

Constructs a Record object. It uses the specified RecordFormat, a byte array from which to initialize the record's contents and the record's name.

Parameters:

recordFormat - Describes the contents of this record.

contents - The contents to which to initialize the record.
Note: When using this object for the record level access classes, if isVariableLength() returns true for a field, the first two bytes of the data provided for that field must contain the length of the valid data. However, the number of bytes provided for the data for the field must equal the maximum field length for the field.

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

recordName - The name to assign to the record.

Throws:

UnsupportedEncodingException - If an error occurs when converting the IBM i data to a Java Object.

Method Detail

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

equals

public boolean equals(Object obj)

Tests this Record object for equality with the given object.

Overrides:

equals in class Object

Parameters:

obj - The Object to compare.

Returns:

true if obj is a Record object and its record length, record number, record name, dependent fields, field values, and key field values equal this Record's; false otherwise. Since there are so many pieces of data that determine whether or not one Record equals another, the programmer may also want to consider using Record.toString() and comparing the Strings for equality.

getContents

public byte[] getContents()
                   throws CharConversionException,
                          UnsupportedEncodingException

Returns the contents of this record as a byte array of IBM i data. Each field's contents will be placed into the byte array based on the field description for the field that is provided by the record format specified on construction of this object. The data type object for the field description will be used to do any necessary conversion of the contents of the field to the byte array.
Note: If a field is a variable-length field, the first two bytes of data for the field contain the length of the valid data for the field. However, the number of bytes provided for the field is the maximum length of the field as specified by the FieldDescription object for the field in the record format for this object.
The record format for the record must be set prior to invoking this method.

Returns:

The contents of this record.

Throws:

CharConversionException - If an error occurs when converting the contents of a field to IBM i data.

UnsupportedEncodingException - If an error occurs when converting the contents of a field to IBM i data.

See Also:

Record(com.ibm.as400.access.RecordFormat), setRecordFormat(com.ibm.as400.access.RecordFormat)

getContents

public void getContents(OutputStream out)
                 throws IOException

Writes the contents of this record to the specified output stream. Each field's contents will be written to out based on the field description for the field that is provided by the record format specified on construction of this object. The data type object for the field description will be used to do any necessary conversion of the contents of the field.
Note: If a field is a variable-length field, the first two bytes of data for the field contain the length of the valid data for the field. However, the number of bytes provided for the field is the maximum length of the field as specified by the FieldDescription object for the field in the record format for this object.
The record format for the record must be set prior to invoking this method.

Parameters:

out - The stream to which to write the contents of the record.

Throws:

IOException - If an I/O error occurs while communicating with the system.

See Also:

Record(com.ibm.as400.access.RecordFormat), setRecordFormat(com.ibm.as400.access.RecordFormat)

getField

public Object getField(int index)
                throws UnsupportedEncodingException

Returns the value of the field by index.
The record format for the record must be set prior to invoking this method.

Parameters:

index - The ordinal position of the field in the record. This value must be between 0 and getNumberOfFields() - 1 inclusive.

Returns:

The contents of the requested field.

Throws:

UnsupportedEncodingException - If an error occurs when converting the IBM i data to a Java Object.

See Also:

Record(com.ibm.as400.access.RecordFormat), setRecordFormat(com.ibm.as400.access.RecordFormat)

getField

public Object getField(String name)
                throws UnsupportedEncodingException

Returns the value of the field by name.
The record format for the record must be set prior to invoking this method.

Parameters:

name - The name of the field.

Returns:

The contents of the requested field.

Throws:

UnsupportedEncodingException - If an error occurs when converting the IBM i data to a Java Object.

See Also:

Record(com.ibm.as400.access.RecordFormat), setRecordFormat(com.ibm.as400.access.RecordFormat)

getFieldAsBytes

public byte[] getFieldAsBytes(int index)

Returns the value of the field by index, as an unconverted byte array.
The record format for the record must be set prior to invoking this method.

Parameters:

index - The ordinal position of the field in the record. This value must be between 0 and getNumberOfFields() - 1 inclusive.

Returns:

The unconverted contents of the requested field.

See Also:

Record(com.ibm.as400.access.RecordFormat), setRecordFormat(com.ibm.as400.access.RecordFormat)

getFieldAsBytes

public byte[] getFieldAsBytes(String name)

Returns the value of the field by name, as an unconverted byte array.
The record format for the record must be set prior to invoking this method.

Parameters:

name - The name of the field.

Returns:

The unconverted contents of the requested field.

See Also:

Record(com.ibm.as400.access.RecordFormat), setRecordFormat(com.ibm.as400.access.RecordFormat)

getFields

public Object[] getFields()
                   throws UnsupportedEncodingException

Returns the values of the fields in the record.

Returns:

The values of the fields in the record. An array of size zero is returned if the record format has not been set.

Throws:

UnsupportedEncodingException - If an error occurs when converting the IBM i data to a Java Object.

getKeyFields

public Object[] getKeyFields()
                      throws UnsupportedEncodingException

Returns the values of the key fields in the record.

Returns:

The values of the key fields in the record. An array of length 0 is returned if the record format has not been set or if no key fields exist.

Throws:

UnsupportedEncodingException - If an error occurs when converting the IBM i data to a Java Object.

getKeyFieldsAsBytes

public byte[] getKeyFieldsAsBytes()

Returns the values of the key fields in a byte array.

Returns:

The values of the key fields in a byte array. A byte array of length 0 is returned if the record format has not been set or if no key fields exist.

getNumberOfFields

public int getNumberOfFields()

Returns the number of fields in this record.

Returns:

The number of fields in this record. Zero is returned if the record format has not been set.

getNumberOfKeyFields

public int getNumberOfKeyFields()

Returns the number of key fields in this record.

Returns:

The number of key fields in this record. Zero is returned if the record format has not been set.

getRecordFormat

public RecordFormat getRecordFormat()

Returns the record format for this record.

Returns:

The record format for this record. If the record format has not been set, null is returned.

getRecordLength

public int getRecordLength()

Returns the record length of this record.

Returns:

The record length of this record. Zero is returned if the record format for this object has not been set.

getRecordName

public String getRecordName()

Returns the record name for this record.

Returns:

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

getRecordNumber

public int getRecordNumber()

Returns the record number of this record. This method only pertains to the record level access classes.

Returns:

The record number of this record. Zero is returned if no record number has been set.

getRecordNumberLong

public long getRecordNumberLong()

Returns the record number in long type of this record. This method only pertains to the record level access classes.

Returns:

The record number of this record. Zero is returned if no record number has been set.

hashCode

public int hashCode()

Returns a hash code value for this Record. This is useful if Record objects need to be placed into Hashtables.

Overrides:

hashCode in class Object

Returns:

The hash code.

isNullField

public boolean isNullField(int index)

Indicates if the field is null.
The record format for the record must be set prior to invoking this method.

Parameters:

index - The index of the field. The index must be between 0 and getNumberOfFields() - 1.

Returns:

true if the field is null; false otherwise.

See Also:

Record(com.ibm.as400.access.RecordFormat), setRecordFormat(com.ibm.as400.access.RecordFormat)

isNullField

public boolean isNullField(String name)

Indicates if the field is null.
The record format for the record must be set prior to invoking this method.

Parameters:

name - The name of the field.

Returns:

true if the field is null; false otherwise.

See Also:

Record(com.ibm.as400.access.RecordFormat), setRecordFormat(com.ibm.as400.access.RecordFormat)

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)

setContents

public void setContents(byte[] contents)
                 throws UnsupportedEncodingException

Sets the contents of this record from the specified byte array. The contents of each field will be set from contents based on the field description for the field that is provided by the record format specified on construction of this object. The data type object for the field description will be used to do any necessary conversion of the data from the byte array.
Note: When using this object for the record level access classes, if isVariableLength() returns true for a field, the first two bytes of the data provided for that field must contain the length of the valid data. However, the number of bytes provided for the data for the field must equal the maximum field length for the field.
The record format for the record must be set prior to invoking this method.

Parameters:

contents - The data with which to set the contents of this record.

Throws:

UnsupportedEncodingException - If an error occurs when converting the IBM i data to a Java Object.

See Also:

Record(com.ibm.as400.access.RecordFormat), setRecordFormat(com.ibm.as400.access.RecordFormat)

setContents

public void setContents(byte[] contents,
                        int offset)
                 throws UnsupportedEncodingException

Sets the contents of this record from the specified byte array. The contents of each field will be set from contents based on the field description for the field that is provided by the record format specified on construction of this object. The data type object for the field description will be used to do any necessary conversion of the data from the byte array.
Note: When using this object for the record level access classes, if isVariableLength() returns true for a field, the first two bytes of the data provided for that field must contain the length of the valid data. However, the number of bytes provided for the data for the field must equal the maximum field length for the field.
The record format for the record must be set prior to invoking this method.

Parameters:

contents - The data with which to set the contents of this record.

offset - The offset in contents at which to start.

Throws:

UnsupportedEncodingException - If an error occurs when converting the IBM i data to a Java Object.

See Also:

Record(com.ibm.as400.access.RecordFormat), setRecordFormat(com.ibm.as400.access.RecordFormat)

setContents

public void setContents(InputStream in)
                 throws IOException

Sets the contents of this record from the specified input stream. The contents of each field will be set from in based on the field description for the field that is provided by the record format specified on construction of this object. The data type object for the field description will be used to do any necessary conversion of the data from the input stream.
Note: When using this object for the record level access classes, if isVariableLength() returns true for a field, the first two bytes of the data provided for that field must contain the length of the data.
The record format for the record must be set prior to invoking this method.

Parameters:

in - The stream from which to read the data.

Throws:

IOException - If an I/O error occurs while communicating with the system.

See Also:

Record(com.ibm.as400.access.RecordFormat), setRecordFormat(com.ibm.as400.access.RecordFormat)

setField

public void setField(int index,
                     Object value)

Sets the contents of the field at index to value.
The record format for the record must be set prior to invoking this method.

Parameters:

index - The position in this record of the field whose contents are to be set. The index must be between 0 and getNumberOfFields() - 1.

value - The value to which to set the contents of the field. Specify null for value to indicate that the field is null.

See Also:

Record(com.ibm.as400.access.RecordFormat), setRecordFormat(com.ibm.as400.access.RecordFormat)

setField

public void setField(String name,
                     Object value)

Sets the contents of the field with the specified name to value.
The record format for the record must be set prior to invoking this method.

Parameters:

name - The name of the field whose contents are to be set.

value - The value to which to set the contents of the field. Specify null for value to indicate that the field is null.

See Also:

Record(com.ibm.as400.access.RecordFormat), setRecordFormat(com.ibm.as400.access.RecordFormat)

setRecordFormat

public void setRecordFormat(RecordFormat recordFormat)
                     throws PropertyVetoException

Sets the record format for this record.

Parameters:

recordFormat - The record format for this record.

Throws:

PropertyVetoException - If a change is vetoed.

setRecordName

public void setRecordName(String name)
                   throws PropertyVetoException

Sets the name for this record.

Parameters:

name - The name for this record.

Throws:

PropertyVetoException - If a change is vetoed.

setRecordNumber

public void setRecordNumber(int recordNumber)
                     throws PropertyVetoException

Sets the record number of this record. This method only pertains to the record level access class SequentialFile when a write or update by record number is being done.

Parameters:

recordNumber - The record number of this record. The recordNumber must be greater than 0.

Throws:

PropertyVetoException - If a change is vetoed.

setRecordNumberLong

public void setRecordNumberLong(long recordNumber)
                         throws PropertyVetoException

Sets the record number with long type of this record.

Parameters:

recordNumber -

Throws:

PropertyVetoException - If the recipient wishes the property change to be rolled back.

toString

public String toString()

Returns the contents of this record formatted as a String. If a field is null, "null" is substituted for the contents of the field in the string representation of this record.

Overrides:

toString in class Object

Returns:

The contents of this record. The empty string is returned if the record has not contents.