org.hackystat.sensorbase.db
Class DbImplementation

java.lang.Object
  extended by org.hackystat.sensorbase.db.DbImplementation
Direct Known Subclasses:
DerbyImplementation

public abstract class DbImplementation
extends java.lang.Object

Provides a specification of the operations that must be implemented by every SensorBase storage system. Also provides some 'helper' methods, which return the Managers for the various resources.

Author:
Philip Johnson

Field Summary
protected  java.util.logging.Logger logger
          Keep a pointer to the Logger.
protected  Server server
          Keeps a pointer to this Server for use in accessing the managers.
 
Constructor Summary
DbImplementation(Server server)
          Constructs a new DbImplementation.
 
Method Summary
abstract  boolean compressTables()
          Databases like Derby require an explicit compress command for releasing disk space after a large number of rows have been deleted.
abstract  void deleteProject(User owner, java.lang.String projectName)
          Ensures that the Project with the given owner and projectName is no longer present in the db.
abstract  void deleteSensorData(User user)
          Ensures that sensor data with the given user is no longer present in this manager.
abstract  void deleteSensorData(User user, javax.xml.datatype.XMLGregorianCalendar timestamp)
          Ensures that sensor data with the given user and timestamp is no longer present in this manager.
abstract  void deleteSensorDataType(java.lang.String sdtName)
          Ensures that the SensorDataType with the given name is no longer present in this manager.
abstract  void deleteUser(java.lang.String email)
          Ensures that the User with the given email is no longer present in this manager.
abstract  java.lang.String getProject(User owner, java.lang.String projectName)
          Returns the Project instance as XML string, or null if not found.
abstract  java.lang.String getProjectIndex()
          Returns the XML ProjectIndex for all Projects in this server.
protected  ProjectManager getProjectManager()
          Returns the ProjectManager associated with this server.
abstract  java.lang.String getProjectSensorDataSnapshot(java.util.List<User> users, javax.xml.datatype.XMLGregorianCalendar startTime, javax.xml.datatype.XMLGregorianCalendar endTime, java.util.List<java.lang.String> uriPatterns, java.lang.String sdt, java.lang.String tool)
          Returns an XML SensorDataIndex to sensor data for the given time interval and sdt with the most recent runtime value.
abstract  ProjectSummary getProjectSummary(java.util.List<User> users, javax.xml.datatype.XMLGregorianCalendar startTime, javax.xml.datatype.XMLGregorianCalendar endTime, java.util.List<java.lang.String> uriPatterns, java.lang.String href)
          Returns a ProjectSummary instance constructed for the given Project between the startTime and endTime.
abstract  int getRowCount(java.lang.String table)
          Returns the current number of rows in the specified table.
protected  SdtManager getSdtManager()
          Returns the SdtManager associated with this server.
abstract  java.lang.String getSensorData(User user, javax.xml.datatype.XMLGregorianCalendar timestamp)
          Returns the SensorData instance as XML string, or null if not found.
abstract  java.lang.String getSensorDataIndex()
          Returns the XML SensorDataIndex for all sensor data in this server.
abstract  java.lang.String getSensorDataIndex(java.util.List<User> users, javax.xml.datatype.XMLGregorianCalendar startTime, javax.xml.datatype.XMLGregorianCalendar endTime, java.util.List<java.lang.String> uriPatterns, int startIndex, int maxInstances)
          Returns the XML SensorDataIndex for all sensor data matching these users, start/end time, and whose resource string matches at least one in the list of UriPatterns.
abstract  java.lang.String getSensorDataIndex(java.util.List<User> users, javax.xml.datatype.XMLGregorianCalendar startTime, javax.xml.datatype.XMLGregorianCalendar endTime, java.util.List<java.lang.String> uriPatterns, java.lang.String sdt)
          Returns an XML SensorDataIndex representing the SensorData for the given user between start and end time whose resource string matches at least one of the UriPatterns.
abstract  java.lang.String getSensorDataIndex(java.util.List<User> users, javax.xml.datatype.XMLGregorianCalendar startTime, javax.xml.datatype.XMLGregorianCalendar endTime, java.util.List<java.lang.String> uriPatterns, java.lang.String sdt, java.lang.String tool)
          Returns an XML SensorDataIndex representing the SensorData for the given user between start and end time whose resource string matches at least one of the UriPatterns.
abstract  java.lang.String getSensorDataIndex(User user)
          Returns the XML SensorDataIndex for all sensor data for this user.
abstract  java.lang.String getSensorDataIndex(User user, java.lang.String sdtName)
          Returns the XML SensorDataIndex for all sensor data for this user and sensor data type.
abstract  java.lang.String getSensorDataIndexLastMod(User user, javax.xml.datatype.XMLGregorianCalendar lastModStartTime, javax.xml.datatype.XMLGregorianCalendar lastModEndTime)
          Returns the XML SensorDataIndex for all sensor data for the given user that arrived at the server since the given start and end timestamps.
protected  SensorDataManager getSensorDataManager()
          Returns the SensorDataManager associated with this server.
abstract  java.lang.String getSensorDataType(java.lang.String sdtName)
          Returns the SensorDataType instance as XML string, or null if not found.
abstract  java.lang.String getSensorDataTypeIndex()
          Returns the XML SensorDataTypeIndex for all SDTs in this server.
abstract  java.util.Set<java.lang.String> getTableNames()
          Returns a set containing the names of all tables in this database.
abstract  java.lang.String getUser(java.lang.String email)
          Returns the User instance as XML string, or null if not found.
abstract  java.lang.String getUserIndex()
          Returns the XML UserIndex for all Users in this server.
protected  UserManager getUserManager()
          Returns the UserManager associated with this server.
abstract  boolean hasSensorData(User user, javax.xml.datatype.XMLGregorianCalendar timestamp)
          Returns true if the passed [key, timestamp] has sensor data defined for it.
abstract  boolean indexTables()
          The most appropriate set of indexes for the database has been evolving over time as we develop new queries.
abstract  void initialize()
          To be called as part of the startup process for a storage system.
abstract  boolean isFreshlyCreated()
          Returns true if the initialize() method did indeed create a fresh storage system.
abstract  boolean storeProject(Project project, java.lang.String xmlProject, java.lang.String xmlProjectRef)
          Persists a Project instance.
abstract  boolean storeSensorData(SensorData data, java.lang.String xmlSensorData, java.lang.String xmlSensorDataRef)
          Persists a SensorData instance.
abstract  boolean storeSensorDataType(SensorDataType sdt, java.lang.String xmlSensorDataType, java.lang.String xmlSensorDataTypeRef)
          Persists a SensorDataType instance.
abstract  boolean storeUser(User user, java.lang.String xmlUser, java.lang.String xmlUserRef)
          Persists a User instance.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

server

protected Server server
Keeps a pointer to this Server for use in accessing the managers.


logger

protected java.util.logging.Logger logger
Keep a pointer to the Logger.

Constructor Detail

DbImplementation

public DbImplementation(Server server)
Constructs a new DbImplementation.

Parameters:
server - The server.
Method Detail

initialize

public abstract void initialize()
To be called as part of the startup process for a storage system. This method should:


isFreshlyCreated

public abstract boolean isFreshlyCreated()
Returns true if the initialize() method did indeed create a fresh storage system. This is used by the ResourceManagers to determine if they should read in default data or not.

Returns:
True if the storage system is freshly created.

getSensorDataIndex

public abstract java.lang.String getSensorDataIndex()
Returns the XML SensorDataIndex for all sensor data in this server.

Returns:
The XML String containing an index to all Sensor Data.

getSensorDataIndex

public abstract java.lang.String getSensorDataIndex(User user)
Returns the XML SensorDataIndex for all sensor data for this user.

Parameters:
user - The User whose sensor data is to be returned.
Returns:
The XML String providing an index of all relevent sensor data resources.

getSensorDataIndex

public abstract java.lang.String getSensorDataIndex(User user,
                                                    java.lang.String sdtName)
Returns the XML SensorDataIndex for all sensor data for this user and sensor data type.

Parameters:
user - The User whose sensor data is to be returned.
sdtName - The sensor data type name.
Returns:
The XML String providing an index of all relevent sensor data resources.

getSensorDataIndex

public abstract java.lang.String getSensorDataIndex(java.util.List<User> users,
                                                    javax.xml.datatype.XMLGregorianCalendar startTime,
                                                    javax.xml.datatype.XMLGregorianCalendar endTime,
                                                    java.util.List<java.lang.String> uriPatterns,
                                                    java.lang.String sdt)
Returns an XML SensorDataIndex representing the SensorData for the given user between start and end time whose resource string matches at least one of the UriPatterns.

Parameters:
users - The list of users whose SensorData will be returned.
startTime - The earliest Sensor Data to be returned.
endTime - The latest SensorData to be returned.
uriPatterns - At least one UriPattern must match the SensorData resource field.
sdt - The SDT of interest, or null if data from all SDTs should be retrieved.
Returns:
An XML String containing a SensorDataIndex of matching SensorData.

getSensorDataIndex

public abstract java.lang.String getSensorDataIndex(java.util.List<User> users,
                                                    javax.xml.datatype.XMLGregorianCalendar startTime,
                                                    javax.xml.datatype.XMLGregorianCalendar endTime,
                                                    java.util.List<java.lang.String> uriPatterns,
                                                    java.lang.String sdt,
                                                    java.lang.String tool)
Returns an XML SensorDataIndex representing the SensorData for the given user between start and end time whose resource string matches at least one of the UriPatterns.

Parameters:
users - The list of users whose SensorData will be returned.
startTime - The earliest Sensor Data to be returned.
endTime - The latest SensorData to be returned.
uriPatterns - At least one UriPattern must match the SensorData resource field.
sdt - The SDT of interest. Should not be null.
tool - The tool of interest. Should not be null.
Returns:
An XML String containing a SensorDataIndex of matching SensorData.

getSensorDataIndex

public abstract java.lang.String getSensorDataIndex(java.util.List<User> users,
                                                    javax.xml.datatype.XMLGregorianCalendar startTime,
                                                    javax.xml.datatype.XMLGregorianCalendar endTime,
                                                    java.util.List<java.lang.String> uriPatterns,
                                                    int startIndex,
                                                    int maxInstances)
Returns the XML SensorDataIndex for all sensor data matching these users, start/end time, and whose resource string matches at least one in the list of UriPatterns. Client must guarantee that startTime and endTime are within Project dates, and that startIndex and maxInstances are non-negative.

Parameters:
users - The users.
startTime - The start time.
endTime - The end time.
uriPatterns - A list of UriPatterns.
startIndex - The starting index.
maxInstances - The maximum number of instances to return.
Returns:
The XML SensorDataIndex string corresponding to the matching sensor data.

getSensorDataIndexLastMod

public abstract java.lang.String getSensorDataIndexLastMod(User user,
                                                           javax.xml.datatype.XMLGregorianCalendar lastModStartTime,
                                                           javax.xml.datatype.XMLGregorianCalendar lastModEndTime)
Returns the XML SensorDataIndex for all sensor data for the given user that arrived at the server since the given start and end timestamps. This method uses the LastMod timestamp rather than the "regular" timestamp, and is used for real-time monitoring of data arriving at the server.

Parameters:
user - The user whose data is being monitored.
lastModStartTime - The beginning lastMod timestamp of interest.
lastModEndTime - The ending lastMod timestamp of interest.
Returns:
The XML SensorDataIndex for the recently arrived data based upon the lastMod tstamps.

getProjectSensorDataSnapshot

public abstract java.lang.String getProjectSensorDataSnapshot(java.util.List<User> users,
                                                              javax.xml.datatype.XMLGregorianCalendar startTime,
                                                              javax.xml.datatype.XMLGregorianCalendar endTime,
                                                              java.util.List<java.lang.String> uriPatterns,
                                                              java.lang.String sdt,
                                                              java.lang.String tool)
Returns an XML SensorDataIndex to sensor data for the given time interval and sdt with the most recent runtime value. This constitutes the "snapshot" of the data with the given sdt. If the tool parameter is null, then the last runtime snapshot is returned without regard to the tool.

Parameters:
users - The list of users whose sensor data will be checked.
startTime - The start time.
endTime - The end time.
uriPatterns - The uripatterns that must match the resource string.
sdt - The sensor data type of interest.
tool - The tool of interest, or null if any tool is OK.
Returns:
A string containing the XML representation of the SensorDataIndex for this snapshot.

getSensorData

public abstract java.lang.String getSensorData(User user,
                                               javax.xml.datatype.XMLGregorianCalendar timestamp)
Returns the SensorData instance as XML string, or null if not found.

Parameters:
user - The user.
timestamp - The timestamp associated with this sensor data.
Returns:
The SensorData XML string, or null.

hasSensorData

public abstract boolean hasSensorData(User user,
                                      javax.xml.datatype.XMLGregorianCalendar timestamp)
Returns true if the passed [key, timestamp] has sensor data defined for it.

Parameters:
user - The user.
timestamp - The timestamp
Returns:
True if there is any sensor data for this [key, sdtName, timestamp].

storeSensorData

public abstract boolean storeSensorData(SensorData data,
                                        java.lang.String xmlSensorData,
                                        java.lang.String xmlSensorDataRef)
Persists a SensorData instance. If SensorData with this [email, timestamp] already exists in the storage system, it should be overwritten.

Parameters:
data - The sensor data.
xmlSensorData - The SensorData marshalled into an XML String.
xmlSensorDataRef - The corresponding SensorDataRef marshalled into an XML String
Returns:
True if the sensor data was successfully inserted.

deleteSensorData

public abstract void deleteSensorData(User user,
                                      javax.xml.datatype.XMLGregorianCalendar timestamp)
Ensures that sensor data with the given user and timestamp is no longer present in this manager.

Parameters:
user - The user.
timestamp - The timestamp associated with this sensor data.

deleteSensorData

public abstract void deleteSensorData(User user)
Ensures that sensor data with the given user is no longer present in this manager.

Parameters:
user - The user.

getSensorDataTypeIndex

public abstract java.lang.String getSensorDataTypeIndex()
Returns the XML SensorDataTypeIndex for all SDTs in this server.

Returns:
The XML String containing an index to all SensorDataTypes.

getSensorDataType

public abstract java.lang.String getSensorDataType(java.lang.String sdtName)
Returns the SensorDataType instance as XML string, or null if not found.

Parameters:
sdtName - The SDT name.
Returns:
The SensorDataType XML string, or null.

storeSensorDataType

public abstract boolean storeSensorDataType(SensorDataType sdt,
                                            java.lang.String xmlSensorDataType,
                                            java.lang.String xmlSensorDataTypeRef)
Persists a SensorDataType instance. If a SensorDataType with this name already exists in the storage system, it will be overwritten.

Parameters:
sdt - The sensor data type
xmlSensorDataType - The SensorDataType marshalled into an XML String.
xmlSensorDataTypeRef - The corresponding SensorDataTypeRef marshalled into an XML String
Returns:
True if the SDT was successfully inserted.

deleteSensorDataType

public abstract void deleteSensorDataType(java.lang.String sdtName)
Ensures that the SensorDataType with the given name is no longer present in this manager.

Parameters:
sdtName - The SDT name.

getUserIndex

public abstract java.lang.String getUserIndex()
Returns the XML UserIndex for all Users in this server.

Returns:
The XML String containing an index to all Users.

getUser

public abstract java.lang.String getUser(java.lang.String email)
Returns the User instance as XML string, or null if not found.

Parameters:
email - The user's email.
Returns:
The User XML string, or null.

storeUser

public abstract boolean storeUser(User user,
                                  java.lang.String xmlUser,
                                  java.lang.String xmlUserRef)
Persists a User instance. If a User with this name already exists in the storage system, it will be overwritten.

Parameters:
user - The user
xmlUser - The User marshalled into an XML String.
xmlUserRef - The corresponding UserRef marshalled into an XML String
Returns:
True if the user was successfully inserted.

deleteUser

public abstract void deleteUser(java.lang.String email)
Ensures that the User with the given email is no longer present in this manager.

Parameters:
email - The user's email address.

getProjectIndex

public abstract java.lang.String getProjectIndex()
Returns the XML ProjectIndex for all Projects in this server.

Returns:
The XML String containing an index to all Projects.

getProject

public abstract java.lang.String getProject(User owner,
                                            java.lang.String projectName)
Returns the Project instance as XML string, or null if not found.

Parameters:
owner - The user who owns the project.
projectName - The name of the Project.
Returns:
The Project XML string, or null.

storeProject

public abstract boolean storeProject(Project project,
                                     java.lang.String xmlProject,
                                     java.lang.String xmlProjectRef)
Persists a Project instance. If a Project with this owner and name already exists in the storage system, it will be overwritten.

Parameters:
project - The Project.
xmlProject - The Project marshalled into an XML String.
xmlProjectRef - The corresponding ProjectRef marshalled into an XML String
Returns:
True if the user was successfully inserted.

deleteProject

public abstract void deleteProject(User owner,
                                   java.lang.String projectName)
Ensures that the Project with the given owner and projectName is no longer present in the db.

Parameters:
owner - The User who owns this project.
projectName - The name of the Project.

getProjectSummary

public abstract ProjectSummary getProjectSummary(java.util.List<User> users,
                                                 javax.xml.datatype.XMLGregorianCalendar startTime,
                                                 javax.xml.datatype.XMLGregorianCalendar endTime,
                                                 java.util.List<java.lang.String> uriPatterns,
                                                 java.lang.String href)
Returns a ProjectSummary instance constructed for the given Project between the startTime and endTime. This summary provides a breakdown of the number of sensor data instances found of the given type during the given time period.

Parameters:
users - The users in this project.
startTime - The startTime
endTime - The endTime.
uriPatterns - The UriPatterns for this project.
href - The URL naming this resource.
Returns:
The ProjectSummary instance.

getUserManager

protected UserManager getUserManager()
Returns the UserManager associated with this server. Since the DbManager is initialized before all other managers, we will simply get these other Managers on demand and not cache them.

Returns:
The User Manager.

getSensorDataManager

protected SensorDataManager getSensorDataManager()
Returns the SensorDataManager associated with this server. Since the DbManager is initialized before all other managers, we will simply get these other Managers on demand and not cache them.

Returns:
The Sensor Data Manager.

getSdtManager

protected SdtManager getSdtManager()
Returns the SdtManager associated with this server. Since the DbManager is initialized before all other managers, we will simply get these other Managers on demand and not cache them.

Returns:
The SdtManager.

getProjectManager

protected ProjectManager getProjectManager()
Returns the ProjectManager associated with this server. Since the DbManager is initialized before all other managers, we will simply get these other Managers on demand and not cache them.

Returns:
The ProjectManager.

compressTables

public abstract boolean compressTables()
Databases like Derby require an explicit compress command for releasing disk space after a large number of rows have been deleted. This operation invokes the compress command on all tables in the database. If a database implementation does not support explicit compression, then this command should do nothing but return true.

Returns:
True if the compress command succeeded or if the database does not support compression.

indexTables

public abstract boolean indexTables()
The most appropriate set of indexes for the database has been evolving over time as we develop new queries. This command sets up the appropriate set of indexes. It should be able to be called repeatedly without error.

Returns:
True if the index commands succeeded.

getRowCount

public abstract int getRowCount(java.lang.String table)
Returns the current number of rows in the specified table.

Parameters:
table - The table whose rows are to be counted.
Returns:
The number of rows in the table, or -1 if the table does not exist or an error occurs.

getTableNames

public abstract java.util.Set<java.lang.String> getTableNames()
Returns a set containing the names of all tables in this database. Used by clients to invoke getRowCount with a legal table name.

Returns:
A set of table names.