org.sakaiproject.component.legacy.message
Class BaseMessageService

java.lang.Object
  extended byorg.sakaiproject.component.legacy.message.BaseMessageService
All Implemented Interfaces:
CacheRefresher, EntityProducer, MessageService, StorageUser
Direct Known Subclasses:
BaseAnnouncementService, BaseChatService, BaseDiscussionService, BaseMailArchiveService

public abstract class BaseMessageService
extends Object
implements MessageService, StorageUser, CacheRefresher

BaseMessageService is a simple implementation of the CHEF MessageService as a Turbine service.

BaseMessageService simply stored messages in memory and has no persistence past the lifetime of the service object.

Services Used:

Note: for simplicity, we implement only the Edit versions of message and header - otherwise we'd want to inherit from two places in the extensions. A non-edit version is implemented by the edit version. -ggolden

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

Nested Class Summary
 class BaseMessageService.BaseMessageChannelEdit
          MessageChannel implementation
 class BaseMessageService.BaseMessageEdit
          MessageEdit implementation
 class BaseMessageService.BaseMessageHeaderEdit
          MessageHeaderEdit implementation
protected  class BaseMessageService.MessagePermissionFilter
          filter
protected  class BaseMessageService.MessageSelectionFilter
           
protected static interface BaseMessageService.Storage
          Storage implementation
 
Nested classes inherited from class org.sakaiproject.service.legacy.entity.EntityProducer
EntityProducer.ChangeType
 
Field Summary
protected  boolean m_caching
          Configuration: cache, or not.
protected  Cache m_channelCache
          A Cache object for caching: channels keyed by reference.
protected  EntityManager m_entityManager
          Dependency: EntityManager.
protected  Logger m_logger
          Dependency: logging service
protected  MemoryService m_memoryService
          Dependency: MemoryService.
protected  Hashtable m_messageCaches
          A bunch of caches for messages: keyed by channel id, the cache is keyed by message reference.
protected  ServerConfigurationService m_serverConfigurationService
          Dependency: ServerConfigurationService.
protected  BaseMessageService.Storage m_storage
          A Storage object for persistent storage.
 
Fields inherited from interface org.sakaiproject.service.legacy.message.MessageService
REF_TYPE_CHANNEL, REF_TYPE_CHANNEL_GROUPS, REF_TYPE_MESSAGE, SECURE_ADD, SECURE_ALL_GROUPS, SECURE_READ, SECURE_READ_DRAFT, SECURE_REMOVE_ANY, SECURE_REMOVE_OWN, SECURE_UPDATE_ANY, SECURE_UPDATE_OWN
 
Constructor Summary
BaseMessageService()
           
 
Method Summary
 MessageChannelEdit addChannel(String ref)
          Add a new channel.
 boolean allowAddChannel(String ref)
          check permissions for addChannel().
 boolean allowEditChannel(String ref)
          check permissions for editChannel()
 boolean allowGetChannel(String ref)
          check permissions for getChannel().
protected  boolean allowGetMessage(String channelRef, String msgRef)
          Check the message read permission for the message
 boolean allowRemoveChannel(String ref)
          Check permissions for removeChannel().
 String archive(String siteId, Document doc, Stack stack, String archivePath, List attachments)
          Archive the resources for the given site.
 void cancelChannel(MessageChannelEdit edit)
          Cancel the changes made to a MessageChannelEdit object, and release the lock.
 void cancelMessage(MessageEdit edit)
          Cancel the changes made to a MessageEdit object, and release the lock.
 String channelReference(String context, String id)
          Access the internal reference which can be used to access the channel from within the system.
 void commitChannel(MessageChannelEdit edit)
          Commit the changes made to a MessageChannelEdit object, and release the lock.
 void destroy()
          Destroy
protected  void disableMessageChannel(Site site)
          Remove the main message channel for a site.
 MessageChannelEdit editChannel(String ref)
          Return a specific channel, as specified by channel id, locked for update.
protected  void enableMessageChannel(Site site)
          Setup a main message channel for a site.
protected abstract  String eventId(String secure)
          Form a tracking event string based on a security function string.
protected  MessageChannel findChannel(String ref)
          Find the channel, in cache or info store - cache it if newly found.
protected  String getAccessPoint(boolean relative)
          Access the partial URL that forms the root of resource URLs.
 MessageChannel getChannel(String ref)
          Return a specific channel.
 List getChannelIds(String context)
          Access a list of channel ids that are defined related to the context.
 List getChannels()
          Return a list of all the defined channels.
 Entity getEntity(Reference ref)
          Access the referenced Entity - the entity will belong to the service.
 Collection getEntityAuthzGroups(Reference ref)
          Access a collection of authorization group ids for security on the for the referenced entity - the entity will belong to the service.
 String getEntityDescription(Reference ref)
          Create an entity description for the entity referenced - the entity will belong to the service.
 ResourceProperties getEntityResourceProperties(Reference ref)
          Access the resource properties for the referenced entity - the entity will belong to the service.
 String getEntityUrl(Reference ref)
          Access a URL for the referenced entity - the entity will belong to the service.
 HttpAccess getHttpAccess()
          Get the HttpAccess object that supports entity access via the access servlet for my entities.
 Message getMessage(Reference ref)
          Get a message, given a reference.
 List getMessages(String channelRef, Time afterDate, int limitedToLatest, boolean ascending, boolean includeDrafts, boolean pubViewOnly)
          Access a list of messages in the channel, that are after the date, limited to just the n latest messages, ordered as specified, including drafts if specified. Channel read permission is required, unless pubViewOnly is selected - draft read on the channel is required to see drafts.
protected abstract  String getReferenceRoot()
          Return the reference rooot for use in resource references and urls.
 void importEntities(String fromContext, String toContext, List resourceIds)
          import tool(s) contents from the source context into the destination context
 void init()
          Final initialization, once all dependencies are set.
 String merge(String siteId, Element root, String archivePath, String fromSiteId, Map attachmentNames, Map userIdTrans, Set userListAllowImport)
          Merge the resources from the archive into the given site.
 String messageReference(String channelRef, String id)
          Access the internal reference which can be used to access the message from within the system.
 String messageReference(String context, String channelId, String id)
          Access the internal reference which can be used to access the message from within the system.
protected abstract  MessageHeaderEdit newMessageHeader(Message msg, Element el)
          Construct a new message header from XML in a DOM element.
protected abstract  MessageHeaderEdit newMessageHeader(Message msg, MessageHeader other)
          Construct a new message header as a copy of another.
protected abstract  MessageHeaderEdit newMessageHeader(Message msg, String id)
          Construct a new message header from XML in a DOM element.
protected abstract  BaseMessageService.Storage newStorage()
          Construct a Storage object.
 Object refresh(Object key, Object oldValue, Event event)
          Get a new value for this key whose value has already expired in the cache.
 void removeChannel(MessageChannelEdit channel)
          Remove a channel.
protected  BaseMessageService service()
          Access this service from the inner classes.
protected abstract  String serviceName()
          Report the Service API name being implemented.
 void setCaching(String value)
          Configuration: set the locks-in-db
 void setEntityManager(EntityManager service)
          Dependency: EntityManager.
 void setLogger(Logger service)
          Dependency: logging service.
 void setMemoryService(MemoryService service)
          Dependency: MemoryService.
 void setServerConfigurationService(ServerConfigurationService service)
          Dependency: ServerConfigurationService.
 void syncWithSiteChange(Site site, EntityProducer.ChangeType change)
          Synchronize any entities related to the Site given this change in the Site, possibly a structural change where a tool is added or removed, or the site is new, or being deleted.
protected  void unlock(String lock, String resource)
          Check security permission.
protected  void unlock2(String lock1, String lock2, String resource)
          Check security permission.
protected  void unlock3(String lock1, String lock2, String lock3, String resource)
          Check security permission.
protected  boolean unlockCheck(String lock, String resource)
          Check security permission.
protected  boolean unlockCheck2(String lock1, String lock2, String resource)
          Check security permission, for either of two locks/
protected  boolean unlockCheck3(String lock1, String lock2, String lock3, String resource)
          Check security permission, for either of two locks/
 boolean willArchiveMerge()
          
 boolean willImport()
          
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface org.sakaiproject.service.legacy.entity.EntityProducer
getLabel, parseEntityReference
 
Methods inherited from interface org.sakaiproject.util.storage.StorageUser
getDate, getOwnerId, isDraft, newContainer, newContainer, newContainer, newContainerEdit, newContainerEdit, newContainerEdit, newResource, newResource, newResource, newResourceEdit, newResourceEdit, newResourceEdit, storageFields
 

Field Detail

m_storage

protected BaseMessageService.Storage m_storage
A Storage object for persistent storage.


m_channelCache

protected Cache m_channelCache
A Cache object for caching: channels keyed by reference. (if m_caching)


m_messageCaches

protected Hashtable m_messageCaches
A bunch of caches for messages: keyed by channel id, the cache is keyed by message reference. (if m_caching)


m_logger

protected Logger m_logger
Dependency: logging service


m_memoryService

protected MemoryService m_memoryService
Dependency: MemoryService.


m_serverConfigurationService

protected ServerConfigurationService m_serverConfigurationService
Dependency: ServerConfigurationService.


m_caching

protected boolean m_caching
Configuration: cache, or not.


m_entityManager

protected EntityManager m_entityManager
Dependency: EntityManager.

Constructor Detail

BaseMessageService

public BaseMessageService()
Method Detail

service

protected BaseMessageService service()
Access this service from the inner classes.


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.

setServerConfigurationService

public void setServerConfigurationService(ServerConfigurationService service)
Dependency: ServerConfigurationService.

Parameters:
service - The ServerConfigurationService.

setCaching

public void setCaching(String value)
Configuration: set the locks-in-db


setEntityManager

public void setEntityManager(EntityManager service)
Dependency: EntityManager.

Parameters:
service - The EntityManager.

init

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


destroy

public void destroy()
Destroy


serviceName

protected abstract String serviceName()
Report the Service API name being implemented.


newStorage

protected abstract BaseMessageService.Storage newStorage()
Construct a Storage object.

Returns:
The new storage object.

newMessageHeader

protected abstract MessageHeaderEdit newMessageHeader(Message msg,
                                                      String id)
Construct a new message header from XML in a DOM element.

Parameters:
msg - The message to own this header.
id - The message Id.
Returns:
The new message header.

newMessageHeader

protected abstract MessageHeaderEdit newMessageHeader(Message msg,
                                                      Element el)
Construct a new message header from XML in a DOM element.

Parameters:
msg - The message to own this header.
el - The XML DOM element that has the header information.
Returns:
The new message header.

newMessageHeader

protected abstract MessageHeaderEdit newMessageHeader(Message msg,
                                                      MessageHeader other)
Construct a new message header as a copy of another.

Parameters:
msg - The message to own this header.
other - The other header to copy.
Returns:
The new message header.

eventId

protected abstract String eventId(String secure)
Form a tracking event string based on a security function string.

Parameters:
secure - The security function string.
Returns:
The event tracking string.

getReferenceRoot

protected abstract String getReferenceRoot()
Return the reference rooot for use in resource references and urls.

Returns:
The reference rooot for use in resource references and urls.

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 /msg)
Returns:
the partial URL that forms the root of resource URLs.

channelReference

public String channelReference(String context,
                               String id)
Access the internal reference which can be used to access the channel from within the system.

Specified by:
channelReference in interface MessageService
Parameters:
context - The context.
id - The channel id.
Returns:
The the internal reference which can be used to access the channel from within the system.

messageReference

public String messageReference(String context,
                               String channelId,
                               String id)
Access the internal reference which can be used to access the message from within the system.

Specified by:
messageReference in interface MessageService
Parameters:
context - The context.
channelId - The channel id.
id - The message id.
Returns:
The the internal reference which can be used to access the message from within the system.

messageReference

public String messageReference(String channelRef,
                               String id)
Access the internal reference which can be used to access the message from within the system.

Specified by:
messageReference in interface MessageService
Parameters:
channelRef - The channel reference.
id - The message id.
Returns:
The the internal reference which can be used to access the message from within the system.

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

unlockCheck2

protected boolean unlockCheck2(String lock1,
                               String lock2,
                               String resource)
Check security permission, for either of two locks/

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

unlockCheck3

protected boolean unlockCheck3(String lock1,
                               String lock2,
                               String lock3,
                               String resource)
Check security permission, for either of two locks/

Parameters:
lock1 - The lock id string.
lock2 - The lock id string.
resource - The resource reference string, or null if no resource is involved.
Returns:
true if either allowed, 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

unlock2

protected void unlock2(String lock1,
                       String lock2,
                       String resource)
                throws PermissionException
Check security permission.

Parameters:
lock1 - The lock id string.
lock2 - 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 to either.

unlock3

protected void unlock3(String lock1,
                       String lock2,
                       String lock3,
                       String resource)
                throws PermissionException
Check security permission.

Parameters:
lock1 - The lock id string.
lock2 - The lock id string.
lock3 - 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 to either.

getChannels

public List getChannels()
Return a list of all the defined channels.

Specified by:
getChannels in interface MessageService
Returns:
a list of MessageChannel (or extension) objects (may be empty).

allowGetChannel

public boolean allowGetChannel(String ref)
check permissions for getChannel().

Specified by:
allowGetChannel in interface MessageService
Parameters:
ref - The channel reference.
Returns:
true if the user is allowed to getChannel(channelId), false if not.

getChannel

public MessageChannel getChannel(String ref)
                          throws IdUnusedException,
                                 PermissionException
Return a specific channel.

Specified by:
getChannel in interface MessageService
Parameters:
ref - The channel reference.
Returns:
the MessageChannel that has the specified name.
Throws:
IdUnusedException - If this name is not defined for any channel.
PermissionException - If the user does not have any permissions to the channel.

findChannel

protected MessageChannel findChannel(String ref)
Find the channel, in cache or info store - cache it if newly found.

Parameters:
ref - The channel reference.
Returns:
The channel, if found.

allowAddChannel

public boolean allowAddChannel(String ref)
check permissions for addChannel().

Specified by:
allowAddChannel in interface MessageService
Parameters:
ref - The channel reference.
Returns:
true if the user is allowed to addChannel(channelId), false if not.

addChannel

public MessageChannelEdit addChannel(String ref)
                              throws IdUsedException,
                                     IdInvalidException,
                                     PermissionException
Add a new channel. Must commitEdit() to make official, or cancelEdit() when done!

Specified by:
addChannel in interface MessageService
Parameters:
ref - The channel reference.
Returns:
The newly created channel, locked for update.
Throws:
IdUsedException - if the id is not unique.
IdInvalidException - if the id is not made up of valid characters.
PermissionException - if the user does not have permission to add a channel.

allowEditChannel

public boolean allowEditChannel(String ref)
check permissions for editChannel()

Specified by:
allowEditChannel in interface MessageService
Parameters:
ref - The channel reference.
Returns:
true if the user is allowed to update the channel, false if not.

editChannel

public MessageChannelEdit editChannel(String ref)
                               throws IdUnusedException,
                                      PermissionException,
                                      InUseException
Return a specific channel, as specified by channel id, locked for update. Must commitEdit() to make official, or cancelEdit() when done!

Specified by:
editChannel in interface MessageService
Parameters:
ref - The channel reference.
Returns:
the Channel that has the specified id.
Throws:
IdUnusedException - If this name is not a defined channel.
PermissionException - If the user does not have any permissions to edit the channel.
InUseException - if the channel is locked for edit by someone else.

commitChannel

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

Specified by:
commitChannel in interface MessageService

cancelChannel

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

Specified by:
cancelChannel in interface MessageService

allowRemoveChannel

public boolean allowRemoveChannel(String ref)
Check permissions for removeChannel().

Specified by:
allowRemoveChannel in interface MessageService
Parameters:
ref - The channel reference.
Returns:
true if the user is allowed to removeChannel(), false if not.

removeChannel

public void removeChannel(MessageChannelEdit channel)
                   throws PermissionException
Remove a channel. Remove a channel - it must be locked from editChannel().

Specified by:
removeChannel in interface MessageService
Parameters:
channel - The channel to remove.
Throws:
PermissionException - if the user does not have permission to remove a channel.

getMessage

public Message getMessage(Reference ref)
                   throws IdUnusedException,
                          PermissionException
Get a message, given a reference. This call avoids the need to have channel security, as long as the user has permissions to the message.

Specified by:
getMessage in interface MessageService
Parameters:
ref - The message reference
Returns:
The message.
Throws:
IdUnusedException - If this reference does not identify a message.
PermissionException - If the user does not have any permissions to the message.

allowGetMessage

protected boolean allowGetMessage(String channelRef,
                                  String msgRef)
Check the message read permission for the message

Returns:
True if the end user has permission to read the message, or permission to all messages in the channel, false if not.

cancelMessage

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

Specified by:
cancelMessage in interface MessageService

getMessages

public List getMessages(String channelRef,
                        Time afterDate,
                        int limitedToLatest,
                        boolean ascending,
                        boolean includeDrafts,
                        boolean pubViewOnly)
                 throws PermissionException
Access a list of messages in the channel, that are after the date, limited to just the n latest messages, ordered as specified, including drafts if specified. Channel read permission is required, unless pubViewOnly is selected - draft read on the channel is required to see drafts.

Specified by:
getMessages in interface MessageService
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.
ascending - if true, sort oldest first, else sort latest first.
includeDrafts - if true, include drafts (if the user has draft permission), else leave them out.
pubViewOnly - if true, include only messages marked pubview, else include any.
Returns:
A list of Message objects that meet the criteria; may be empty
Throws:
PermissionException - If the current user does not have channel read permission.

getChannelIds

public List getChannelIds(String context)
Access a list of channel ids that are defined related to the context.

Specified by:
getChannelIds in interface MessageService
Parameters:
context - The context in which to search
Returns:
A List (String) of channel id for channels withing the context.

willArchiveMerge

public boolean willArchiveMerge()

Specified by:
willArchiveMerge in interface EntityProducer
Returns:
true if the serice wants to be part of archive / merge, false if not.

willImport

public boolean willImport()

Specified by:
willImport in interface EntityProducer
Returns:
true if the serice wants to be part of import, false if not.

getHttpAccess

public HttpAccess getHttpAccess()
Get the HttpAccess object that supports entity access via the access servlet for my entities.

Specified by:
getHttpAccess in interface EntityProducer
Returns:
The HttpAccess object for my entities, or null if I do not support access.

getEntityDescription

public String getEntityDescription(Reference ref)
Create an entity description for the entity referenced - the entity will belong to the service.

Specified by:
getEntityDescription in interface EntityProducer
Parameters:
ref - The entity reference.
Returns:
The entity description, or null if one cannot be made.

getEntityResourceProperties

public ResourceProperties getEntityResourceProperties(Reference ref)
Access the resource properties for the referenced entity - the entity will belong to the service.

Specified by:
getEntityResourceProperties in interface EntityProducer
Parameters:
ref - The entity reference.
Returns:
The ResourceProperties object for the entity, or null if it has none.

getEntity

public Entity getEntity(Reference ref)
Access the referenced Entity - the entity will belong to the service.

Specified by:
getEntity in interface EntityProducer
Parameters:
ref - The entity reference.
Returns:
The Entity, or null if not found.

getEntityAuthzGroups

public Collection getEntityAuthzGroups(Reference ref)
Access a collection of authorization group ids for security on the for the referenced entity - the entity will belong to the service.

Specified by:
getEntityAuthzGroups in interface EntityProducer
Parameters:
ref - The entity reference.
Returns:
The entity's collection of authorization group ids, or null if this cannot be done.

getEntityUrl

public String getEntityUrl(Reference ref)
Access a URL for the referenced entity - the entity will belong to the service.

Specified by:
getEntityUrl in interface EntityProducer
Parameters:
ref - The entity reference.
Returns:
The entity's URL, or null if it does not have one.

archive

public String archive(String siteId,
                      Document doc,
                      Stack stack,
                      String archivePath,
                      List attachments)
Archive the resources for the given site.

Specified by:
archive in interface EntityProducer
Parameters:
siteId - the id of the site.
doc - The document to contain the xml.
stack - The stack of elements, the top of which will be the containing element of the "service.name" element.
archivePath - The path to the folder where we are writing auxilary files.
attachments - A list of attachments - add to this if any attachments need to be included in the archive.
Returns:
A log of status messages from the archive.

merge

public String merge(String siteId,
                    Element root,
                    String archivePath,
                    String fromSiteId,
                    Map attachmentNames,
                    Map userIdTrans,
                    Set userListAllowImport)
Merge the resources from the archive into the given site.

Specified by:
merge in interface EntityProducer
Parameters:
siteId - The id of the site getting imported into.
root - The XML DOM tree of content to merge.
attachmentNames - A map of old attachment name (as found in the DOM) to new attachment name.
Returns:
A log of status messages from the merge.

importEntities

public void importEntities(String fromContext,
                           String toContext,
                           List resourceIds)
import tool(s) contents from the source context into the destination context

Specified by:
importEntities in interface EntityProducer
Parameters:
fromContext - The source context
toContext - The destination context
resourceIds - when null, all resources will be imported; otherwise, only resources with those ids will be imported

syncWithSiteChange

public void syncWithSiteChange(Site site,
                               EntityProducer.ChangeType change)
Synchronize any entities related to the Site given this change in the Site, possibly a structural change where a tool is added or removed, or the site is new, or being deleted.

Specified by:
syncWithSiteChange in interface EntityProducer
Parameters:
site - The site that has just changed.
change - The ChangeType for the site (newly added, updated, or just removed).

enableMessageChannel

protected void enableMessageChannel(Site site)
Setup a main message channel for a site.

Parameters:
site - The site.

disableMessageChannel

protected void disableMessageChannel(Site site)
Remove the main message channel for a site.

Parameters:
site - The site.

refresh

public Object refresh(Object key,
                      Object oldValue,
                      Event event)
Get a new value for this key whose value has already expired in the cache.

Specified by:
refresh in interface CacheRefresher
Parameters:
key - The key whose value has expired and needs to be refreshed.
oldValue - The old exipred value of the key.
event - The event which triggered this refresh.
Returns:
a new value for use in the cache for this key; if null, the entry will be removed.