org.sakaiproject.component.legacy.digest
Class BaseDigestService

java.lang.Object
  extended byorg.sakaiproject.component.legacy.digest.BaseDigestService
All Implemented Interfaces:
DigestService, Runnable, StorageUser
Direct Known Subclasses:
DbDigestService

public abstract class BaseDigestService
extends Object
implements DigestService, StorageUser, Runnable

BaseDigestService is the base service for DigestService.

Version:
$Revision: 6016 $
Author:
University of Michigan, Sakai Software Development Team

Nested Class Summary
 class BaseDigestService.BaseDigest
          Digest implementation
protected static interface BaseDigestService.Storage
          Storage
 
Field Summary
protected  List m_digestQueue
          The queue of digests waiting to be added (DigestMessage).
protected  String m_lastSendPeriod
          The time period last time the sendDigests() was called.
protected  Logger m_logger
          Dependency: logging service
protected  MemoryService m_memoryService
          Dependency: MemoryService.
protected  String m_relativeAccessPoint
          The initial portion of a relative access point URL.
protected  boolean m_sendDigests
          True if we are in the mode of sending out digests, false if we are waiting.
protected  BaseDigestService.Storage m_storage
          Storage manager for this service.
protected  Thread m_thread
          The thread I run my periodic clean and report on.
protected  boolean m_threadStop
          My thread's quit flag.
protected  TimeService m_timeService
          Dependency: TimeService.
protected static long PERIOD
          How long to wait between runnable runs (ms).
 
Fields inherited from interface org.sakaiproject.service.legacy.digest.DigestService
REFERENCE_ROOT, SECURE_ADD_DIGEST, SECURE_EDIT_DIGEST, SECURE_REMOVE_DIGEST, SERVICE_NAME
 
Constructor Summary
BaseDigestService()
           
 
Method Summary
 DigestEdit add(String id)
          Add a new set of digest with this id.
 void cancel(DigestEdit edit)
          Cancel the changes made to a DigestEdit object, and release the lock.
 void commit(DigestEdit edit)
          Commit the changes made to a DigestEdit object, and release the lock.
protected  TimeRange computeRange(Time time)
          Compute a time range based on a specific time.
 void destroy()
          Returns to uninitialized state.
 void digest(DigestMessage message)
          Add a new message to a digest, creating one if needed.
protected  String digestId(String ref)
          Access the digest id extracted from a digest reference.
 String digestReference(String id)
          Access the internal reference which can be used to access the resource from within the system.
 DigestEdit edit(String id)
          Get a locked Digest object for editing.
protected  BaseDigestService.BaseDigest findDigest(String id)
          Find the digest object, in cache or storage.
protected  String getAccessPoint(boolean relative)
          Access the partial URL that forms the root of resource URLs.
 Time getDate(Entity r)
          Access the resource date.
 Digest getDigest(String id)
          Access digest associated with this id.
 List getDigests()
          Access all digest objects.
 String getOwnerId(Entity r)
          Access the resource owner user id.
 void init()
          Final initialization, once all dependencies are set.
 boolean isDraft(Entity r)
          Check if this resource is in draft mode.
 Entity newContainer(Element element)
          Construct a new container resource, from an XML element.
 Entity newContainer(Entity other)
          Construct a new container resource, as a copy of another
 Entity newContainer(String ref)
          Construct a new continer given just an id.
 Edit newContainerEdit(Element element)
          Construct a new container resource, from an XML element.
 Edit newContainerEdit(Entity other)
          Construct a new container resource, as a copy of another
 Edit newContainerEdit(String ref)
          Construct a new continer given just an id.
 Entity newResource(Entity container, Element element)
          Construct a new resource, from an XML element.
 Entity newResource(Entity container, Entity other)
          Construct a new resource from another resource of the same type.
 Entity newResource(Entity container, String id, Object[] others)
          Construct a new resource given just an id.
 Edit newResourceEdit(Entity container, Element element)
          Construct a new resource, from an XML element.
 Edit newResourceEdit(Entity container, Entity other)
          Construct a new resource from another resource of the same type.
 Edit newResourceEdit(Entity container, String id, Object[] others)
          Construct a new resource given just an id.
protected abstract  BaseDigestService.Storage newStorage()
          Construct storage for this service.
protected  void processQueue()
          Attempt to process all the queued digest requests.
 void remove(DigestEdit edit)
          Remove this DigestEdit - it must be locked from edit().
 void run()
          Run the clean and report thread.
protected  void send(String id, List msgs, TimeRange period)
          Send a single digest message
protected  void sendDigests()
          If it's time, send out any digested messages.
 void setLogger(Logger service)
          Dependency: logging service.
 void setMemoryService(MemoryService service)
          Dependency: MemoryService.
 void setTimeService(TimeService service)
          Dependency: TimeService.
protected  void start()
          Start the clean and report thread.
protected  void stop()
          Stop the clean and report thread.
 Object[] storageFields(Entity r)
          Collect the fields that need to be stored outside the XML (for the resource).
protected  void unlock(String lock, String resource)
          Check security permission.
protected  boolean unlockCheck(String lock, String resource)
          Check security permission.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

m_storage

protected BaseDigestService.Storage m_storage
Storage manager for this service.


m_relativeAccessPoint

protected String m_relativeAccessPoint
The initial portion of a relative access point URL.


m_digestQueue

protected List m_digestQueue
The queue of digests waiting to be added (DigestMessage).


m_thread

protected Thread m_thread
The thread I run my periodic clean and report on.


m_threadStop

protected boolean m_threadStop
My thread's quit flag.


PERIOD

protected static final long PERIOD
How long to wait between runnable runs (ms).

See Also:
Constant Field Values

m_sendDigests

protected boolean m_sendDigests
True if we are in the mode of sending out digests, false if we are waiting.


m_lastSendPeriod

protected String m_lastSendPeriod
The time period last time the sendDigests() was called.


m_logger

protected Logger m_logger
Dependency: logging service


m_memoryService

protected MemoryService m_memoryService
Dependency: MemoryService.


m_timeService

protected TimeService m_timeService
Dependency: TimeService.

Constructor Detail

BaseDigestService

public BaseDigestService()
Method Detail

start

protected void start()
Start the clean and report thread.


stop

protected void stop()
Stop the clean and report thread.


run

public void run()
Run the clean and report thread.

Specified by:
run in interface Runnable

processQueue

protected void processQueue()
Attempt to process all the queued digest requests. Ones that cannot be processed now will be returned to the queue.


sendDigests

protected void sendDigests()
If it's time, send out any digested messages. Send once daily, after a certiain time of day (local time).


send

protected void send(String id,
                    List msgs,
                    TimeRange period)
Send a single digest message

Parameters:
id - The use id to send the message to.
msgs - The List (DigestMessage) of message to digest.
period - The time period of the digested messages.

newStorage

protected abstract BaseDigestService.Storage newStorage()
Construct storage for this service.


getAccessPoint

protected String getAccessPoint(boolean relative)
Access the partial URL that forms the root of resource URLs.

Parameters:
relative - if true, form within the access path only (i.e. starting with /content)
Returns:
the partial URL that forms the root of resource URLs.

digestReference

public String digestReference(String id)
Access the internal reference which can be used to access the resource from within the system.

Parameters:
id - The digest id string.
Returns:
The the internal reference which can be used to access the resource from within the system.

digestId

protected String digestId(String ref)
Access the digest id extracted from a digest reference.

Parameters:
ref - The digest reference string.
Returns:
The the digest id extracted from a digest reference.

unlockCheck

protected boolean unlockCheck(String lock,
                              String resource)
Check security permission.

Parameters:
lock - The lock id string.
resource - The resource reference string, or null if no resource is involved.
Returns:
true if allowd, false if not

unlock

protected void unlock(String lock,
                      String resource)
               throws PermissionException
Check security permission.

Parameters:
lock - The lock id string.
resource - The resource reference string, or null if no resource is involved.
Throws:
PermissionException - Thrown if the user does not have access

setLogger

public void setLogger(Logger service)
Dependency: logging service.

Parameters:
service - The logging service.

setMemoryService

public void setMemoryService(MemoryService service)
Dependency: MemoryService.

Parameters:
service - The MemoryService.

setTimeService

public void setTimeService(TimeService service)
Dependency: TimeService.

Parameters:
service - The TimeService.

init

public void init()
Final initialization, once all dependencies are set.


destroy

public void destroy()
Returns to uninitialized state.


getDigest

public Digest getDigest(String id)
                 throws IdUnusedException
Access digest associated with this id.

Specified by:
getDigest in interface DigestService
Parameters:
id - The digest id.
Returns:
The Digest object.
Throws:
IdUnusedException - if there is not digest object with this id.

getDigests

public List getDigests()
Access all digest objects.

Specified by:
getDigests in interface DigestService
Returns:
A List (Digest) of all defined digests.

digest

public void digest(DigestMessage message)
Add a new message to a digest, creating one if needed. This returns right away; the digest will be added as soon as possible.

Specified by:
digest in interface DigestService
Parameters:
message - The message to digest.

edit

public DigestEdit edit(String id)
                throws InUseException
Get a locked Digest object for editing. May be new. Must commit(), cancel() or remove() when done.

Specified by:
edit in interface DigestService
Parameters:
id - The digest id.
Returns:
A DigestEdit object for editing.
Throws:
InUseException - if the digest object is locked by someone else.

commit

public void commit(DigestEdit edit)
Commit the changes made to a DigestEdit object, and release the lock. The DigestEdit is disabled, and not to be used after this call.

Specified by:
commit in interface DigestService

cancel

public void cancel(DigestEdit edit)
Cancel the changes made to a DigestEdit object, and release the lock. The DigestEdit is disabled, and not to be used after this call.

Specified by:
cancel in interface DigestService

remove

public void remove(DigestEdit edit)
Remove this DigestEdit - it must be locked from edit(). The DigestEdit is disabled, and not to be used after this call.

Specified by:
remove in interface DigestService

findDigest

protected BaseDigestService.BaseDigest findDigest(String id)
Find the digest object, in cache or storage.

Parameters:
id - The digest id.
Returns:
The digest object found in cache or storage, or null if not found.

add

public DigestEdit add(String id)
               throws IdUsedException
Add a new set of digest with this id. Must commit(), remove() or cancel() when done.

Specified by:
add in interface DigestService
Parameters:
id - The digest id.
Returns:
A new DigestEdit object for editing.
Throws:
IdUsedException - if these digest already exist.

newContainer

public Entity newContainer(String ref)
Construct a new continer given just an id.

Specified by:
newContainer in interface StorageUser
Parameters:
ref - The container reference.
Returns:
The new containe Resource.

newContainer

public Entity newContainer(Element element)
Construct a new container resource, from an XML element.

Specified by:
newContainer in interface StorageUser
Parameters:
element - The XML.
Returns:
The new container resource.

newContainer

public Entity newContainer(Entity other)
Construct a new container resource, as a copy of another

Specified by:
newContainer in interface StorageUser
Parameters:
other - The other contianer to copy.
Returns:
The new container resource.

newResource

public Entity newResource(Entity container,
                          String id,
                          Object[] others)
Construct a new resource given just an id.

Specified by:
newResource in interface StorageUser
Parameters:
container - The Resource that is the container for the new resource (may be null).
id - The id for the new object.
others - (options) array of objects to load into the Resource's fields.
Returns:
The new resource.

newResource

public Entity newResource(Entity container,
                          Element element)
Construct a new resource, from an XML element.

Specified by:
newResource in interface StorageUser
Parameters:
container - The Resource that is the container for the new resource (may be null).
element - The XML.
Returns:
The new resource from the XML.

newResource

public Entity newResource(Entity container,
                          Entity other)
Construct a new resource from another resource of the same type.

Specified by:
newResource in interface StorageUser
Parameters:
container - The Resource that is the container for the new resource (may be null).
other - The other resource.
Returns:
The new resource as a copy of the other.

newContainerEdit

public Edit newContainerEdit(String ref)
Construct a new continer given just an id.

Specified by:
newContainerEdit in interface StorageUser
Parameters:
ref - The container reference.
Returns:
The new containe Resource.

newContainerEdit

public Edit newContainerEdit(Element element)
Construct a new container resource, from an XML element.

Specified by:
newContainerEdit in interface StorageUser
Parameters:
element - The XML.
Returns:
The new container resource.

newContainerEdit

public Edit newContainerEdit(Entity other)
Construct a new container resource, as a copy of another

Specified by:
newContainerEdit in interface StorageUser
Parameters:
other - The other contianer to copy.
Returns:
The new container resource.

newResourceEdit

public Edit newResourceEdit(Entity container,
                            String id,
                            Object[] others)
Construct a new resource given just an id.

Specified by:
newResourceEdit in interface StorageUser
Parameters:
container - The Resource that is the container for the new resource (may be null).
id - The id for the new object.
others - (options) array of objects to load into the Resource's fields.
Returns:
The new resource.

newResourceEdit

public Edit newResourceEdit(Entity container,
                            Element element)
Construct a new resource, from an XML element.

Specified by:
newResourceEdit in interface StorageUser
Parameters:
container - The Resource that is the container for the new resource (may be null).
element - The XML.
Returns:
The new resource from the XML.

newResourceEdit

public Edit newResourceEdit(Entity container,
                            Entity other)
Construct a new resource from another resource of the same type.

Specified by:
newResourceEdit in interface StorageUser
Parameters:
container - The Resource that is the container for the new resource (may be null).
other - The other resource.
Returns:
The new resource as a copy of the other.

storageFields

public Object[] storageFields(Entity r)
Collect the fields that need to be stored outside the XML (for the resource).

Specified by:
storageFields in interface StorageUser
Returns:
An array of field values to store in the record outside the XML (for the resource).

isDraft

public boolean isDraft(Entity r)
Check if this resource is in draft mode.

Specified by:
isDraft in interface StorageUser
Parameters:
r - The resource.
Returns:
true if the resource is in draft mode, false if not.

getOwnerId

public String getOwnerId(Entity r)
Access the resource owner user id.

Specified by:
getOwnerId in interface StorageUser
Parameters:
r - The resource.
Returns:
The resource owner user id.

getDate

public Time getDate(Entity r)
Access the resource date.

Specified by:
getDate in interface StorageUser
Parameters:
r - The resource.
Returns:
The resource date.

computeRange

protected TimeRange computeRange(Time time)
Compute a time range based on a specific time.

Returns:
The time range that encloses the specific time.