001: /**********************************************************************************
002: * $URL: https://source.sakaiproject.org/svn/message/tags/sakai_2-4-1/message-api/api/src/java/org/sakaiproject/message/api/MessageChannel.java $
003: * $Id: MessageChannel.java 22952 2007-03-19 17:51:51Z josrodri@iupui.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
023: import java.util.Collection;
024: import java.util.List;
025:
026: import org.sakaiproject.entity.api.Entity;
027: import org.sakaiproject.exception.IdUnusedException;
028: import org.sakaiproject.exception.IdUsedException;
029: import org.sakaiproject.exception.InUseException;
030: import org.sakaiproject.exception.PermissionException;
031: import org.sakaiproject.javax.Filter;
032: import org.w3c.dom.Element;
033:
034: /**
035: * <p>
036: * MessageChannel is the base interface for Sakai communications service message channels. Extensions to this interface configure types of communications channels (Chat, Announcements, etc.)
037: * </p>
038: * <p>
039: * Channels contains collections of messages, each Message (or extension) object. Each chat channel has a unique channel id (read only), and is a Sakai Resource.
040: * </p>
041: * <p>
042: * The chat channel can be asked:
043: * <ul>
044: * <li>for an iterator on the messages, with a filter</li>
045: * <li>to find a specific message</li>
046: * <li>to add a new message</li>
047: * <li>to update an existing message</li>
048: * <li>to remove an existing message</li>
049: * </ul>
050: * </p>
051: * <p>
052: * The chat channel can be subscribed to providing notification when:
053: * <ul>
054: * <li>a new message has been posted</li>
055: * <li>a message has been changed</li>
056: * <li>a message has been removed</li>
057: * <li>the channel has been removed</li>
058: * </ul>
059: * </p>
060: * <p>
061: * Security on the channel include:
062: * <ul>
063: * <li>message.channel.read</li>
064: * <li>message.channel.remove.any</li>
065: * <li>message.channel.remove.own</li>
066: * <li>message.channel.post</li>
067: * </ul>
068: * Security Roles for the channel include:
069: * <ul>
070: * <li>message.member: read, remove.own, post</li>
071: * <li>message.administrator: chat.member, remove.any</li>
072: * </ul>
073: * </p>
074: * <p>
075: * Event handling is defined in the specific extension classes.
076: * </p>
077: *
078: * @author Sakai Software Development Team
079: */
080: public interface MessageChannel extends Entity {
081: /**
082: * Access the context of the resource.
083: *
084: * @return The context.
085: */
086: String getContext();
087:
088: /**
089: * check permissions for getMessages() or getMessage().
090: *
091: * @return true if the user is allowed to get messages from this channel, false if not.
092: */
093: boolean allowGetMessages();
094:
095: /**
096: * Return a list of all or filtered messages in the channel. The order in which the messages will be found in the iteration is by date, oldest first if ascending is true, newest first if ascending is false.
097: *
098: * @param filter
099: * A filtering object to accept messages, or null if no filtering is desired.
100: * @param ascending
101: * Order of messages, ascending if true, descending if false
102: * @return a list of channel Message objects or specializations of Message objects (may be empty).
103: * @exception PermissionException
104: * if the user does not have read permission to the channel.
105: */
106: List getMessages(Filter filter, boolean ascending)
107: throws PermissionException;
108:
109: /**
110: * Return a specific channel message, as specified by message name.
111: *
112: * @param messageId
113: * The id of the message to get.
114: * @return the Message that has the specified id.
115: * @exception IdUnusedException
116: * If this name is not a defined message in this channel.
117: * @exception PermissionException
118: * If the user does not have any permissions to read the message.
119: */
120: Message getMessage(String messageId) throws IdUnusedException,
121: PermissionException;
122:
123: /**
124: * check permissions for editMessage()
125: *
126: * @param id
127: * The message id.
128: * @return true if the user is allowed to update the message, false if not.
129: */
130: boolean allowEditMessage(String messageId);
131:
132: /**
133: * Return a specific channel message, as specified by message name, locked for update. Must commitEdit() to make official, or cancelEdit() when done!
134: *
135: * @param messageId
136: * The id of the message to get.
137: * @return the Message that has the specified id.
138: * @exception IdUnusedException
139: * If this name is not a defined message in this channel.
140: * @exception PermissionException
141: * If the user does not have any permissions to edit the message.
142: * @exception InUseException
143: * if the message is locked for edit by someone else.
144: */
145: MessageEdit editMessage(String messageId) throws IdUnusedException,
146: PermissionException, InUseException;
147:
148: /**
149: * Commit the changes made to a MessageEdit object, and release the lock. The MessageEdit is disabled, and not to be used after this call. If the message is in a form that the user has no permission to store, a PermissionException is thrown, and the
150: * edit is canceled.
151: *
152: * @param user
153: * The UserEdit object to commit.
154: */
155: void commitMessage(MessageEdit edit);
156:
157: /**
158: * Commit the changes made to a MessageEdit object, and release the lock. The MessageEdit is disabled, and not to be used after this call. If the message is in a form that the user has no permission to store, a PermissionException is thrown, and the
159: * edit is canceled.
160: *
161: * @param user
162: * The UserEdit object to commit.
163: * @param priority
164: * The notification priority for this commit.
165: */
166: void commitMessage(MessageEdit edit, int priority);
167:
168: /**
169: * Commit the changes made to a MessageEdit object, and release the lock. The MessageEdit is disabled, and not to be used after this call. If the message is in a form that the user has no permission to store, a PermissionException is thrown, and the
170: * edit is canceled. Used when a scheduled notification is made for this message.
171: *
172: * @param user
173: * The UserEdit object to commit.
174: * @param priority
175: * The notification priority for this commit.
176: * @param invokee
177: * The id for the object to be called when the scheduled notification fires.
178: */
179: void commitMessage(MessageEdit edit, int priority, String invokee);
180:
181: /**
182: * Cancel the changes made to a MessageEdit object, and release the lock. The MessageEdit is disabled, and not to be used after this call.
183: *
184: * @param user
185: * The UserEdit object to commit.
186: */
187: void cancelMessage(MessageEdit edit);
188:
189: /**
190: * check permissions for addMessage().
191: *
192: * @return true if the user is allowed to addMessage(...), false if not.
193: */
194: boolean allowAddMessage();
195:
196: /**
197: * check permission for adding draft message and modifying it afterwards.
198: */
199: boolean allowAddDraftMessage();
200:
201: /**
202: * Check if the user has permission to add a channel-wide (not grouped) message.
203: *
204: * @return true if the user has permission to add a channel-wide (not grouped) message.
205: */
206: boolean allowAddChannelMessage();
207:
208: /**
209: * Add a new message to this channel. Must commitEdit() to make official, or cancelEdit() when done!
210: *
211: * @return The newly added message, locked for update.
212: * @exception PermissionException
213: * If the user does not have write permission to the channel.
214: */
215: MessageEdit addMessage() throws PermissionException;
216:
217: /**
218: * check permissions for removeMessage().
219: *
220: * @param message
221: * The message from this channel to remove.
222: * @return true if the user is allowed to removeMessage(...), false if not.
223: */
224: boolean allowRemoveMessage(Message message);
225:
226: /**
227: * Remove a message from the channel based on message id
228: *
229: * @param messageId
230: * The messageId for the message of the channel to remove.
231: * @exception PermissionException
232: * if the user does not have permission to remove the message.
233: */
234: void removeMessage(String messageId) throws PermissionException;
235:
236: /**
237: * Remove a message from the channel - it must be locked from editMessage().
238: *
239: * @param message
240: * The message from this channel to remove.
241: * @exception PermissionException
242: * if the user does not have permission to remove the message.
243: */
244: void removeMessage(MessageEdit message) throws PermissionException;
245:
246: /**
247: * Merge in a new message as defined in the xml. Must commitEdit() to make official, or cancelEdit() when done!
248: *
249: * @param el
250: * The message information in XML in a DOM element.
251: * @return The newly added message, locked for update.
252: * @exception PermissionException
253: * If the user does not have write permission to the channel.
254: * @exception IdUsedException
255: * if the user id is already used.
256: */
257: MessageEdit mergeMessage(Element el) throws PermissionException,
258: IdUsedException;
259:
260: /**
261: * Get the collection of Groups defined for the context of this channel that the end user has add message permissions in.
262: *
263: * @return The Collection (Group) of groups defined for the context of this channel that the end user has add message permissions in, empty if none.
264: */
265: Collection getGroupsAllowAddMessage();
266:
267: /**
268: * Get the collection of Group defined for the context of this channel that the end user has get message permissions in.
269: *
270: * @return The Collection (Group) of groups defined for the context of this channel that the end user has get message permissions in, empty if none.
271: */
272: Collection getGroupsAllowGetMessage();
273:
274: /**
275: * Get the collection of Group defined for the context of this channel that the end user has remove message permissions in.
276: *
277: * @param own
278: * true if the message is the user's own, false if it is someone else's.
279: * @return The Collection (Group) of groups defined for the context of this channel that the end user has get message permissions in, empty if none.
280: */
281: Collection getGroupsAllowRemoveMessage(boolean own);
282: }
|