uk.ac.ed.epcc.webapp.model.history

Class HistoryFactory<P extends DataObject,H extends HistoryFactory.HistoryRecord<P>>

java.lang.Object

uk.ac.ed.epcc.webapp.model.data.DataObjectFactory<H>

uk.ac.ed.epcc.webapp.model.history.HistoryFactory<P,H>

Type Parameters:

P - type of peer

H -

All Implemented Interfaces:

Contexed, ContextCached, FormCreatorProducer, FormUpdateProducer<H>, FilterMatcher<H>, TableStructureListener, TypeConverter<H,java.lang.Number>, DataObjectSelector<H>, Selector<DataObjectItemInput<H>>, Owner<H>, IndexedProducer<H>, HistoryHandler<P>, TimePurgeFactory, Tagged, Targetted<H>

Direct Known Subclasses:

LinkHistoryManager, PersonHistoryFactory

public class HistoryFactory<P extends DataObject,H extends HistoryFactory.HistoryRecord<P>>
extends DataObjectFactory<H>
implements HistoryHandler<P>, TableStructureListener, TimePurgeFactory

Class to generate History objects. As History objects are only manipulated via the factory (they are logically part of a series rather than making sense on their own) we make the History object an pseudo inner class of HistoryFactory. The factory reference is explicit rather than a real inner class to stop the history object being generic parameterised by itself.

Every entry in a History table contains some fields from the tracked object (any field without a corresponding field in the history table is not tracked. There is also a field giving the ID of the peer object. This defaults to PeerID but can be changed by overriding the getPeerName() method. There are also 2 time fields giving the period over which the data is valid. These can be either SQL time-type fields or numeric fields

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
class	HistoryFactory.HistoryFilter Filter for History objects selecting by peer object and date range
static class	HistoryFactory.HistoryRecord<P extends DataObject> Class Representing time history of and object.
class	HistoryFactory.Mapper Maps history objects to display classes for Timechart graphs.
class	HistoryFactory.PeerIterator Converts History objects into Peer object representation

Nested classes/interfaces inherited from class uk.ac.ed.epcc.webapp.model.data.DataObjectFactory

DataObjectFactory.AbstractDataObjectInput, DataObjectFactory.AbstractFinder<X>, DataObjectFactory.DataObjectAcceptFilter, DataObjectFactory.DataObjectInput, DataObjectFactory.DataObjectIntegerInput, DataObjectFactory.DestAcceptFilter<T extends DataObject>, DataObjectFactory.FilterAdapter, DataObjectFactory.FilterCounter, DataObjectFactory.FilterExists, DataObjectFactory.FilterIterator, DataObjectFactory.FilterSelector, DataObjectFactory.FilterSet, DataObjectFactory.Finder, DataObjectFactory.MakeRemoteFilterVisitor<R extends DataObject>, DataObjectFactory.MatchFilter, DataObjectFactory.ReferencedAdapter<I extends Indexed>, DataObjectFactory.ReferenceIterator<I extends Indexed>, DataObjectFactory.SortingDataObjectInput, DataObjectFactory.TimeAcceptFilter<T extends DataObject>, DataObjectFactory.TimeFilter

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	END_TIME_FIELD
protected static long	ENDTIME
static Feature	HISTORY_CACHE_FEATURE
static Feature	HISTORY_STATUS_FEATURE
static java.lang.String	START_TIME_FIELD

Fields inherited from class uk.ac.ed.epcc.webapp.model.data.DataObjectFactory

AUTO_CREATE_TABLES_FEATURE, COMPOSITES_SUFFIX, REJECT_MULTIPLE_RESULT_FEATURE, res

Constructor Summary

Constructors

Modifier	Constructor and Description
	HistoryFactory(AppContext c, java.lang.String table) Constructor for Stand alone history factories.
protected	HistoryFactory(DataObjectFactory<P> fac) Constructor to allow sub-classes to set factory before calling DataObjectFactory.setContext(AppContext, String)
	HistoryFactory(DataObjectFactory<P> fac, java.lang.String table) Standard Constructor for HistoryFactory HistoryFactory contains a ref to its peer factory.

Method Summary

Modifier and Type	Method and Description
SetPlot	addChart(LabelledSetRangeMapper<H> gm, java.util.Iterator<H> iter, TimeChart tc, float other_thresh)
SetPlot	addChart(LabelledSetRangeMapper<H> gm, java.util.Iterator<H> iter, TimeChart tc, float other_thresh, int max_plot)
void	closeGaps(P peer, java.util.Date start, java.util.Date end) close gaps in history sequence over a time range.
protected java.util.Date	expireTime(P peer, java.util.Date start) calculates the time the current data should expire.
H	find(P peer, java.util.Date time) Find History by peer and date
protected H	find(P peer, java.util.Date time, boolean want_tail)
void	fixSeries(P peer, java.util.Date start, java.util.Date end) fix a corrupt history sequence, ensure there are no overlapping records and fix and reversed timestamps and spurious splits.
protected void	fixSeries(P peer, java.util.Iterator<H> it) fix a corrupt history sequence, ensure there are no overlapping records and fix and reversed timestamps and spurious splits.
TableSpecification	getDefaultTableSpecification(AppContext c, java.lang.String homeTable) Get the default table specification if the table is to be created.
java.util.Iterator<H>	getIterator(java.util.Date start, java.util.Date end)
java.util.Iterator<H>	getIterator(P peer, java.util.Date start, java.util.Date end)
java.util.Iterator<H>	getIterator(SQLFilter<P> peer, java.util.Date start, java.util.Date end)
protected java.util.List<OrderClause>	getOrder()
DataObjectFactory<P>	getPeerFactory()
java.lang.String	getPeerName() Name of the field containing the peer id This must match the equivalent methid in the History type.
IndexedProducer<P>	getPeerProducer()
protected IndexedTypeProducer	getPeerReference()
java.lang.Class<H>	getTarget() Get a bound on the type of object produced by this factory for run-time checking.
boolean	isPeerType(DataObject peer) is peer of right type
protected H	makeBDO(Repository.Record res) Construct a new Blank DataObject of the correct Class This method takes a Record as an argument.
protected HistoryFactory.HistoryRecord<P>	makeHistory(java.util.Date now, P peer) make History object from peer
protected void	postCreateTableSetup(AppContext c, java.lang.String table)
void	purge(P o) Delete all history records corresponding to a specified peer object.
void	purgeOldData(java.util.Date epoch)
void	resetStructure() Table structure has changed
protected void	setPeerFactory(DataObjectFactory<P> fac)
boolean	skipUpdate(P peer) extension point to allow history to be skipped based on peer state
void	terminate(P peer) Terminates the history for a given peer object updates the quota history to reflect the current status of the quota.
HistoryFactory.HistoryRecord<P>	update(P peer) Updates quota history.
int	wipe(P peer, java.util.Set<java.lang.String> fields) wipe data from entire sequence of a record

Methods inherited from class uk.ac.ed.epcc.webapp.model.data.DataObjectFactory

all, allowPreSelect, canCreate, canUpdate, checkComposite, convertToDestinationFilter, customiseForm, equals, exists, find, find, find, find, find, getAllIterator, getComposite, getComposites, getComposites, getConfigTag, getContext, getCount, getDefaultRelationshipFilter, getDefaults, getDestFilter, getExcludeFilter, getFieldConstraints, getFieldHelp, getFilter, getFilter, getFilter, getFinalSelectFilter, getFinalTableSpecification, getFindFilter, getFormCreator, getFormUpdate, getID, getIndex, getInput, getInput, getInput, getLogger, getMaxIdentifierLength, getNullable, getOptional, getProperty, getReferenced, getReferenceFieldType, getReferenceFieldType, getRemoteFilter, getRemoteSQLFilter, getResult, getResult, getSelectFilter, getSelector, getSelector, getSelectors, getSupress, getTableSpecification, getTableStructureContributers, getTag, getTranslations, getUniqueIdName, hasComposite, hashCode, isMine, isMine, isMyReference, isValid, makeBDO, makeObject, makeRecord, makeReference, makeReference, matches, narrowSelector, narrowSelector, observeComposite, OrderBy, postSetContext, release, restrictDefaultInput, setComposites, setContext, setContext, setContextWithMake, setProperty, toString, updateTable

Methods inherited from class java.lang.Object

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

Field Detail

HISTORY_CACHE_FEATURE

public static final Feature HISTORY_CACHE_FEATURE

HISTORY_STATUS_FEATURE

public static final Feature HISTORY_STATUS_FEATURE

ENDTIME

protected static long ENDTIME

START_TIME_FIELD

public static final java.lang.String START_TIME_FIELD

See Also:

Constant Field Values

END_TIME_FIELD

public static final java.lang.String END_TIME_FIELD

See Also:

Constant Field Values

Constructor Detail

HistoryFactory

public HistoryFactory(DataObjectFactory<P> fac,
                      java.lang.String table)

Standard Constructor for HistoryFactory HistoryFactory contains a ref to its peer factory. We use a constructor like this to encourage HistoryFactories to be produced from existing PeerFactories. This is especially important If the PeerFactory wants to hold a reference to the HistoryFactory e.g. LinkManager

Parameters:

fac -

table - table to store data

HistoryFactory

protected HistoryFactory(DataObjectFactory<P> fac)

Constructor to allow sub-classes to set factory before calling DataObjectFactory.setContext(AppContext, String)

Parameters:

fac -

HistoryFactory

public HistoryFactory(AppContext c,
                      java.lang.String table)

Constructor for Stand alone history factories. The peer factory needs to be resolved from the meta-data or config.

Parameters:

c -

table -

Method Detail

getPeerReference

protected IndexedTypeProducer getPeerReference()

getPeerFactory

public DataObjectFactory<P> getPeerFactory()

getPeerProducer

public IndexedProducer<P> getPeerProducer()

setPeerFactory

protected void setPeerFactory(DataObjectFactory<P> fac)

getDefaultTableSpecification

public TableSpecification getDefaultTableSpecification(AppContext c,
                                                       java.lang.String homeTable)

Description copied from class: DataObjectFactory

Get the default table specification if the table is to be created. A null result means that a default specification is not available and the table will not be created.

Overrides:

getDefaultTableSpecification in class DataObjectFactory<H extends HistoryFactory.HistoryRecord<P>>

Parameters:

c - AppContext

homeTable - String table name.

Returns:

null or TableSpecification

addChart

public SetPlot addChart(LabelledSetRangeMapper<H> gm,
                        java.util.Iterator<H> iter,
                        TimeChart tc,
                        float other_thresh)
                 throws java.lang.Exception

Parameters:

gm -

iter -

tc -

other_thresh -

Returns:

Chart.Plot

Throws:

java.lang.Exception

addChart

public SetPlot addChart(LabelledSetRangeMapper<H> gm,
                        java.util.Iterator<H> iter,
                        TimeChart tc,
                        float other_thresh,
                        int max_plot)
                 throws java.lang.Exception

Throws:

java.lang.Exception

expireTime

protected java.util.Date expireTime(P peer,
                                    java.util.Date start)

calculates the time the current data should expire. defaults to ENDTIME but can be overridden to implement data we want to time expire

Parameters:

peer -

start -

Returns:

long

find

public final H find(P peer,
                    java.util.Date time)
             throws DataException,
                    java.lang.IllegalArgumentException

Description copied from interface: HistoryHandler

Find History by peer and date

Specified by:

find in interface HistoryHandler<P extends DataObject>

Returns:

History

Throws:

DataException

java.lang.IllegalArgumentException

find

protected final H find(P peer,
                       java.util.Date time,
                       boolean want_tail)
                throws DataException,
                       java.lang.IllegalArgumentException

Throws:

DataException

java.lang.IllegalArgumentException

getIterator

public java.util.Iterator<H> getIterator(P peer,
                                         java.util.Date start,
                                         java.util.Date end)
                                  throws DataFault

Specified by:

getIterator in interface HistoryHandler<P extends DataObject>

Throws:

DataFault

getIterator

public java.util.Iterator<H> getIterator(SQLFilter<P> peer,
                                         java.util.Date start,
                                         java.util.Date end)
                                  throws DataFault

Specified by:

getIterator in interface HistoryHandler<P extends DataObject>

Throws:

DataFault

getIterator

public java.util.Iterator<H> getIterator(java.util.Date start,
                                         java.util.Date end)
                                  throws DataFault

Specified by:

getIterator in interface HistoryHandler<P extends DataObject>

Throws:

DataFault

getPeerName

public java.lang.String getPeerName()

Name of the field containing the peer id This must match the equivalent methid in the History type.

Specified by:

getPeerName in interface HistoryHandler<P extends DataObject>

Returns:

String containing field name

isPeerType

public final boolean isPeerType(DataObject peer)

Description copied from interface: HistoryHandler

is peer of right type

Specified by:

isPeerType in interface HistoryHandler<P extends DataObject>

Parameters:

peer - a DataObject to check

Returns:

boolean true if type matches

makeBDO

protected H makeBDO(Repository.Record res)
             throws DataFault

Description copied from class: DataObjectFactory

Construct a new Blank DataObject of the correct Class This method takes a Record as an argument. This allows the factory to either create different sub-classes depending on a value in the record or to produce objects from different Repositories/tables. We keep the return type as DataObject instead of making it generic as this helps with legacy compatibility a little bit (problem is if we have another generic sub-type between us and a legacy sub-class

Specified by:

makeBDO in class DataObjectFactory<H extends HistoryFactory.HistoryRecord<P>>

Parameters:

res - Record to create object from

Returns:

new object of correct class.

Throws:

DataFault

getTarget

public java.lang.Class<H> getTarget()

Description copied from class: DataObjectFactory

Get a bound on the type of object produced by this factory for run-time checking. This implements IndexedProducer.getTarget(). Normally this method should be overridden each time we make a sub-class that narrows the produced type. However checks should still pass if the super-type method is retained.

Specified by:

getTarget in interface IndexedProducer<H extends HistoryFactory.HistoryRecord<P>>

Specified by:

getTarget in interface Targetted<H extends HistoryFactory.HistoryRecord<P>>

Overrides:

getTarget in class DataObjectFactory<H extends HistoryFactory.HistoryRecord<P>>

Returns:

Class object for return type

makeHistory

protected final HistoryFactory.HistoryRecord<P> makeHistory(java.util.Date now,
                                                            P peer)
                                                     throws ConsistencyError,
                                                            DataFault

make History object from peer

Parameters:

peer - DataObject to record.

Returns:

history object

Throws:

ConsistencyError

DataFault

getOrder

protected java.util.List<OrderClause> getOrder()

Overrides:

getOrder in class DataObjectFactory<H extends HistoryFactory.HistoryRecord<P>>

purge

public void purge(P o)
           throws DataFault

Description copied from interface: HistoryHandler

Delete all history records corresponding to a specified peer object.

Specified by:

purge in interface HistoryHandler<P extends DataObject>

Parameters:

o - DataObject peer

Throws:

DataFault

terminate

public final void terminate(P peer)
                     throws java.lang.IllegalArgumentException,
                            DataException

Description copied from interface: HistoryHandler

Terminates the history for a given peer object updates the quota history to reflect the current status of the quota.

Specified by:

terminate in interface HistoryHandler<P extends DataObject>

Parameters:

peer - Peer object whose history will be terminated

Throws:

java.lang.IllegalArgumentException

DataException

skipUpdate

public boolean skipUpdate(P peer)

extension point to allow history to be skipped based on peer state

Parameters:

peer -

Returns:

update

public final HistoryFactory.HistoryRecord<P> update(P peer)
                                             throws java.lang.IllegalArgumentException,
                                                    ConsistencyError,
                                                    DataException

Description copied from interface: HistoryHandler

Updates quota history. updates the quota history to reflect the current status of the quota.

Specified by:

update in interface HistoryHandler<P extends DataObject>

Returns:

History

Throws:

java.lang.IllegalArgumentException

ConsistencyError

DataException

fixSeries

public void fixSeries(P peer,
                      java.util.Date start,
                      java.util.Date end)
               throws DataException

fix a corrupt history sequence, ensure there are no overlapping records and fix and reversed timestamps and spurious splits.

Parameters:

peer -

start -

end -

Throws:

DataException

fixSeries

protected void fixSeries(P peer,
                         java.util.Iterator<H> it)
                  throws DataFault,
                         DataException

fix a corrupt history sequence, ensure there are no overlapping records and fix and reversed timestamps and spurious splits.

Parameters:

peer -

it -

Throws:

DataFault

DataException

closeGaps

public void closeGaps(P peer,
                      java.util.Date start,
                      java.util.Date end)
               throws DataException

close gaps in history sequence over a time range.

Parameters:

peer -

start -

end -

Throws:

DataException

postCreateTableSetup

protected void postCreateTableSetup(AppContext c,
                                    java.lang.String table)

Overrides:

postCreateTableSetup in class DataObjectFactory<H extends HistoryFactory.HistoryRecord<P>>

resetStructure

public void resetStructure()

Description copied from interface: TableStructureListener

Table structure has changed

Specified by:

resetStructure in interface TableStructureListener

purgeOldData

public void purgeOldData(java.util.Date epoch)
                  throws java.lang.Exception

Specified by:

purgeOldData in interface TimePurgeFactory

Throws:

java.lang.Exception

wipe

public int wipe(P peer,
                java.util.Set<java.lang.String> fields)
         throws DataFault

wipe data from entire sequence of a record

Parameters:

peer -

fields -

Throws:

DataFault