equip.data.sql
Class CustomTableDataStore

java.lang.Object
  equip.data.sql.CustomTableDataStore

All Implemented Interfaces:

IDataStore

public class CustomTableDataStore

extends java.lang.Object

implements IDataStore

Implementation of IDataStore interface which holds data for one specific (run-time configured) tuple type in a single JDBC table.

See notes for DataDelegate for configuring a dataspace to make use of a custom data store such as this.

This version is intended to make it relatively easy to expose an existing table of data through Equip. To do this it requires an auxiliary table to contain data-table to Equip mapping information and additional Equip-specific information.

It is configured as follows:

<storeId>.url: <JDBC-URL> [e.g. "jdbc:mysql://serverURL/dbName"]
<storeId>.user: <JDBC-username> [default: root]
<storeId>.password: <JDBC-password> [Optional]
<storeId>.driver: <JDBC-driver-classname> [e.g. "com.mysql.jdbc.Driver"]
<storeId>.readonly: <readonly> [default: true]
<storeId>.dataTableName: <data-table-name>
<storeId>.dataKeyType: <type> [default: int, options: string, float, double, char]
<storeId>.dataKeyColumn: <data-table-key-column-name>
<storeId>.dataKeyMapClass: <class-to-map-data-key-to-guid> [default: equip.data.sql.DataKeyMapGetUnique]
<storeId>.dataKeyAllocateClass: <class-to-get-a-new-data-key> [default: equip.data.sql.DataKeyAllocateMax]
<storeId>.dataNameColumn: <data-table-item-data-name-column-name> [optional; defaults to using helper table, column "NAME"]
<storeId>.helperTableName: <equip-specific-helper-table-name> [see below for schema]
<storeId>.tupleTypeName: <tuple-type-name> [used in field 0 of tuple, StringBox]
<storeId>.tupleSize: <N>
<storeId>.field<n>Type: <type> [default: int, options: string, float, double, char; n=1..N]
<storeId>.field<n>Column: <data-table-colum-name-for-field-n> [required, n=1..N]

The helper table schema is typically something like that produced by:

CREATE DATABASE FOODB;
USE FOODB;

CREATE TABLE EQUIPFOO (
  GUID VARCHAR(100) NOT NULL,
  NAME VARCHAR(255),
  DATAKEY INTEGER NOT NULL,
  PRIMARY KEY (GUID)
);

where DATAKEY is the foreign key (same type) as the primary key of the data table.

For example, consider the following simple data table:

CREATE TABLE FOO (
  SEQUENCE INTEGER NOT NULL,
  INTVALUE INTEGER NOT NULL,
  PRIMARY KEY (SEQUENCE)
);
INSERT INTO FOO VALUES(1, 10);
INSERT INTO FOO VALUES(2, 20);
INSERT INTO FOO VALUES(3, 30);

GRANT ALL ON FOODB TO 'equip'@127.0.0.1 IDENTIFIED BY 'password';
FLUSH PRIVILEGES;

in a mysql database called "FOODB" on the local host, with account name "equip" and password "password"...

This could be exposed as a tuple with 3 fields:

• field[0], tuple type name, "equip.data.sql.CustomTable.FOO"
• field[1], sequence number (SEQUENCE), in an IntBox
• field[2], value (INTVALUE), in an IntBox

using the following configuration (assuming that the storeId is "FooTable":

FooTable.url: jdbc:mysql://localhost:3306/FOODB
FooTable.user: equip
FooTable.password: password
FooTable.driver: com.mysql.jdbc.Driver
FooTable.readonly: false
FooTable.dataTableName: FOO
FooTable.dataKeyType: int
FooTable.dataKeyColumn: SEQUENCE
FooTable.dataKeyMapClass: equip.data.sql.DataKeyMapGetUnique
FooTable.dataKeyAllocateClass: equip.data.sql.DataKeyAllocateMax
#FooTable.dataNameColumn:
FooTable.helperTableName: EQUIPFOO
FooTable.tupleTypeName: equip.data.sql.CustomTable.FOO
FooTable.tupleSize: 2
FooTable.field1Type: int
FooTable.field1Column: SEQUENCE
FooTable.field2Type: int
FooTable.field2Column: INTVALUE

Author:

Chris Greenhalgh, 2003-10-27

Field Summary

(package private) java.sql.Connection	conn single shared connection
(package private) IDataKeyAllocate	dataKeyAllocateInstance config
(package private) java.lang.String	dataKeyColumn config
(package private) IDataKeyMap	dataKeyMapInstance config
(package private) java.lang.String	dataKeyType config
(package private) java.lang.String	dataNameColumn config (null if "NAME" in helper table)
(package private) java.lang.String	dataTableName config
(package private) static java.lang.String	DEFAULT_DATAKEY_COLUMN
(package private) static java.lang.String	DEFAULT_ID_COLUMN
(package private) static java.lang.String	DEFAULT_NAME_COLUMN
(package private) java.lang.String	getValuesQuery SELECT ...
(package private) java.lang.String	helperTableName config
(package private) boolean	readonly readonly?
(package private) GUID	responsible
(package private) java.lang.String[]	tupleFieldColumns config
(package private) java.lang.String[]	tupleFieldTypes config
(package private) int	tupleSize config
(package private) java.lang.String	tupleTypeName config
(package private) static java.lang.String	TYPE_CHAR
(package private) static java.lang.String	TYPE_DOUBLE
(package private) static java.lang.String	TYPE_FLOAT
(package private) static java.lang.String	TYPE_INT
(package private) static java.lang.String	TYPE_STRING

Constructor Summary

CustomTableDataStore(java.lang.String storeId, GUID responsible)
default constructor.

Method Summary

boolean	checkAdd(AddEvent add) check if store would like to/be prepared to handle this AddEvent.
protected java.util.Vector	doSQLQuery(java.lang.String query) sql query.
protected void	doSQLUpdate(java.lang.String update) sql update.
protected java.lang.String	fieldToSQLString(java.lang.String type, ValueBase field)
void	flush() Flush any pending persistent records
java.util.Enumeration	getCandidateItemBindings(ItemData[] itemTemplates) get the ItemBinding maintained by this store which should be considered when pattern matching the associated itemTemplates for an add/delete while present pattern.
java.util.Enumeration	getExpiredGUIDs(Time now) returns GUIDs of all leased items expiring at or before time 'now'.
Time	getFirstExpireTime() returns lowest (soonest, or furthest in past) expire time of any leased item in this store.
ItemBinding	getItemBinding(GUID id) get the ItemBinding for the given id iff it is maintained by this store, else null.
java.util.Enumeration	getRemoveResponsibleGUIDs(RemoveResponsible remove) get GUIDs of data items in this store which are process bound to the given responsible ID as per the RemoveResponsible event (or not, according to inverse flag).
boolean	handleAdd(AddEvent add) request that store handle the Add event, adding to itself accordingly.
boolean	handleDelete(DeleteEvent del) request that store handles the given delete, which it must iff it is currently maintaining state for the corresponding data item.
boolean	handleUpdate(UpdateEvent update) request that store handles the given update, which it must iff it is currently maintaining state for it.
boolean	holdsGUID(GUID id) check if store is maintaining state for the given GUID.
protected ValueBase	newTupleField(java.lang.String type, java.lang.String value) make a correctly typed typle field value
static GUID	parseGUID(java.lang.String guid) string to guid
protected java.lang.String	quoteType(java.lang.String type, java.lang.String value) to type-specific quoting if required
void	terminate() terminate - tidy up.
protected java.lang.Object	toNativeType(java.lang.String type, java.lang.String value) to type-specific java type
void	truncateExpireTimes(GUID responsible, Time expire) reduce lease on all leased items with given responsible id to expire at 'expire time'.

Methods inherited from class java.lang.Object

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

Field Detail

conn

java.sql.Connection conn

single shared connection

readonly

boolean readonly

readonly?

dataTableName

java.lang.String dataTableName

config

dataKeyType

java.lang.String dataKeyType

config

TYPE_INT

static final java.lang.String TYPE_INT

See Also:

Constant Field Values

TYPE_STRING

static final java.lang.String TYPE_STRING

See Also:

Constant Field Values

TYPE_FLOAT

static final java.lang.String TYPE_FLOAT

See Also:

Constant Field Values

TYPE_DOUBLE

static final java.lang.String TYPE_DOUBLE

See Also:

Constant Field Values

TYPE_CHAR

static final java.lang.String TYPE_CHAR

See Also:

Constant Field Values

dataKeyColumn

java.lang.String dataKeyColumn

config

dataKeyMapInstance

IDataKeyMap dataKeyMapInstance

config

dataKeyAllocateInstance

IDataKeyAllocate dataKeyAllocateInstance

config

dataNameColumn

java.lang.String dataNameColumn

config (null if "NAME" in helper table)

DEFAULT_NAME_COLUMN

static final java.lang.String DEFAULT_NAME_COLUMN

See Also:

Constant Field Values

DEFAULT_ID_COLUMN

static final java.lang.String DEFAULT_ID_COLUMN

See Also:

Constant Field Values

DEFAULT_DATAKEY_COLUMN

static final java.lang.String DEFAULT_DATAKEY_COLUMN

See Also:

Constant Field Values

helperTableName

java.lang.String helperTableName

config

tupleTypeName

java.lang.String tupleTypeName

config

tupleSize

int tupleSize

config

tupleFieldTypes

java.lang.String[] tupleFieldTypes

config

tupleFieldColumns

java.lang.String[] tupleFieldColumns

config

getValuesQuery

java.lang.String getValuesQuery

SELECT ... WHERE part of query to get data from data table

responsible

GUID responsible

Constructor Detail

CustomTableDataStore

public CustomTableDataStore(java.lang.String storeId,
                            GUID responsible)
                     throws DataStoreConfigurationException

default constructor.

Method Detail

handleAdd

public boolean handleAdd(AddEvent add)

request that store handle the Add event, adding to itself accordingly. Note: also has to handle lease updates.

Specified by:

handleAdd in interface IDataStore

Parameters:

add - The AddEvent to be handled.

Returns:

true iff this store has handled the add event; false if declined. (normally as indicated by a call to IDataStore.checkAdd

checkAdd

public boolean checkAdd(AddEvent add)

check if store would like to/be prepared to handle this AddEvent.

Specified by:

checkAdd in interface IDataStore

Parameters:

add - The AddEvent to be handled.

Returns:

true iff this store would be happy/able to handle it.

holdsGUID

public boolean holdsGUID(GUID id)

check if store is maintaining state for the given GUID.

Specified by:

holdsGUID in interface IDataStore

Parameters:

id - The GUID of the data item in question.

Returns:

true iff the store currently has state for this item.

handleUpdate

public boolean handleUpdate(UpdateEvent update)

request that store handles the given update, which it must iff it is currently maintaining state for it. Note: implies currently no migration of item state between store(s).

Specified by:

handleUpdate in interface IDataStore

Parameters:

update - the UpdateEvent to be handled.

Returns:

true iff the update has been handled (and necessarily the item's state is maintained by this store).

handleDelete

public boolean handleDelete(DeleteEvent del)

request that store handles the given delete, which it must iff it is currently maintaining state for the corresponding data item.

Specified by:

handleDelete in interface IDataStore

Returns:

true iff the delete has been handled (and necessarily the item's state was maintained by this store).

getRemoveResponsibleGUIDs

public java.util.Enumeration getRemoveResponsibleGUIDs(RemoveResponsible remove)

get GUIDs of data items in this store which are process bound to the given responsible ID as per the RemoveResponsible event (or not, according to inverse flag).

Specified by:

getRemoveResponsibleGUIDs in interface IDataStore

Parameters:

remove - the RemoveResponsible event.

Returns:

an Enumeration of the GUIDs of locally maintained data items that should now be deleted.

getItemBinding

public ItemBinding getItemBinding(GUID id)

get the ItemBinding for the given id iff it is maintained by this store, else null.

Specified by:

getItemBinding in interface IDataStore

Parameters:

id - the id of the data item being requested.

Returns:

the ItemBinding for that item, else null iff unknown to this store.

getCandidateItemBindings

public java.util.Enumeration getCandidateItemBindings(ItemData[] itemTemplates)

get the ItemBinding maintained by this store which should be considered when pattern matching the associated itemTemplates for an add/delete while present pattern.

Specified by:

getCandidateItemBindings in interface IDataStore

Parameters:

itemTemplates - array of template data items, else null or zero length list for a wild-card (any item).

Returns:

Enumeration of ItemBindings that should be considered (guaranteed to be a superset of possible matches).

getFirstExpireTime

public Time getFirstExpireTime()

returns lowest (soonest, or furthest in past) expire time of any leased item in this store.

Specified by:

getFirstExpireTime in interface IDataStore

Returns:

lowest (soonest, or furthest in past) expire time, else null.

getExpiredGUIDs

public java.util.Enumeration getExpiredGUIDs(Time now)

returns GUIDs of all leased items expiring at or before time 'now'.

Specified by:

getExpiredGUIDs in interface IDataStore

Parameters:

now - The current time of the expiration clock.

Returns:

Enumeration of GUIDs of now expiring data items which the call might now reasonably issue delete events for).

truncateExpireTimes

public void truncateExpireTimes(GUID responsible,
                                Time expire)

reduce lease on all leased items with given responsible id to expire at 'expire time'.

Specified by:

truncateExpireTimes in interface IDataStore

Parameters:

responsible - required item responsible id

expire - the new expire time for matched items

Returns:

none.

terminate

public void terminate()

terminate - tidy up.

Specified by:

terminate in interface IDataStore

doSQLQuery

protected java.util.Vector doSQLQuery(java.lang.String query)
                               throws java.sql.SQLException

sql query.

Returns:

Vector of Strings

Throws:

java.sql.SQLException

doSQLUpdate

protected void doSQLUpdate(java.lang.String update)
                    throws java.sql.SQLException

sql update.

Throws:

java.sql.SQLException

quoteType

protected java.lang.String quoteType(java.lang.String type,
                                     java.lang.String value)

to type-specific quoting if required

toNativeType

protected java.lang.Object toNativeType(java.lang.String type,
                                        java.lang.String value)

to type-specific java type

parseGUID

public static GUID parseGUID(java.lang.String guid)

string to guid

newTupleField

protected ValueBase newTupleField(java.lang.String type,
                                  java.lang.String value)

make a correctly typed typle field value

fieldToSQLString

protected java.lang.String fieldToSQLString(java.lang.String type,
                                            ValueBase field)

flush

public void flush()

Flush any pending persistent records

Specified by:

flush in interface IDataStore