01: /**********************************************************************************
02: * $URL: https://source.sakaiproject.org/svn/chat/tags/sakai_2-4-1/chat-api/api/src/java/org/sakaiproject/chat/api/ChatChannel.java $
03: * $Id: ChatChannel.java 8206 2006-04-24 19:40:15Z ggolden@umich.edu $
04: ***********************************************************************************
05: *
06: * Copyright (c) 2003, 2004, 2005, 2006 The Sakai Foundation.
07: *
08: * Licensed under the Educational Community License, Version 1.0 (the "License");
09: * you may not use this file except in compliance with the License.
10: * You may obtain a copy of the License at
11: *
12: * http://www.opensource.org/licenses/ecl1.php
13: *
14: * Unless required by applicable law or agreed to in writing, software
15: * distributed under the License is distributed on an "AS IS" BASIS,
16: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
17: * See the License for the specific language governing permissions and
18: * limitations under the License.
19: *
20: **********************************************************************************/package org.sakaiproject.chat.api;
21:
22: import java.util.List;
23:
24: import org.sakaiproject.exception.IdUnusedException;
25: import org.sakaiproject.exception.InUseException;
26: import org.sakaiproject.exception.PermissionException;
27: import org.sakaiproject.message.api.MessageChannel;
28:
29: /**
30: * <p>
31: * ChatChannel is the extension to the MessageChanel interface for a Sakai Chat service chat channel. Messages in the ChatChannel are ChatMessages with ChatMessageHeaders.
32: * </p>
33: * <p>
34: * Security is defined, see MessageChannel.
35: * </p>
36: * <p>
37: * Usage Events generated:
38: * <ul>
39: * <li>chat.message.channel.read - chat message resource id</li>
40: * <li>chat.message.channel.remove.any - chat message resource id</li>
41: * <li>chat.message.channel.remove.own - chat message resource id</li>
42: * <li>chat.message.channel.post - chat message resource id</li>
43: * </p>
44: */
45: public interface ChatChannel extends MessageChannel {
46: /**
47: * A (ChatMessage) cover for getMessage to return a specific chat channel message, as specified by message id.
48: *
49: * @param messageId
50: * The id of the message to get.
51: * @return the ChatMessage that has the specified id.
52: * @exception IdUnusedException
53: * If this name is not a defined message in this chat channel.
54: * @exception PermissionException
55: * If the user does not have any permissions to read the message.
56: */
57: public ChatMessage getChatMessage(String messageId)
58: throws IdUnusedException, PermissionException;
59:
60: /**
61: * A (ChatMessageEdit) cover for editMessage. Return a specific channel message, as specified by message name, locked for update. Must commitEdit() to make official, or cancelEdit() when done!
62: *
63: * @param messageId
64: * The id of the message to get.
65: * @return the Message that has the specified id.
66: * @exception IdUnusedException
67: * If this name is not a defined message in this channel.
68: * @exception PermissionException
69: * If the user does not have any permissions to read the message.
70: * @exception InUseException
71: * if the current user does not have permission to mess with this user.
72: */
73: public ChatMessageEdit editChatMessage(String messageId)
74: throws IdUnusedException, PermissionException,
75: InUseException;
76:
77: /**
78: * A (ChatMessageEdit) cover for addMessage. Add a new message to this channel. Must commitEdit() to make official, or cancelEdit() when done!
79: *
80: * @return The newly added message, locked for update.
81: * @exception PermissionException
82: * If the user does not have write permission to the channel.
83: */
84: public ChatMessageEdit addChatMessage() throws PermissionException;
85:
86: /**
87: * a (ChatMessage) cover for addMessage to add a new message to this channel.
88: *
89: * @param attachments
90: * The message header attachments, a vector of Reference objects.
91: * @param body
92: * The body text.
93: * @return The newly added message.
94: * @exception PermissionException
95: * If the user does not have write permission to the channel.
96: */
97: public ChatMessage addChatMessage(List attachments, String body)
98: throws PermissionException;
99: }
|