uk.ac.ed.epcc.webapp.model.data

Class Repository.Record

java.lang.Object

java.util.AbstractMap<K,V>

java.util.HashMap<java.lang.String,java.lang.Object>

uk.ac.ed.epcc.webapp.model.data.Repository.Record

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, java.util.Map<java.lang.String,java.lang.Object>

Enclosing class:

Repository

public final class Repository.Record
extends java.util.HashMap<java.lang.String,java.lang.Object>

Record encapsulates a Database record. It is essentially a Map container where database field names are used as the key and the field data is the value referenced.

In general this code is fairly flexible as to the type of objects stored in the record. The type of object returned from the DB depends pretty much on the DB layer and the DB schema. Note that different DB drivers will handle the same schema in different ways, for example different mysql drivers/versions returned Integers or Longs for the same field.

Record supports a default conversion between integer and Date properties/Fields based on the Repository Resolution property. The resolution defaults to 1 second but can be set using the repository.resolution.[table-name] property. Provided that the java side consistently uses Date or integers the java code does not need to know the conversion factor explicitly.

Records are always created empty. They can then either be populated using a ResultSet or created from scratch using put/get methods. An existing database record can be retrieved by using the setID method on an empty Record. In all cases no changes are written to the database until the commit() method is called.

The class also supports get/set Property methods that support additional type conversions and casting. These are more useful than the put/get calls in the Map interface as the type of Object returned from the map may change if the database schema (or JDBC driver) is changed.

For Example:

     Repository res = Repository.getInstance(ctx,"my_table");
     Record rec = res.new Record();
     rec.setProperty("Number",12.0);
     rec.commit(); // create record
     rec.setProperty("Number",24.0); 
     rec.commit(); // update record
     
     Record rec2 = res.new Record();
     rec2.setID(rec.getID()); // retrieve new copy from DB by ID.
     double d = rec2.getDoubleProperty("Number"); // should be 24.0

In many cases the values of a database field are actually codes denoting one of a finite set of objects.In this case a class implementing TypeProducer should be used to express this mapping. There are special getProperty and setProperty calls that use this interface. Java Enum types can be supported using EnumProducer where the text value of the Enum will be stored in the database. however much of the existing code base uses sub classes of BasicType to implement type-safe enumeration.

The intention is that this class is more database facing and that model classes contain an instance of Record rather than sub-classing it.

See Also:

Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from class java.util.AbstractMap

java.util.AbstractMap.SimpleEntry<K,V>, java.util.AbstractMap.SimpleImmutableEntry<K,V>

Nested classes/interfaces inherited from interface java.util.Map

java.util.Map.Entry<K,V>

Constructor Summary

Constructors

Constructor and Description
Record()

Method Summary

Modifier and Type	Method and Description
void	backup()
void	clear() reset to uninitialised state.
java.lang.Object	clone()
boolean	commit() commit changes made to this object to the
void	delete() delete the corresponding database entry and restore the Record to uninitialised state.
boolean	equals(java.util.Map<java.lang.String,java.lang.Object> r) Compare with a Map of values for all the fields they have in common test for equality.
int	findDuplicate() Get the id of an identical (up to id) record in the database normally called on an uncommitted record so only the set fields are used to generate the query This is not efficient but can be used when merging data.
int	findDuplicate(int id, java.util.Set<java.lang.String> fields, boolean check_all) Get the id of an identical (up to id) record in the database normally called on an uncommitted record so only the set fields are used to generate the query.
boolean	getBooleanProperty(java.lang.String name) Query a property that should contain a single Y/N character and retrun this as a boolean.
boolean	getBooleanProperty(java.lang.String name, boolean default_value) Query a property that should contain a single Y/N character and retrun this as a boolean.
java.util.Date	getDateProperty(java.lang.String name)
double	getDoubleProperty(java.lang.String name) get a property as a double value
double	getDoubleProperty(java.lang.String name, double default_value)
float	getFloatProperty(java.lang.String name) get a property as a float value
float	getFloatProperty(java.lang.String name, float default_value)
int	getID() get the unique id value for this Record
int	getIntProperty(java.lang.String name)
int	getIntProperty(java.lang.String name, int default_value)
long	getLongProperty(java.lang.String name) get a property as a long value
long	getLongProperty(java.lang.String name, long default_value)
java.lang.Number	getNumberProperty(java.lang.String name)
java.lang.Object	getProperty(java.lang.String name) Returns the value associated with this database column name Where possible you should use one of the getProperty methods as these will take care of any conversion from the underlying database object.
<F,D> F	getProperty(TypeProducer<F,D> t) Return the .Value associated with the specified TypeProducer
<F,D> F	getProperty(TypeProducer<F,D> t, F def) Return the .Value associated with the specified TypeProducer
Repository	getRepository() get the enclosing Repository
java.lang.Object	getRequiredProperty(java.lang.String name) Returns the value associated with this database column name Unlike getProperty the returned value should never be null to additional error reporting is invoked if it is.
StreamData	getStreamDataProperty(java.lang.String name)
java.lang.String	getStringProperty(java.lang.String name) get a property as a string.
java.lang.String	getStringProperty(java.lang.String name, java.lang.String default_value) get a property value as a string with a default value to return if the property is not set or the string is empty
java.util.Map<java.lang.String,java.lang.Object>	getValues() Get a map of the contents without the UniqueID field
boolean	isLocked()
void	lock() mark the record as read-only/locked This is intended for when
java.lang.Object	put(java.lang.String key, java.lang.Object value)
void	putAll(java.util.Map<? extends java.lang.String,? extends java.lang.Object> m)
java.lang.Object	remove(java.lang.String key)
void	set(java.util.Map<? extends java.lang.String,? extends java.lang.Object> m) Like putAll but does full synchronisation removing fields that are missing as well.
Repository.Record	setID(int id2) This method returns a reference to itself so we can initialise the record as part of a constructor.
protected void	setInitialID(int id)
void	setOptionalProperty(java.lang.String name, java.lang.Object value) Set a property where it is acceptable for the property not to exist in the underlying database.
<F,D> void	setOptionalProperty(TypeProducer<? super F,D> t, F v) Set the property associated with a TypeProducer where it is acceptable for the property not to exist in the underlying database
void	setProperty(java.lang.String name, boolean val) store a Y/N value based on boolean input.
void	setProperty(java.lang.String name, double val) set a property to a double value
void	setProperty(java.lang.String name, float val) set a property to an float value
void	setProperty(java.lang.String name, int val) set a property to an integer value
void	setProperty(java.lang.String name, long val) set a property to an long value
void	setProperty(java.lang.String key, java.lang.Object value) Store data in record
<F,D> void	setProperty(TypeProducer<? super F,D> t, F v) Set the property associated with a TypeProducer
protected void	setValue(java.lang.StringBuilder buff, java.sql.PreparedStatement stmt, int pos, java.lang.String key) output the value of a field to a prepared statement Note that StreamData objects are added as binary streams.
java.lang.String	toString()

Methods inherited from class java.util.HashMap

compute, computeIfAbsent, computeIfPresent, containsKey, containsValue, entrySet, forEach, get, getOrDefault, isEmpty, keySet, merge, putIfAbsent, remove, remove, replace, replace, replaceAll, size, values

Methods inherited from class java.util.AbstractMap

equals, hashCode

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.util.Map

equals, hashCode

Constructor Detail

Record

public Record()

Method Detail

clear

public void clear()

reset to uninitialised state.

Specified by:

clear in interface java.util.Map<java.lang.String,java.lang.Object>

Overrides:

clear in class java.util.HashMap<java.lang.String,java.lang.Object>

clone

public java.lang.Object clone()

Overrides:

clone in class java.util.HashMap<java.lang.String,java.lang.Object>

commit

public boolean commit()
               throws DataFault

commit changes made to this object to the

Returns:

boolean true if change made

Throws:

DataFault

backup

public void backup()
            throws DataFault

Throws:

DataFault

getValues

public java.util.Map<java.lang.String,java.lang.Object> getValues()

Get a map of the contents without the UniqueID field

Returns:

Map

delete

public void delete()
            throws ConsistencyError,
                   DataFault

delete the corresponding database entry and restore the Record to uninitialised state.

Throws:

ConsistencyError

DataFault

equals

public boolean equals(java.util.Map<java.lang.String,java.lang.Object> r)

Compare with a Map of values for all the fields they have in common test for equality.

Parameters:

r - Map to compare to

Returns:

return false if any common fields are different.

getBooleanProperty

public final boolean getBooleanProperty(java.lang.String name)

Query a property that should contain a single Y/N character and retrun this as a boolean. A missing property is returned as true

Parameters:

name - String name of property

Returns:

boolean true for Y

getBooleanProperty

public final boolean getBooleanProperty(java.lang.String name,
                                        boolean default_value)

Query a property that should contain a single Y/N character and retrun this as a boolean. A missing property is returned as the default value

Parameters:

name - String name of property

default_value - value to return for missing property

Returns:

boolean true for Y

getDateProperty

public final java.util.Date getDateProperty(java.lang.String name)

getDoubleProperty

public final double getDoubleProperty(java.lang.String name)

get a property as a double value

Parameters:

name - String Property to get

Returns:

double value

getDoubleProperty

public final double getDoubleProperty(java.lang.String name,
                                      double default_value)

getFloatProperty

public final float getFloatProperty(java.lang.String name)

get a property as a float value

Parameters:

name - String Property to get

Returns:

float value

getFloatProperty

public final float getFloatProperty(java.lang.String name,
                                    float default_value)

getIntProperty

public final int getIntProperty(java.lang.String name)

getIntProperty

public final int getIntProperty(java.lang.String name,
                                int default_value)

getID

public final int getID()
                throws ConsistencyError

get the unique id value for this Record

Returns:

int id

Throws:

ConsistencyError - if id not defined yet

getLongProperty

public final long getLongProperty(java.lang.String name)

get a property as a long value

Parameters:

name - String Property to get

Returns:

int value

getLongProperty

public final long getLongProperty(java.lang.String name,
                                  long default_value)

getNumberProperty

public final java.lang.Number getNumberProperty(java.lang.String name)

getProperty

public final <F,D> F getProperty(TypeProducer<F,D> t)

Return the .Value associated with the specified TypeProducer

Type Parameters:

F - The type of value returned

D - Type stored in DB

Parameters:

t -

Returns:

TheValue

getProperty

public final <F,D> F getProperty(TypeProducer<F,D> t,
                                 F def)

Return the .Value associated with the specified TypeProducer

Type Parameters:

F - The type of value returned

D - Type stored in DB

Parameters:

t -

def - default result

Returns:

TheValue

getProperty

public final java.lang.Object getProperty(java.lang.String name)

Returns the value associated with this database column name Where possible you should use one of the getProperty methods as these will take care of any conversion from the underlying database object.

Parameters:

name - The name of the field

Returns:

an Object representing the value of the field

getRequiredProperty

public final java.lang.Object getRequiredProperty(java.lang.String name)

Returns the value associated with this database column name Unlike getProperty the returned value should never be null to additional error reporting is invoked if it is.

Parameters:

name - The name of the field

Returns:

an Object representing the value of the field

getStreamDataProperty

public final StreamData getStreamDataProperty(java.lang.String name)
                                       throws DataFault

Throws:

DataFault

getStringProperty

public final java.lang.String getStringProperty(java.lang.String name)

get a property as a string.

Parameters:

name - Property to get

Returns:

String value

getStringProperty

public final java.lang.String getStringProperty(java.lang.String name,
                                                java.lang.String default_value)

get a property value as a string with a default value to return if the property is not set or the string is empty

Parameters:

name -

default_value -

Returns:

String

getRepository

public Repository getRepository()

get the enclosing Repository

Returns:

the Repository used to create this Record.

put

public java.lang.Object put(java.lang.String key,
                            java.lang.Object value)

Specified by:

put in interface java.util.Map<java.lang.String,java.lang.Object>

Overrides:

put in class java.util.HashMap<java.lang.String,java.lang.Object>

putAll

public void putAll(java.util.Map<? extends java.lang.String,? extends java.lang.Object> m)

Specified by:

putAll in interface java.util.Map<java.lang.String,java.lang.Object>

Overrides:

putAll in class java.util.HashMap<java.lang.String,java.lang.Object>

remove

public java.lang.Object remove(java.lang.String key)

set

public void set(java.util.Map<? extends java.lang.String,? extends java.lang.Object> m)

Like putAll but does full synchronisation removing fields that are missing as well.

Parameters:

m - Map to sync to

setInitialID

protected void setInitialID(int id)

setID

public Repository.Record setID(int id2)
                        throws DataException

This method returns a reference to itself so we can initialise the record as part of a constructor.

Parameters:

id2 -

Returns:

reference to self

Throws:

DataException

setProperty

public final void setProperty(java.lang.String key,
                              java.lang.Object value)

Store data in record

Parameters:

key -

value -

setOptionalProperty

public final void setOptionalProperty(java.lang.String name,
                                      java.lang.Object value)

Set a property where it is acceptable for the property not to exist in the underlying database.

Parameters:

name -

value -

setProperty

public final <F,D> void setProperty(TypeProducer<? super F,D> t,
                                    F v)

Set the property associated with a TypeProducer

Type Parameters:

F - Type corresponding to the TypeProducer

D - Type stored in Database

Parameters:

t - the BasicType to set

v - The Value to set.

setOptionalProperty

public final <F,D> void setOptionalProperty(TypeProducer<? super F,D> t,
                                            F v)

Set the property associated with a TypeProducer where it is acceptable for the property not to exist in the underlying database

Type Parameters:

F - Type corresponding to TypeProducer

D - Type stored in Database

Parameters:

t - the BasicType to set

v - The Value to set.

setProperty

public final void setProperty(java.lang.String name,
                              boolean val)

store a Y/N value based on boolean input. This allows single character fields to be used to store boolean values. A true boolean field will also work as the strings will be converted appropriately

Parameters:

name - String property to set

val - boolean value

See Also:

Repository.convertBoolean(Object, Boolean)

setProperty

public final void setProperty(java.lang.String name,
                              double val)

set a property to a double value

Parameters:

name - String property to set.

val -

setProperty

public final void setProperty(java.lang.String name,
                              float val)

set a property to an float value

Parameters:

name - String property to set.

val -

setProperty

public final void setProperty(java.lang.String name,
                              int val)

set a property to an integer value

Parameters:

name - String property to set.

val -

setProperty

public final void setProperty(java.lang.String name,
                              long val)

set a property to an long value

Parameters:

name - String property to set.

val -

setValue

protected final void setValue(java.lang.StringBuilder buff,
                              java.sql.PreparedStatement stmt,
                              int pos,
                              java.lang.String key)
                       throws java.sql.SQLException

output the value of a field to a prepared statement Note that StreamData objects are added as binary streams.

Parameters:

buff - query buffer. We append additional info to this to provide better debug messages

stms - PreparedStatement fo populate

pos - statement position to set

key - Field to output

Throws:

java.sql.SQLException

findDuplicate

public int findDuplicate()
                  throws ConsistencyError,
                         DataFault

Get the id of an identical (up to id) record in the database normally called on an uncommitted record so only the set fields are used to generate the query This is not efficient but can be used when merging data.

Returns:

id

Throws:

ConsistencyError

DataFault

findDuplicate

public int findDuplicate(int id,
                         java.util.Set<java.lang.String> fields,
                         boolean check_all)
                  throws ConsistencyError,
                         DataFault

Get the id of an identical (up to id) record in the database normally called on an uncommitted record so only the set fields are used to generate the query. If a +ve id value is specified this will be included in the selection effectively looking for a particular record that matches the uncommitted record. This is not efficient but can be used when merging data.

Parameters:

id - to match (if greater than zero)

fields - Set of field names to check.

check_all - Should all fields be checked not just the set/dirty fields.

Returns:

id of duplicate

Throws:

ConsistencyError

DataFault

toString

public java.lang.String toString()

Overrides:

toString in class java.util.AbstractMap<java.lang.String,java.lang.Object>

lock

public void lock()
          throws DataFault

mark the record as read-only/locked This is intended for when

Throws:

DataFault

isLocked

public boolean isLocked()