ewe.database
Class Record

java.lang.Object
  ewe.database.Record

All Implemented Interfaces:

DatabaseTypes

public class Record

extends Object

implements DatabaseTypes

Field Summary

Fields inherited from interface ewe.database.DatabaseTypes

BOOLEAN, BYTE_ARRAY, CREATED_FIELD, DATE, DATE_TIME, DECIMAL, DOUBLE, FIRST_SPECIAL_FIELD, FLAG_SYNCHRONIZED, FLAGS_FIELD, INTEGER, JAVA_OBJECT, LONG, MAX_ID, MODIFIED_BY_FIELD, MODIFIED_FIELD, NAME_FIELD, OBJECT_BYTES_FIELD, OBJECT_TEXT_FIELD, OID_FIELD, reservedFieldHeaders, reservedFieldIDs, reservedFieldNames, reservedFieldTypes, SORT_DATE_ONLY, SORT_IGNORE_CASE, SORT_TIME_ONLY, SORT_UNKNOWN_IS_GREATER_THAN_KNOWN, SORT_UNKNOWN_IS_LESS_THAN_KNOWN, STRING, TIME, TIMESTAMP

Constructor Summary

Record(Database db)
Create a Record for use with the specified Database.

Record(Database db, int[] fields)
Create a Record for use with the specified Database using but where only the specified fields will be read in from DatabaseEntry objects.

Method Summary

Object	copyData(Object theData) Return a copy of the data returned by getField() - unless that data is of type JAVA_OBJECT in which case a copy will only be returned if it implements ewe.util.Copyable.
Database	getDatabase()
Object	getField(int fieldID) Call this after a readFrom().
int[]	getFields() Return the fields that are being used with this Record.
int	getID(String fieldName) Find the ID of a specified field given its name - throwing an IllegalArgumentException if the ID is not found.
void	readFrom(DatabaseEntry de) Read the field values from the DatabaseEntry into the data objects being kept by the Record object.
void	reset() This clears the data held by the Record, but still keeps the data objects used to hold the data.
void	selectFields(int[] fields) Select the fields to be used by the Record - each of which must be a valid field for the Database used by the Record.
Object	setField(int fieldID) This method is used to retrieve the data object used to wrap the field data, and at the same time mark that field as having its data set, for a later writeTo() operation.
void	setField(int fieldID, Object fieldData) This method should normally be used only if the field type is JAVA_OBJECT.
Hashtable	toHashtable() Place copies of the field values in the Record into a new Hashtable, keyed by the field name.
Hashtable	toHashtable(Hashtable destination, boolean copyData) Place the field values (or copies of the values) in the Record into a Hashtable, keyed by the field name.
PropertyList	toPropertyList() Place copies of the field values in the Record into a new PropertyList, keyed by the field name.
PropertyList	toPropertyList(PropertyList destination, boolean copyData) Place the field values (or copies of the values) in the Record into a PropertyList, keyed by the field name.
void	transferTo(int[] sourceFields, int[] destFields, DatabaseEntry dest) Copy a set of fields from this Record into the destination DatabaseEntry (which may be from a different Database) into fields with IDs specified by destFields, and which are of the same type as the source fields.
void	writeTo(DatabaseEntry de) Set the field values int the DatabaseEntry from the set data objects being kept by the Record object.
void	zero() This sets all the data held by the Record to a zero value.
void	zeroData(Object theData) Sets the data value to whatever is considered to be a zero value.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, toString

Constructor Detail

Record

public Record(Database db)

Create a Record for use with the specified Database. All fields will be read in from DatabaseEntry objects.

Record

public Record(Database db,
              int[] fields)

Create a Record for use with the specified Database using but where only the specified fields will be read in from DatabaseEntry objects.

Method Detail

getDatabase

public Database getDatabase()

selectFields

public void selectFields(int[] fields)
                  throws IllegalArgumentException

Select the fields to be used by the Record - each of which must be a valid field for the Database used by the Record.

Throws:

IllegalArgumentException

getFields

public int[] getFields()

Return the fields that are being used with this Record.

reset

public void reset()

This clears the data held by the Record, but still keeps the data objects used to hold the data. This is used to reset a Record before setting individual fields prior to a writeTo() operation. You would probably prefer to use the zero() method instead as this initializes all fields with what is considered zero data (e.g. Strings are set empty, decimals are set to zero, etc).

zero

public void zero()

This sets all the data held by the Record to a zero value. This is used to reset a Record before setting individual fields prior to a writeTo() operation.

setField

public Object setField(int fieldID)
                throws IllegalArgumentException

This method is used to retrieve the data object used to wrap the field data, and at the same time mark that field as having its data set, for a later writeTo() operation. After calling this method you should set the object data appropriately.

Parameters:

fieldID - the field ID to look for.

Returns:

the data object representing the field read in by readFrom().

Throws:

IllegalArgumentException - if the fieldID is not being read in by this Record.

setField

public void setField(int fieldID,
                     Object fieldData)
              throws IllegalArgumentException

This method should normally be used only if the field type is JAVA_OBJECT. It sets the field data and at the same time mark that field as having its data set, for a later writeTo() operation.

Parameters:

fieldID - the field ID to look for.

fieldData - data object representing the field read in by readFrom().

Throws:

IllegalArgumentException - if the fieldID is not being read in by this Record.

readFrom

public void readFrom(DatabaseEntry de)

Read the field values from the DatabaseEntry into the data objects being kept by the Record object. Any field that is being read by the Record but is not present in the DatabaseEntry will have a null data value associated with it. All field with values in the DatabaseEntries are read into their wrapper objects.

writeTo

public void writeTo(DatabaseEntry de)

Set the field values int the DatabaseEntry from the set data objects being kept by the Record object.

getField

public Object getField(int fieldID)
                throws IllegalArgumentException

Call this after a readFrom(). It will return the value of the specified fieldID. Note that this value is only valid until the next call of readFrom() - unless that value is of type JAVA_OBJECT, in which case it will continue to be valid.

To keep a persistent copy of the data call copyData(Object data). Calling copyData() on an encoded JAVA_OBJECT is safe, it will simply return the same value.

Parameters:

fieldID - the field ID to look for.

Returns:

the data object representing the field read in by readFrom(). If there was no value for the field in the DatabaseEntry, null will be returned.

Throws:

IllegalArgumentException - if the fieldID is not being read in by this Record.

getID

public int getID(String fieldName)
          throws IllegalArgumentException

Find the ID of a specified field given its name - throwing an IllegalArgumentException if the ID is not found.

Throws:

IllegalArgumentException

copyData

public Object copyData(Object theData)

Return a copy of the data returned by getField() - unless that data is of type JAVA_OBJECT in which case a copy will only be returned if it implements ewe.util.Copyable.

zeroData

public void zeroData(Object theData)

Sets the data value to whatever is considered to be a zero value.

transferTo

public void transferTo(int[] sourceFields,
                       int[] destFields,
                       DatabaseEntry dest)
                throws IllegalArgumentException

Copy a set of fields from this Record into the destination DatabaseEntry (which may be from a different Database) into fields with IDs specified by destFields, and which are of the same type as the source fields.

Parameters:

sourceFields - An array of Field IDs which must be within the field list for this Record object.

destFields - An array of Field IDs, equal in length to the sourceFields array but with values which correspond to destination fields in the destination DatabaseEntry.

dest - the destination DatabaseEntry (which may be from a different Database).

Throws:

IllegalArgumentException - if any of the sourceFields IDs is not in this Record or if any of the destination field IDs are invalid or of the wrong type.

toHashtable

public Hashtable toHashtable(Hashtable destination,
                             boolean copyData)

Place the field values (or copies of the values) in the Record into a Hashtable, keyed by the field name.

Parameters:

destination - the destination Hashtable, or null to create a new one.

copyData - set this true to save copies of the field data.

Returns:

the destination Hashtable or a new Hashtable.

toHashtable

public Hashtable toHashtable()

Place copies of the field values in the Record into a new Hashtable, keyed by the field name.

toPropertyList

public PropertyList toPropertyList(PropertyList destination,
                                   boolean copyData)

Place the field values (or copies of the values) in the Record into a PropertyList, keyed by the field name.

Parameters:

destination - the destination PropertyList, or null to create a new one.

copyData - set this true to save copies of the field data.

Returns:

the destination PropertyList or a new PropertyList.

toPropertyList

public PropertyList toPropertyList()

Place copies of the field values in the Record into a new PropertyList, keyed by the field name.