org.sakaiproject.announcement.cover

Class AnnouncementService

java.lang.Object

org.sakaiproject.announcement.cover.AnnouncementService

public class AnnouncementService
extends Object

AnnouncementService is a static Cover for the AnnouncementService; see that interface for usage details.

Version:

$Revision$

Author:

University of Michigan, Sakai Software Development Team

Field Summary

Fields

Modifier and Type	Field and Description
static String	APPLICATION_ID
static String	ASSIGNMENT_REFERENCE
static String	EVENT_ANNC_UPDATE_ACCESS
static String	EVENT_ANNC_UPDATE_AVAILABILITY
static String	EVENT_ANNC_UPDATE_TITLE Events
static String	MOD_DATE
static String	REF_TYPE_CHANNEL
static String	REF_TYPE_MESSAGE
static String	REFERENCE_ROOT
static String	RELEASE_DATE
static String	RETRACT_DATE
static String	SECURE_ADD
static String	SECURE_ANNC_ADD
static String	SECURE_ANNC_READ
static String	SECURE_ANNC_READ_DRAFT
static String	SECURE_ANNC_REMOVE_ANY
static String	SECURE_ANNC_REMOVE_OWN
static String	SECURE_ANNC_ROOT
static String	SECURE_ANNC_UPDATE_ANY
static String	SECURE_ANNC_UPDATE_OWN
static String	SECURE_READ
static String	SECURE_READ_DRAFT
static String	SECURE_REMOVE_ANY
static String	SECURE_REMOVE_OWN
static String	SECURE_UPDATE_ANY
static String	SECURE_UPDATE_OWN

Constructor Summary

Constructors

Constructor and Description
AnnouncementService()

Method Summary

Modifier and Type	Method and Description
static AnnouncementChannelEdit	addAnnouncementChannel(String param0) A (AnnouncementChannel) cover for addChannel() to add a new announcement channel.
static MessageChannelEdit	addChannel(String param0) Add a new channel.
static boolean	allowAddChannel(String param0) check permissions for addChannel().
static boolean	allowEditChannel(String param0) check permissions for editChannel()
static boolean	allowGetChannel(String param0) check permissions for getChannel().
static boolean	allowRemoveChannel(String param0) Check permissions for removeChannel().
static String	archive(String param0, Document param1, Stack param2, String param3, List param4)
static void	cancelChannel(MessageChannelEdit param0) Cancel the changes made to a MessageChannelEdit object, and release the lock.
static void	cancelMessage(MessageEdit param0) Cancel the changes made to a MessageEdit object, and release the lock.
static String	channelReference(String param0, String param1) Access the internal reference which can be used to access the channel from within the system.
static void	clearMessagesCache(String channelRef) clears the message cache for this channel
static void	commitChannel(MessageChannelEdit param0) Commit the changes made to a MessageChannelEdit object, and release the lock.
static MessageChannelEdit	editChannel(String param0) Return a specific channel, as specified by channel id, locked for update.
static AnnouncementChannel	getAnnouncementChannel(String param0) A (AnnouncementChannel) cover for getChannel() to return a specific announcement channel.
static Reference	getAnnouncementReference(String param0) Get announcement entity reference for given context
static MessageChannel	getChannel(String param0) Return a specific channel.
static List	getChannelIds(String param0) Access a list of channel ids that are defined related to the context.
static List	getChannels() Return a list of all the defined channels.
static AnnouncementService	getInstance() Access the component instance: special cover only method.
static String	getLabel()
static Message	getMessage(Reference param0) Get a message, given a reference.
static List	getMessages(String channelReference, Filter filter, boolean order, boolean merged) Return a list of messages from the provided channel (merged flag returns merged messages)
static List	getMessages(String param0, Time param1, int param2, boolean param3, boolean param4, boolean param5) 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.
static String	getRssUrl(Reference param0) Get URL to access the announcement rss feed
static Map	getSummary(String param0, int param1, int param2) Get a summary of an Announcement Channel
static boolean	isMessageViewable(AnnouncementMessage param0) Determine if message viewable based on release/retract dates (if set)
static String	merge(String param0, Element param1, String param2, String param3, Map param4, HashMap param5, Set param6)
static String	messageReference(String param0, String param1) Access the internal reference which can be used to access the message from within the system.
static String	messageReference(String param0, String param1, String param2) Access the internal reference which can be used to access the message from within the system.
static void	removeChannel(MessageChannelEdit param0) Remove a channel - it must be locked from editChannel().

Methods inherited from class java.lang.Object

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

Field Detail

MOD_DATE

public static final String MOD_DATE

See Also:

Constant Field Values

RELEASE_DATE

public static final String RELEASE_DATE

See Also:

Constant Field Values

RETRACT_DATE

public static final String RETRACT_DATE

See Also:

Constant Field Values

ASSIGNMENT_REFERENCE

public static final String ASSIGNMENT_REFERENCE

See Also:

Constant Field Values

EVENT_ANNC_UPDATE_TITLE

public static final String EVENT_ANNC_UPDATE_TITLE

Events

See Also:

Constant Field Values

EVENT_ANNC_UPDATE_ACCESS

public static final String EVENT_ANNC_UPDATE_ACCESS

See Also:

Constant Field Values

EVENT_ANNC_UPDATE_AVAILABILITY

public static final String EVENT_ANNC_UPDATE_AVAILABILITY

See Also:

Constant Field Values

APPLICATION_ID

public static String APPLICATION_ID

REFERENCE_ROOT

public static String REFERENCE_ROOT

SECURE_ANNC_ROOT

public static String SECURE_ANNC_ROOT

SECURE_ANNC_READ

public static String SECURE_ANNC_READ

SECURE_ANNC_ADD

public static String SECURE_ANNC_ADD

SECURE_ANNC_REMOVE_OWN

public static String SECURE_ANNC_REMOVE_OWN

SECURE_ANNC_REMOVE_ANY

public static String SECURE_ANNC_REMOVE_ANY

SECURE_ANNC_UPDATE_OWN

public static String SECURE_ANNC_UPDATE_OWN

SECURE_ANNC_UPDATE_ANY

public static String SECURE_ANNC_UPDATE_ANY

SECURE_ANNC_READ_DRAFT

public static String SECURE_ANNC_READ_DRAFT

SECURE_READ

public static String SECURE_READ

SECURE_ADD

public static String SECURE_ADD

SECURE_REMOVE_OWN

public static String SECURE_REMOVE_OWN

SECURE_REMOVE_ANY

public static String SECURE_REMOVE_ANY

SECURE_UPDATE_OWN

public static String SECURE_UPDATE_OWN

SECURE_UPDATE_ANY

public static String SECURE_UPDATE_ANY

SECURE_READ_DRAFT

public static String SECURE_READ_DRAFT

REF_TYPE_CHANNEL

public static String REF_TYPE_CHANNEL

REF_TYPE_MESSAGE

public static String REF_TYPE_MESSAGE

Constructor Detail

AnnouncementService

public AnnouncementService()

Method Detail

getInstance

public static AnnouncementService getInstance()

Access the component instance: special cover only method.

Returns:

the component instance.

getAnnouncementChannel

public static AnnouncementChannel getAnnouncementChannel(String param0)
                                                  throws IdUnusedException,
                                                         PermissionException

A (AnnouncementChannel) cover for getChannel() to return a specific announcement channel.

Parameters:

param0 - The channel reference string.

Returns:

the AnnouncementChannel that has the specified name.

Throws:

IdUnusedException - If this name is not defined for a announcement channel.

PermissionException - If the user does not have any permissions to the channel.

addAnnouncementChannel

public static AnnouncementChannelEdit addAnnouncementChannel(String param0)
                                                      throws IdUsedException,
                                                             IdInvalidException,
                                                             PermissionException

A (AnnouncementChannel) cover for addChannel() to add a new announcement channel.

Parameters:

param0 - The channel reference string.

Returns:

The newly created channel.

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.

getChannels

public static List getChannels()

Return a list of all the defined channels.

Returns:

a list of MessageChannel (or extension) objects (may be empty).

allowGetChannel

public static boolean allowGetChannel(String param0)

check permissions for getChannel().

Parameters:

param0 - The channel reference string.

Returns:

true if the user is allowed to getChannel(channelId), false if not.

allowAddChannel

public static boolean allowAddChannel(String param0)

check permissions for addChannel().

Parameters:

param0 - The channel reference string.

Returns:

true if the user is allowed to addChannel(channelId), false if not.

addChannel

public static MessageChannelEdit addChannel(String param0)
                                     throws IdUsedException,
                                            IdInvalidException,
                                            PermissionException

Add a new channel. Must commitEdit() to make official, or cancelEdit() when done!

Parameters:

The - channel reference string.

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 static boolean allowEditChannel(String param0)

check permissions for editChannel()

Parameters:

param0 - The channel reference string.

Returns:

true if the user is allowed to update the channel, false if not.

editChannel

public static MessageChannelEdit editChannel(String param0)
                                      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!

Parameters:

param0 - The channel reference string.

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 static void commitChannel(MessageChannelEdit param0)

Commit the changes made to a MessageChannelEdit object, and release the lock. The MessageChannelEdit is disabled, and not to be used after this call.

Parameters:

param0 - The MessageChannelEdit object to commit.

cancelChannel

public static void cancelChannel(MessageChannelEdit param0)

Cancel the changes made to a MessageChannelEdit object, and release the lock. The MessageChannelEdit is disabled, and not to be used after this call.

Parameters:

param0 - The MessageChannelEdit object to cancel.

allowRemoveChannel

public static boolean allowRemoveChannel(String param0)

Check permissions for removeChannel().

Parameters:

param0 - The channel reference string.

Returns:

true if the user is allowed to removeChannel(), false if not.

removeChannel

public static void removeChannel(MessageChannelEdit param0)
                          throws PermissionException

Remove a channel - it must be locked from editChannel().

Parameters:

param0 - The MessageChannelEdit object of the channel to remove.

Throws:

PermissionException - if the user does not have permission to remove a channel.

channelReference

public static String channelReference(String param0,
                                      String param1)

Access the internal reference which can be used to access the channel from within the system.

Parameters:

param0 - The context string.

param1 - The channel id.

Returns:

The the internal reference which can be used to access the channel from within the system.

messageReference

public static String messageReference(String param0,
                                      String param1,
                                      String param2)

Access the internal reference which can be used to access the message from within the system.

Parameters:

param0 - The context string.

param1 - The channel id.

param2 - The message id.

Returns:

The the internal reference which can be used to access the message from within the system.

messageReference

public static String messageReference(String param0,
                                      String param1)

Access the internal reference which can be used to access the message from within the system.

Parameters:

param0 - The channel reference string

param1 - The message id.

Returns:

The the internal reference which can be used to access the message from within the system.

cancelMessage

public static void cancelMessage(MessageEdit param0)

Cancel the changes made to a MessageEdit object, and release the lock. The MessageEdit is disabled, and not to be used after this call.

Parameters:

param0 - The MessageEdit object to cancel.

getMessages

public static List getMessages(String param0,
                               Time param1,
                               int param2,
                               boolean param3,
                               boolean param4,
                               boolean param5)
                        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.

Parameters:

param0 - channel reference string

param1 - if null, no date limit, else limited to only messages after this date.

param2 - if 0, no count limit, else limited to only the latest this number of messages.

param3 - if true, sort oldest first, else sort latest first.

param4 - if true, include drafts (if the user has draft permission), else leave them out.

param5 - 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 static List getChannelIds(String param0)

Access a list of channel ids that are defined related to the context.

Parameters:

param0 - The context in which to search

Returns:

A List (String) of channel id for channels withing the context.

getMessage

public static Message getMessage(Reference param0)
                          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.

Parameters:

param0 - 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.

getChannel

public static MessageChannel getChannel(String param0)
                                 throws IdUnusedException,
                                        PermissionException

Return a specific channel.

Parameters:

param0 - 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.

merge

public static String merge(String param0,
                           Element param1,
                           String param2,
                           String param3,
                           Map param4,
                           HashMap param5,
                           Set param6)

getLabel

public static String getLabel()

archive

public static String archive(String param0,
                             Document param1,
                             Stack param2,
                             String param3,
                             List param4)

getSummary

public static Map getSummary(String param0,
                             int param1,
                             int param2)
                      throws IdUsedException,
                             IdInvalidException,
                             PermissionException

Get a summary of an Announcement Channel

Parameters:

param0 - channel reference string.

param1 - Maximum number of items to return

param2 - Maximum number of days to peer back

Returns:

The Map containing the Summary

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.

getAnnouncementReference

public static Reference getAnnouncementReference(String param0)

Get announcement entity reference for given context

Parameters:

param0 - announcement context (site-id)

Returns:

announcement entity reference

getRssUrl

public static String getRssUrl(Reference param0)

Get URL to access the announcement rss feed

Parameters:

param0 - The announcement entity reference

Returns:

URL for announcement rss feed

isMessageViewable

public static boolean isMessageViewable(AnnouncementMessage param0)

Determine if message viewable based on release/retract dates (if set)

Parameters:

param0 - AnnouncementMessage

Returns:

boolean

clearMessagesCache

public static void clearMessagesCache(String channelRef)

clears the message cache for this channel

Parameters:

channelRef -

getMessages

public static List getMessages(String channelReference,
                               Filter filter,
                               boolean order,
                               boolean merged)
                        throws IdUnusedException,
                               PermissionException,
                               NullPointerException

Return a list of messages from the provided channel (merged flag returns merged messages)

Parameters:

channelReference - Channel's reference String

filter - A filtering object to accept messages, or null if no filtering is desired.

order - Order of messages, ascending if true, descending if false

merged - flag to include merged channel messages, true returns ALL messages including merged sites/channels

Returns:

a list of Message objects or specializations of Message objects (may be empty).

Throws:

IdUnusedException - If this name is not defined for a announcement channel.

PermissionException - if the user does not have read permission to the channel.

NullPointerException