org.sakaiproject.util.storage
Class BaseDbDoubleStorage

java.lang.Object
  extended byorg.sakaiproject.util.storage.BaseDbDoubleStorage
Direct Known Subclasses:
DbAnnouncementService.DbStorage, DbCalendarService.DbStorage, DbChatService.DbStorage, DbDiscussionService.DbStorage, DbMailArchiveService.DbStorage

public class BaseDbDoubleStorage
extends Object

BaseDbDoubleStorage is a class that stores Resources (of some type) in a database, %%% provides locked access, and generally implements a services "storage" class. The service's storage class can extend this to provide covers to turn Resource and Edit into something more type specific to the service.

Note: the methods here are all "id" based, with the following assumptions: - just the Resource Id field is enough to distinguish one Resource from another (or, for resource, the container's id and the resource id). - a resource's reference is based on no more than the resource id, for containers, and no more than resource and container id for resources. - a resource's id and container id cannot change. In order to handle Unicode characters properly, the SQL statements executed by this class should not embed Unicode characters into the SQL statement text; rather, Unicode values should be inserted as fields in a PreparedStatement. Databases handle Unicode better in fields.

Version:
$Revision: 3716 $
Author:
University of Michigan, CHEF Software Development Team

Field Summary
protected  String m_containerEntryTagName
          The xml tag name for the element holding each actual container entry.
protected static String[] M_containerExtraFields
          For container, the extra field is (no longer used) NEXT_ID
protected  String m_containerTableIdField
          The field in the table that holds the container id.
protected  String m_containerTableName
          Table name for container records.
protected  Hashtable m_locks
          Locks, keyed by reference, holding Connections (or, if locks are done locally, holding an Edit).
protected  boolean m_locksAreInDb
          If true, we do our locks in the remote database.
protected  boolean m_locksAreInTable
          If true, we do our locks in the remove database using a separate locking table.
protected  String m_resourceEntryTagName
          The xml tag name for the element holding each actual resource entry.
protected  String m_resourceTableContainerIdField
          The field in the resource table that holds the container id.
protected  String m_resourceTableDraftField
          The field in the record that has the draft indicator ('0' for no, '1' for yes).
protected  String m_resourceTableIdField
          The field in the resource table that holds the resource id.
protected  String m_resourceTableName
          Table name for resource records.
protected  String m_resourceTableOrderField
          The field name in the resource table for ordering.
protected  String[] m_resourceTableOtherFields
          The additional field names in the resource table that go between the two ids and the xml.
protected  String m_resourceTableOwnerField
          The field in the record that has the user id of the resource owner.
protected  String m_resourceTablePubViewField
          The field in the record that has the pubview indicator ('0' for no, '1' for yes).
protected  SqlService m_sql
          Injected (by constructor) SqlService.
protected  StorageUser m_user
          The StorageUser to callback for new Resource and Edit objects.
 
Constructor Summary
BaseDbDoubleStorage(String containerTableName, String containerTableIdField, String resourceTableName, String resourceTableIdField, String resourceTableContainerIdField, String resourceTableOrderField, String resourceTableOwnerField, String resourceTableDraftField, String resourceTablePubViewField, String[] resourceTableOtherFields, boolean locksInDb, String containerEntryName, String resourceEntryName, StorageUser user, SqlService sqlService)
          Construct.
 
Method Summary
 void cancelContainer(Edit edit)
          Cancel the changes and release the lock.
 void cancelResource(Entity container, Edit edit)
          Cancel the changes and release the lock.
 boolean checkContainer(String ref)
          Check if a Container by this id exists.
 boolean checkResource(Entity container, String id)
          Check if a Resource by this id exists.
 void close()
          Close.
 void commitContainer(Edit edit)
          Commit the changes and release the lock.
 void commitResource(Entity container, Edit edit)
          Commit the changes and release the lock.
 Edit editContainer(String ref)
          Get a lock on the Container with this id, or null if a lock cannot be gotten.
 Edit editResource(Entity container, String id)
          Get a lock on the Resource with this id, or null if a lock cannot be gotten.
 List getAllContainers()
          Get all Containers.
 List getAllResources(Entity container)
          Get all Resources.
 Entity getContainer(String ref)
          Get the Container with this id, or null if not found.
 List getContainerIdsMatching(String root)
          Access a list of container ids match (start with) the root.
 Entity getResource(Entity container, String id)
          Get the Resource with this id, or null if not found.
 List getResources(Entity container, Time afterDate, int limitedToLatest, String draftsForId, boolean pubViewOnly)
          Get resources filtered by date and count and drafts, in descending (latest first) order
protected  String insertFields(String before1, String before2, String[] fields, String after)
          Form a string of (field, field, field), for sql insert statements, one for each item in the fields array, plus one before, and one after.
 void open()
          Open and be ready to read / write.
 Edit putContainer(String ref)
          Add a new Container with this id.
 Edit putResource(Entity container, String id, Object[] others)
          Add a new Resource with this id.
protected  Entity readContainer(String xml)
          Read one Container Resource from xml
protected  Entity readResource(Entity container, String xml)
          Read one Resource from xml
 void removeContainer(Edit edit)
          Remove this (locked) Container.
 void removeResource(Entity container, Edit edit)
          Remove this (locked) Resource.
protected  String updateSet(String[] fields)
          Form a string of n name=?
protected  String valuesParams(String[] fields)
          Form a string of n question marks with commas, for sql value statements, one for each item in the values array, or an empty string if null.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

m_containerTableName

protected String m_containerTableName
Table name for container records.


m_containerTableIdField

protected String m_containerTableIdField
The field in the table that holds the container id.


m_resourceTableName

protected String m_resourceTableName
Table name for resource records.


m_resourceTableIdField

protected String m_resourceTableIdField
The field in the resource table that holds the resource id.


m_resourceTableContainerIdField

protected String m_resourceTableContainerIdField
The field in the resource table that holds the container id.


m_resourceTableOtherFields

protected String[] m_resourceTableOtherFields
The additional field names in the resource table that go between the two ids and the xml.


m_resourceTableOrderField

protected String m_resourceTableOrderField
The field name in the resource table for ordering.


m_resourceEntryTagName

protected String m_resourceEntryTagName
The xml tag name for the element holding each actual resource entry.


m_containerEntryTagName

protected String m_containerEntryTagName
The xml tag name for the element holding each actual container entry.


m_resourceTableOwnerField

protected String m_resourceTableOwnerField
The field in the record that has the user id of the resource owner.


m_resourceTableDraftField

protected String m_resourceTableDraftField
The field in the record that has the draft indicator ('0' for no, '1' for yes).


m_resourceTablePubViewField

protected String m_resourceTablePubViewField
The field in the record that has the pubview indicator ('0' for no, '1' for yes).


m_locksAreInDb

protected boolean m_locksAreInDb
If true, we do our locks in the remote database.


m_locksAreInTable

protected boolean m_locksAreInTable
If true, we do our locks in the remove database using a separate locking table.


m_user

protected StorageUser m_user
The StorageUser to callback for new Resource and Edit objects.


m_locks

protected Hashtable m_locks
Locks, keyed by reference, holding Connections (or, if locks are done locally, holding an Edit). Note: keying by reference allows botu container and resource locks to be stored, the reference distinguishes them.


M_containerExtraFields

protected static final String[] M_containerExtraFields
For container, the extra field is (no longer used) NEXT_ID


m_sql

protected SqlService m_sql
Injected (by constructor) SqlService.

Constructor Detail

BaseDbDoubleStorage

public BaseDbDoubleStorage(String containerTableName,
                           String containerTableIdField,
                           String resourceTableName,
                           String resourceTableIdField,
                           String resourceTableContainerIdField,
                           String resourceTableOrderField,
                           String resourceTableOwnerField,
                           String resourceTableDraftField,
                           String resourceTablePubViewField,
                           String[] resourceTableOtherFields,
                           boolean locksInDb,
                           String containerEntryName,
                           String resourceEntryName,
                           StorageUser user,
                           SqlService sqlService)
Construct.

Parameters:
containerTableName - Table name for containers.
containerTableIdField - The field in the container table that holds the id.
resourceTableName - Table name for resources.
resourceTableIdField - The field in the resource table that holds the id.
resourceTableContainerIdField - The field in the resource table that holds the container id.
resourceTableOrderField - The field in the resource table that is used for ordering results.
resourceTableOtherFields - The other fields in the resource table (between the two id fields and the xml field).
locksInDb - If true, we do our locks in the remote database, otherwise we do them here.
containerEntryName - The xml tag name for the element holding each actual container entry.
resourceEntryName - The xml tag name for the element holding each actual resource entry.
user - The StorageUser class to call back for creation of Resource and Edit objects.
sqlService - The SqlService.
Method Detail

open

public void open()
Open and be ready to read / write.


close

public void close()
Close.


readContainer

protected Entity readContainer(String xml)
Read one Container Resource from xml

Parameters:
xml - An string containing the xml which describes the Container resource.
Returns:
The Container Resource object created from the xml.

checkContainer

public boolean checkContainer(String ref)
Check if a Container by this id exists.

Parameters:
ref - The container reference.
Returns:
true if a Container by this id exists, false if not.

getContainer

public Entity getContainer(String ref)
Get the Container with this id, or null if not found.

Parameters:
ref - The container reference.
Returns:
The Container with this id, or null if not found.

getAllContainers

public List getAllContainers()
Get all Containers.

Returns:
The list (Resource) of all Containers.

putContainer

public Edit putContainer(String ref)
Add a new Container with this id.

Parameters:
ref - The container reference.
Returns:
The locked Container object with this id, or null if the id is in use.

editContainer

public Edit editContainer(String ref)
Get a lock on the Container with this id, or null if a lock cannot be gotten.

Parameters:
ref - The container reference.
Returns:
The locked Container with this id, or null if this cannot be locked.

commitContainer

public void commitContainer(Edit edit)
Commit the changes and release the lock.


cancelContainer

public void cancelContainer(Edit edit)
Cancel the changes and release the lock.


removeContainer

public void removeContainer(Edit edit)
Remove this (locked) Container.


readResource

protected Entity readResource(Entity container,
                              String xml)
Read one Resource from xml

Parameters:
container - The container for this resource.
xml - An string containing the xml which describes the resource.
Returns:
The Resource object created from the xml.

checkResource

public boolean checkResource(Entity container,
                             String id)
Check if a Resource by this id exists.

Parameters:
container - The container for this resource.
id - The id.
Returns:
true if a Resource by this id exists, false if not.

getResource

public Entity getResource(Entity container,
                          String id)
Get the Resource with this id, or null if not found.

Parameters:
container - The container for this resource.
id - The id.
Returns:
The Resource with this id, or null if not found.

getAllResources

public List getAllResources(Entity container)
Get all Resources.

Parameters:
container - The container for this resource.
Returns:
The list (Resource) of all Resources.

putResource

public Edit putResource(Entity container,
                        String id,
                        Object[] others)
Add a new Resource with this id.

Parameters:
container - The container for this resource.
id - The id.
others - Other fields for the newResource call
Returns:
The locked Resource object with this id, or null if the id is in use.

editResource

public Edit editResource(Entity container,
                         String id)
Get a lock on the Resource with this id, or null if a lock cannot be gotten.

Parameters:
container - The container for this resource.
id - The user id.
Returns:
The locked Resource with this id, or null if this records cannot be locked.

commitResource

public void commitResource(Entity container,
                           Edit edit)
Commit the changes and release the lock.

Parameters:
container - The container for this resource.

cancelResource

public void cancelResource(Entity container,
                           Edit edit)
Cancel the changes and release the lock.

Parameters:
container - The container for this resource.

removeResource

public void removeResource(Entity container,
                           Edit edit)
Remove this (locked) Resource.

Parameters:
container - The container for this resource.

valuesParams

protected String valuesParams(String[] fields)
Form a string of n question marks with commas, for sql value statements, one for each item in the values array, or an empty string if null.

Returns:
A sql statement fragment for the values part of an insert, one for each value in the array.

updateSet

protected String updateSet(String[] fields)
Form a string of n name=?, for sql update set statements, one for each item in the values array, or an empty string if null.

Returns:
A sql statement fragment for the values part of an insert, one for each value in the array.

insertFields

protected String insertFields(String before1,
                              String before2,
                              String[] fields,
                              String after)
Form a string of (field, field, field), for sql insert statements, one for each item in the fields array, plus one before, and one after.

Parameters:
before1 - The first field name.
before2 - (options) second field name.
after - The last field name.
Returns:
A sql statement fragment for the insert fields.

getResources

public List getResources(Entity container,
                         Time afterDate,
                         int limitedToLatest,
                         String draftsForId,
                         boolean pubViewOnly)
Get resources filtered by date and count and drafts, in descending (latest first) order

Parameters:
afterDate - if null, no date limit, else limited to only messages after this date.
limitedToLatest - if 0, no count limit, else limited to only the latest this number of messages.
draftsForId - how to handle drafts: null means no drafts, "*" means all, otherwise drafts only if created by this userId.
pubViewOnly - if true, include only messages marked pubview, else include any.
Returns:
A list of Message objects that meet the criteria; may be empty

getContainerIdsMatching

public List getContainerIdsMatching(String root)
Access a list of container ids match (start with) the root.

Returns:
A List (String) of container id which match the root.