PIRL.Database
Class Fields_Map

java.lang.Object
  PIRL.Database.Fields_Map

public class Fields_Map
extends Object

A Fields_Map maps a list of field names in user specified order to the actual order of field names as returned from a database table query.

The Fields_Map relates two possible orderings of a list of field names: The actual order is the order of entries as they occur before being mapped. This is expected to be the order in which table record field entries are returned from a database query. The user order is the the order in which the user of table records expects the entries to be in after being mapped. The user order might be thought of as the logical order known to the user of the map as typically set by by pre-determined constant index values associated with known record field names.

The map is constructed by providing a list of field names in user order and a list of field names in actual order. Every user field name that is found in the actual field names list results in a mapping of that name from its index in the user order to its index in the actual order. User names that are not found in the list of actual field names are mapped to the no-index value. Field names are matched using either case sensitive or case insensitive comparison.

The map may be used to access a field entry from a record in actual order by specifying a field name or a user index.

Version:

1.13

Author:

Bradford Castalia, Drew Castalia - idaeim studio

Field Summary

boolean	Case_Sensitive Whether to use case sensitive field name matches.
static boolean	Case_Sensitive_Default The default for case sensitive field name matches.
static String	ID

Constructor Summary

Fields_Map(List<String> user_fields, List<String> actual_fields)
Constructs a Fields_Map that maps a List of field names in user index order to their index in a List of field names in actual (table record) order.

Fields_Map(List<String> user_fields, List<String> actual_fields, boolean case_sensitive)
Constructs a Fields_Map that maps a List of field names in user index order to their index in a List of field names in actual (table record) order.

Fields_Map(List<String> user_fields, String[] actual_fields)
Constructs a Fields_Map that maps a List of field names in user index order to their index in an array of field names in actual (table record) order.

Fields_Map(String[] user_fields, List<String> actual_fields)
Constructs a Fields_Map that maps an array of field names in user index order to their index in a List of field names in actual (table record) order.

Fields_Map(String[] user_fields, String[] actual_fields)
Constructs a Fields_Map that maps an array of field names in user index order to their index in an array of field names in actual (table record) order.

Fields_Map(String[] user_fields, String[] actual_fields, boolean case_sensitive)
Constructs a Fields_Map that maps an array of field names in user index order to their index in an array of field names in actual (table record) order.

Method Summary

Vector<String>	Actual_Fields() Gets a Vector of field names in actual index order.
Vector<String>	Actual_to_User(Vector<String> record) Remaps a record from actual table record order to user fields order.
Vector<String>	All_Actual_Fields() Gets a Vector of actual field names in unmapped order.
Vector<String>	All_User_Fields() Gets a Vector of all the user field names.
void	Confirm_Fields(List<String> field_names) Confirms that a list of user field names are all mapped to valid actual fields.
void	Confirm_Fields(String[] field_names) Confirms that a list of field names are all mapped to valid record locations.
String	entry(List<String> record, int field_number) Gets a field entry from a record corresponding to a user field number.
String	entry(List<String> record, String field_name) Gets a field entry from a record corresponding to a user field name.
int	index(int user_field_number) Maps a user field number to an actual record field number.
int	index(String user_field_name) Maps a user field name to an actual field number.
Vector<String>	Table_Fields() Deprecated.
String	toString() Gets the description of this Fields_Map.
Vector<String>	Unmapped_Actual_Fields() Gets a Vector of unmapped actual field names.
Vector<String>	User_Fields() Gets a Vector of field names in user index order.

Methods inherited from class java.lang.Object

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

Field Detail

ID

public static final String ID

See Also:

Constant Field Values

Case_Sensitive_Default

public static boolean Case_Sensitive_Default

The default for case sensitive field name matches.

The initial value is false;

Case_Sensitive

public boolean Case_Sensitive

Whether to use case sensitive field name matches.

: The case sensistive matching condition is set when the Field_Map is constructed and used by the constructor to assemble the map of user field name indexes to actual field name indexes. This condition is also used for user field name to actual field index and user field name to table record entry mapping. Changing the condition after the Field_Map has been constructed may produce inconsistent mapping results.

Constructor Detail

Fields_Map

public Fields_Map(List<String> user_fields,
                  List<String> actual_fields,
                  boolean case_sensitive)

Constructs a Fields_Map that maps a List of field names in user index order to their index in a List of field names in actual (table record) order.

User field names that are not found in the List of actual names map to a -1 index to indicate missing fields.

User field names are compared to actual field names using the default case sensitivity.

N.B.: The first actual field name that matches each user field name provides the mapping. If the actual field names list contains duplicate entries, only the first entry will be mapped. Likewise, if case insensitive matching is being done only the first actual name that matches a user name regardless of case is mapped.

N.B.: A field names list may contain null entries. A null name always matches a null name. A non-null name never matches a null name.

Parameters:

user_fields - A List of user field name Strings to be mapped.

actual_fields - A List of field name Strings in actual (record) order; as returned in the first record of a Database.Select operation.

case_sensitive - If true, user field names are compared to actual field names with a case sensitive match; otherwise a case insensitive match is used.

Throws:

IllegalArgumentException - If either argument is null.

Fields_Map

public Fields_Map(List<String> user_fields,
                  List<String> actual_fields)

Constructs a Fields_Map that maps a List of field names in user index order to their index in a List of field names in actual (table record) order.

User field names that are not found in the List of actual names map to a -1 index to indicate missing fields.

User field names are compared to actual field names using the default case sensitivity.

N.B.: The first actual field name that matches each user field name provides the mapping. If the actual field names list contains duplicate entries, only the first entry will be mapped. Likewise, if case insensitive matching is being done only the first actual name that matches a user name regardless of case is mapped.

N.B.: A field names list may contain null entries. A null name always matches a null name. A non-null name never matches a null name.

Parameters:

user_fields - A List of user field name Strings to be mapped.

actual_fields - A List of field name Strings in actual (record) order; as returned in the first record of a Database.Select operation.

Throws:

IllegalArgumentException - If either argument is null.

Fields_Map

public Fields_Map(String[] user_fields,
                  String[] actual_fields,
                  boolean case_sensitive)

Constructs a Fields_Map that maps an array of field names in user index order to their index in an array of field names in actual (table record) order.

User field names that are not found in the array of actual names map to a -1 index to indicate missing fields.

N.B.: The first actual field name that matches each user field name provides the mapping. If the actual field names list contains duplicate entries, only the first entry will be mapped. Likewise, if case insensitive matching is being done only the first actual name that matches a user name regardless of case is mapped.

N.B.: A field names list may contain null entries. A null name always matches a null name. A non-null name never matches a null name.

Parameters:

user_fields - An array of user field name Strings to be mapped.

actual_fields - An array of field name Strings in actual (tablae record) order; as returned in the first record of a Database.Select operation.

case_sensitive - If true, user field names are compared to actual field names with a case sensitive match; otherwise a case insensitive match is used.

Throws:

IllegalArgumentException - If either argument is null.

Fields_Map

public Fields_Map(String[] user_fields,
                  String[] actual_fields)

Constructs a Fields_Map that maps an array of field names in user index order to their index in an array of field names in actual (table record) order.

User field names that are not found in the array of actual names map to a -1 index to indicate missing fields.

User field names are compared to actual field names using the default case sensitivity.

N.B.: The first actual field name that matches each user field name provides the mapping. If the actual field names list contains duplicate entries, only the first entry will be mapped. Likewise, if case insensitive matching is being done only the first actual name that matches a user name regardless of case is mapped.

N.B.: A field names list may contain null entries. A null name always matches a null name. A non-null name never matches a null name.

Parameters:

user_fields - An array of user field name Strings to be mapped.

actual_fields - An array of field name Strings in actual (table record) order; as returned in the first record of a Database.Select operation.

Throws:

IllegalArgumentException - If either argument is null.

Fields_Map

public Fields_Map(String[] user_fields,
                  List<String> actual_fields)

Constructs a Fields_Map that maps an array of field names in user index order to their index in a List of field names in actual (table record) order.

User field names that are not found in the List of actual names map to a -1 index to indicate missing fields.

User field names are compared to actual field names using the default case sensitivity.

N.B.: The first actual field name that matches each user field name provides the mapping. If the actual field names list contains duplicate entries, only the first entry will be mapped. Likewise, if case insensitive matching is being done only the first actual name that matches a user name regardless of case is mapped.

N.B.: A field names list may contain null entries. A null name always matches a null name. A non-null name never matches a null name.

Parameters:

user_fields - An array of user field name Strings to be mapped.

actual_fields - A List of field name Strings in actual (record) order; as returned in the first record of a Database.Select operation.

Throws:

IllegalArgumentException - If either argument is null.

Fields_Map

public Fields_Map(List<String> user_fields,
                  String[] actual_fields)

Constructs a Fields_Map that maps a List of field names in user index order to their index in an array of field names in actual (table record) order.

User field names that are not found in the array of actual names map to a -1 index to indicate missing fields.

User field names are compared to actual field names using the default case sensitivity.

N.B.: The first actual field name that matches each user field name provides the mapping. If the actual field names list contains duplicate entries, only the first entry will be mapped. Likewise, if case insensitive matching is being done only the first actual name that matches a user name regardless of case is mapped.

N.B.: A field names list may contain null entries. A null name always matches a null name. A non-null name never matches a null name.

Parameters:

user_fields - A List of user field name Strings to be mapped.

actual_fields - An array of field name Strings in actual (record) order; as returned in the first record of a Database.Select operation.

Throws:

IllegalArgumentException - If either argument is null.

Method Detail

index

public int index(int user_field_number)

Maps a user field number to an actual record field number.

Parameters:

user_field_number - The user field number to map.

Returns:

The actual record field number. This will be -1 if the user field_number is not within the range of the number of field names provided when the Fields_Map was constructed, or it maps to a field that was not present when the map was constructed.

index

public int index(String user_field_name)

Maps a user field name to an actual field number.

The specified field name is compared to the list of user field names with the case sensitivity of the Field_Map object.

Parameters:

user_field_name - The user field name to map.

Returns:

The actual field number. This will be -1 if the field_name was not matched in the list of user field names provided when the Fields_Map was constructed, or it was not mapped to an actual field name.

entry

public String entry(List<String> record,
                    int field_number)

Gets a field entry from a record corresponding to a user field number.

The field number is mapped to is actual index. If this results in a valid record index (non-negative less than the size of the record) the corresponding entry from the record is returned as a String.

Parameters:

record - The record List containing field value Strings. If null, null is returned.

field_number - The user field number before mapping to its actual field index.

Returns:

The record List String entry for the mapped user field_number. This will be null if the user field number does not map to a valid record entry.

entry

public String entry(List<String> record,
                    String field_name)

Gets a field entry from a record corresponding to a user field name.

The field name is mapped to its actual index. If this results in a valid record index (non-negative less than the size of the record) the corresponding entry from the record is returned as a String.

Parameters:

record - The record List containing field value Strings. If null, null is returned.

field_name - The user field name of the field for which to get a record entry.

Returns:

The record List String entry for the mapped field_name. This will be null if the field name does not map to a valid record entry.

User_Fields

public Vector<String> User_Fields()

Gets a Vector of field names in user index order.

Only field names that were mapped when the Fields_Map was constructed will be included in the Vector that is returned.

Returns:

A Vector of field names in user index order.

All_User_Fields

public Vector<String> All_User_Fields()

Gets a Vector of all the user field names.

All the original user field names, as specified in the constructor, are included in the Vector that is returned.

Returns:

A Vector that is a copy of the original user field names specified in the constructor. This will be empty if the constructor was given a null user fields list.

Actual_Fields

public Vector<String> Actual_Fields()

Gets a Vector of field names in actual index order.

Only actual field names that were mapped from user field names when the Fields_Map was constructed will be included in the Vector that is returned. Thus the returned Vector may be smaller than the number of entries in the actual fields name list provided to the constructor.

Returns:

A Vector of field names in actual index order.

All_Actual_Fields

public Vector<String> All_Actual_Fields()

Gets a Vector of actual field names in unmapped order.

All the original actual field names, as specified in the constructor, are included in the Vector that is returned.

Returns:

A Vector that is a copy of the original actual field names specified in the constructor. This will be an empty if the constructor had a null user or actual fields list.

Table_Fields

public Vector<String> Table_Fields()

Deprecated.

Gets a Vector of actual field names in unmapped order.

This is a deprecated name for the All_Actual_Fields() method.

Returns:

A Vector that is a copy of the original actual field names specified in the constructor. This will be an empty if the constructor had a null useer or actual fields list.

Unmapped_Actual_Fields

public Vector<String> Unmapped_Actual_Fields()

Gets a Vector of unmapped actual field names.

Returns:

A Vector containing the actual field names are not mapped to user field names.

Actual_to_User

public Vector<String> Actual_to_User(Vector<String> record)

Remaps a record from actual table record order to user fields order.

A new record is constructed from mapped entries of the specified record for all user fields. Any user field that is not mapped to an actual field results in a null record entry. Entries of the source record that are not mapped will not be included in the returned record; the returned record will be the same size as the user field names list that was used to construct the Fields_Map.

Parameters:

record - A Vector of field values in actual order. If null, null is returned.

Returns:

A Vector of mapped record field values in user order.

Throws:

IllegalArgumentException - If the source record has fewer entries than the number of user fields.

toString

public String toString()

Gets the description of this Fields_Map.

Overrides:

toString in class Object

Returns:

A String describing this Fields_Map.

Confirm_Fields

public void Confirm_Fields(String[] field_names)
                    throws Database_Exception

Confirms that a list of field names are all mapped to valid record locations.

Each name in the list is treated as a user field name that is required to be mapped to an actual field name. Thus the failure of any name in the list to be mapped will throw an exception. Nevertheless, all unmapped field names in the list are identified.

Parameters:

field_names - An array of user name Strings to be checked. null entries are ignored.

Throws:

Database_Exception - if any names fail to map to valid record locations. The exception message will list all missing field names.

Confirm_Fields

public void Confirm_Fields(List<String> field_names)
                    throws Database_Exception

Confirms that a list of user field names are all mapped to valid actual fields.

Each name in the list is treated as a user field name that is required to be mapped to an actual field name. Thus the failure of any name in the list to be mapped will throw an exception. Nevertheless, all unmapped field names in the list are identified.

Parameters:

field_names - The list of names to be checked. If null, nothing is done. Any null entries in the list are ignored.

Throws:

Database_Exception - if any of the field names fail to map to valid actual locations. The exception message will list all unmapped field names.