001: /**********************************************************************************
002: * $URL: https://source.sakaiproject.org/svn/message/tags/sakai_2-4-1/message-api/api/src/java/org/sakaiproject/message/api/MessageService.java $
003: * $Id: MessageService.java 21003 2007-02-05 02:39:11Z csev@umich.edu $
004: ***********************************************************************************
005: *
006: * Copyright (c) 2003, 2004, 2005, 2006 The Sakai Foundation.
007: *
008: * Licensed under the Educational Community License, Version 1.0 (the "License");
009: * you may not use this file except in compliance with the License.
010: * You may obtain a copy of the License at
011: *
012: * http://www.opensource.org/licenses/ecl1.php
013: *
014: * Unless required by applicable law or agreed to in writing, software
015: * distributed under the License is distributed on an "AS IS" BASIS,
016: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
017: * See the License for the specific language governing permissions and
018: * limitations under the License.
019: *
020: **********************************************************************************/package org.sakaiproject.message.api;
021:
022: import java.util.List;
023: import java.util.Map;
024:
025: import org.sakaiproject.entity.api.EntityProducer;
026: import org.sakaiproject.entity.api.Reference;
027: import org.sakaiproject.exception.IdInvalidException;
028: import org.sakaiproject.exception.IdUnusedException;
029: import org.sakaiproject.exception.IdUsedException;
030: import org.sakaiproject.exception.InUseException;
031: import org.sakaiproject.exception.PermissionException;
032: import org.sakaiproject.time.api.Time;
033:
034: /**
035: * <p>
036: * GenericMessageService is the base interface for the different specific Sakai communications service such as Chat, Announcements, etc.
037: * </p>
038: * <p>
039: * The service manages a set of message channels, each containing a set of messages.
040: * </p>
041: * <p>
042: * Channels and Messages can be worked with through the MessageChannel and Message APIs and their extensions.
043: * </p>
044: */
045: public interface MessageService extends EntityProducer {
046: /** Security function / event for reading channel / message. */
047: public static final String SECURE_READ = "read";
048:
049: /** Security function / event for adding channel / message. */
050: public static final String SECURE_ADD = "new";
051:
052: /** Security function / event for removing one's own message. */
053: public static final String SECURE_REMOVE_OWN = "delete.own";
054:
055: /** Security function / event for removing anyone's message or channel. */
056: public static final String SECURE_REMOVE_ANY = "delete.any";
057:
058: /** Security function / event for updating one's own message or the channel. */
059: public static final String SECURE_UPDATE_OWN = "revise.own";
060:
061: /** Security function / event for updating any message. */
062: public static final String SECURE_UPDATE_ANY = "revise.any";
063:
064: /** Security function / event for accessing someone elses draft. */
065: public static final String SECURE_READ_DRAFT = "read.drafts";
066:
067: /** Security function giving the user permission to all groups, if granted to at the channel or site level. */
068: public static final String SECURE_ALL_GROUPS = "all.groups";
069:
070: /** The Reference type for a channel. */
071: public static final String REF_TYPE_CHANNEL = "channel";
072:
073: /** The Reference type for a messgae. */
074: public static final String REF_TYPE_MESSAGE = "msg";
075:
076: /**
077: * Return a list of all the defined channels.
078: *
079: * @return a list of MessageChannel (or extension) objects (may be empty).
080: */
081: public List getChannels();
082:
083: /**
084: * check permissions for getChannel().
085: *
086: * @param ref
087: * The channel reference.
088: * @return true if the user is allowed to getChannel(channelId), false if not.
089: */
090: public boolean allowGetChannel(String ref);
091:
092: /**
093: * Return a specific channel.
094: *
095: * @param ref
096: * The channel reference.
097: * @return the MessageChannel that has the specified name.
098: * @exception IdUnusedException
099: * If this name is not defined for any channel.
100: * @exception PermissionException
101: * If the user does not have any permissions to the channel.
102: */
103: public MessageChannel getChannel(String ref)
104: throws IdUnusedException, PermissionException;
105:
106: /**
107: * check permissions for addChannel().
108: *
109: * @param ref
110: * The channel reference.
111: * @return true if the user is allowed to addChannel(channelId), false if not.
112: */
113: public boolean allowAddChannel(String ref);
114:
115: /**
116: * Add a new channel. Must commitEdit() to make official, or cancelEdit() when done!
117: *
118: * @param ref
119: * The channel reference.
120: * @return The newly created channel, locked for update.
121: * @exception IdUsedException
122: * if the id is not unique.
123: * @exception IdInvalidException
124: * if the id is not made up of valid characters.
125: * @exception PermissionException
126: * if the user does not have permission to add a channel.
127: */
128: public MessageChannelEdit addChannel(String ref)
129: throws IdUsedException, IdInvalidException,
130: PermissionException;
131:
132: /**
133: * check permissions for editChannel()
134: *
135: * @param ref
136: * The channel reference.
137: * @return true if the user is allowed to update the channel, false if not.
138: */
139: public boolean allowEditChannel(String ref);
140:
141: /**
142: * Return a specific channel, as specified by channel id, locked for update. Must commitEdit() to make official, or cancelEdit() when done!
143: *
144: * @param ref
145: * The channel reference.
146: * @return the Channel that has the specified id.
147: * @exception IdUnusedException
148: * If this name is not a defined channel.
149: * @exception PermissionException
150: * If the user does not have any permissions to edit the channel.
151: * @exception InUseException
152: * if the channel is locked for edit by someone else.
153: */
154: public MessageChannelEdit editChannel(String ref)
155: throws IdUnusedException, PermissionException,
156: InUseException;
157:
158: /**
159: * Commit the changes made to a MessageChannelEdit object, and release the lock. The MessageChannelEdit is disabled, and not to be used after this call.
160: *
161: * @param user
162: * The MessageChannelEdit object to commit.
163: */
164: public void commitChannel(MessageChannelEdit edit);
165:
166: /**
167: * Cancel the changes made to a MessageChannelEdit object, and release the lock. The MessageChannelEdit is disabled, and not to be used after this call.
168: *
169: * @param user
170: * The MessageChannelEdit object to cancel.
171: */
172: public void cancelChannel(MessageChannelEdit edit);
173:
174: /**
175: * Check permissions for removeChannel().
176: *
177: * @param ref
178: * The channel reference.
179: * @return true if the user is allowed to removeChannel(), false if not.
180: */
181: public boolean allowRemoveChannel(String ref);
182:
183: /**
184: * Remove a channel - it must be locked from editChannel().
185: *
186: * @param channel
187: * The channel to remove.
188: * @exception PermissionException
189: * if the user does not have permission to remove a channel.
190: */
191: public void removeChannel(MessageChannelEdit channel)
192: throws PermissionException;
193:
194: /**
195: * Access the internal reference which can be used to access the channel from within the system.
196: *
197: * @param context
198: * The context.
199: * @param id
200: * The channel id.
201: * @return The the internal reference which can be used to access the channel from within the system.
202: */
203: public String channelReference(String context, String id);
204:
205: /**
206: * Access the internal reference which can be used to access the message from within the system.
207: *
208: * @param context
209: * The context.
210: * @param channelId
211: * The channel id.
212: * @param id
213: * The message id.
214: * @return The the internal reference which can be used to access the message from within the system.
215: */
216: public String messageReference(String context, String channelId,
217: String id);
218:
219: /**
220: * Access the internal reference which can be used to access the message from within the system.
221: *
222: * @param channelRef
223: * The channel reference.
224: * @param id
225: * The message id.
226: * @return The the internal reference which can be used to access the message from within the system.
227: */
228: public String messageReference(String channelRef, String id);
229:
230: /**
231: * 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.
232: *
233: * @param ref
234: * The message reference
235: * @return The message.
236: * @exception IdUnusedException
237: * If this reference does not identify a message.
238: * @exception PermissionException
239: * If the user does not have any permissions to the message.
240: */
241: public Message getMessage(Reference ref) throws IdUnusedException,
242: PermissionException;
243:
244: /**
245: * Cancel the changes made to a MessageEdit object, and release the lock. The MessageEdit is disabled, and not to be used after this call.
246: *
247: * @param user
248: * The MessageEdit object to cancel.
249: */
250: public void cancelMessage(MessageEdit edit);
251:
252: /**
253: * 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
254: * channel is required to see drafts.
255: *
256: * @param afterDate
257: * if null, no date limit, else limited to only messages after this date.
258: * @param limitedToLatest
259: * if 0, no count limit, else limited to only the latest this number of messages.
260: * @param ascending
261: * if true, sort oldest first, else sort latest first.
262: * @param includeDrafts
263: * if true, include drafts (if the user has draft permission), else leave them out.
264: * @param pubViewOnly
265: * if true, include only messages marked pubview, else include any.
266: * @return A list of Message objects that meet the criteria; may be empty
267: * @exception PermissionException
268: * If the current user does not have channel read permission.
269: */
270: public List getMessages(String channelRef, Time afterDate,
271: int limitedToLatest, boolean ascending,
272: boolean includeDrafts, boolean pubViewOnly)
273: throws PermissionException;
274:
275: /**
276: * Access a list of channel ids that are defined related to the context.
277: *
278: * @param context
279: * The context in which to search
280: * @return A List (String) of channel id for channels withing the context.
281: */
282: public List getChannelIds(String context);
283:
284: /**
285: * Get a summary of an Announcement Channel
286: *
287: * @param ref
288: * The channel reference.
289: * @param items
290: * Maximum number of items to return
291: * @param days
292: * Maximum number of dayes to peer back
293: * @return The Map containnt the Summary
294: * @exception IdUsedException
295: * if the id is not unique.
296: * @exception IdInvalidException
297: * if the id is not made up of valid characters.
298: * @exception PermissionException
299: * if the user does not have permission to add a channel.
300: */
301: public Map getSummary(String ref, int items, int days)
302: throws IdUsedException, IdInvalidException,
303: PermissionException;
304:
305: } // MessageService
|