001: /**********************************************************************************
002: * $URL: https://source.sakaiproject.org/svn/announcement/tags/sakai_2-4-1/announcement-api/api/src/java/org/sakaiproject/announcement/api/AnnouncementService.java $
003: * $Id: AnnouncementService.java 22562 2007-03-13 19:52:22Z 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.announcement.api;
021:
022: import org.sakaiproject.entity.api.Entity;
023: import org.sakaiproject.exception.IdInvalidException;
024: import org.sakaiproject.exception.IdUnusedException;
025: import org.sakaiproject.exception.IdUsedException;
026: import org.sakaiproject.exception.PermissionException;
027: import org.sakaiproject.message.api.MessageService;
028:
029: /**
030: * <p>
031: * AnnouncementService is the extension to MessageService configured for Announcements.
032: * </p>
033: * <p>
034: * MessageChannels are AnnouncementMessageChannels, and Messages are AnnouncementMessages with AnnouncementMessageHeaders.
035: * </p>
036: * <p>
037: * Security in the announcement service, in addition to that defined in the channels, include:
038: * <ul>
039: * <li>announcement.channel.add</li>
040: * </ul>
041: * </p>
042: * <li>announcement.channel.remove</li>
043: * </ul>
044: * </p>
045: * <p>
046: * Usage Events are generated:
047: * <ul>
048: * <li>announcement.channel.add - announcement channel resource id</li>
049: * <li>announcement.channel.remove - announcement channel resource id</li>
050: * </ul>
051: * </p>
052: */
053: public interface AnnouncementService extends MessageService {
054: /** The type string for this application: should not change over time as it may be stored in various parts of persistent entities. */
055: static final String APPLICATION_ID = "sakai:announcement";
056:
057: /** This string starts the references to resources in this service. */
058: public static final String REFERENCE_ROOT = Entity.SEPARATOR
059: + "announcement";
060:
061: /** Security lock / event root for generic message events to make it a mail event. */
062: public static final String SECURE_ANNC_ROOT = "annc.";
063:
064: /** Security lock / event for reading channel / message. */
065: public static final String SECURE_ANNC_READ = SECURE_ANNC_ROOT
066: + SECURE_READ;
067:
068: /** Security lock / event for adding channel / message. */
069: public static final String SECURE_ANNC_ADD = SECURE_ANNC_ROOT
070: + SECURE_ADD;
071:
072: /** Security lock / event for removing one's own message. */
073: public static final String SECURE_ANNC_REMOVE_OWN = SECURE_ANNC_ROOT
074: + SECURE_REMOVE_OWN;
075:
076: /** Security lock / event for removing anyone's message or channel. */
077: public static final String SECURE_ANNC_REMOVE_ANY = SECURE_ANNC_ROOT
078: + SECURE_REMOVE_ANY;
079:
080: /** Security lock / event for updating one's own message or the channel. */
081: public static final String SECURE_ANNC_UPDATE_OWN = SECURE_ANNC_ROOT
082: + SECURE_UPDATE_OWN;
083:
084: /** Security lock / event for updating any message. */
085: public static final String SECURE_ANNC_UPDATE_ANY = SECURE_ANNC_ROOT
086: + SECURE_UPDATE_ANY;
087:
088: /** Security lock / event for accessing someone elses draft. */
089: public static final String SECURE_ANNC_READ_DRAFT = SECURE_ANNC_ROOT
090: + SECURE_READ_DRAFT;
091:
092: /** Security function giving the user permission to all groups, if granted to at the channel or site level. */
093: public static final String SECURE_ANNC_ALL_GROUPS = SECURE_ANNC_ROOT
094: + SECURE_ALL_GROUPS;
095:
096: /**
097: * A (AnnouncementChannel) cover for getChannel() to return a specific announcement channel.
098: *
099: * @param ref
100: * The channel reference.
101: * @return the AnnouncementChannel that has the specified name.
102: * @exception IdUnusedException
103: * If this name is not defined for a announcement channel.
104: * @exception PermissionException
105: * If the user does not have any permissions to the channel.
106: */
107: public AnnouncementChannel getAnnouncementChannel(String ref)
108: throws IdUnusedException, PermissionException;
109:
110: /**
111: * A (AnnouncementChannel) cover for addChannel() to add a new announcement channel.
112: *
113: * @param ref
114: * The channel reference.
115: * @return The newly created channel.
116: * @exception IdUsedException
117: * if the id is not unique.
118: * @exception IdInvalidException
119: * if the id is not made up of valid characters.
120: * @exception PermissionException
121: * if the user does not have permission to add a channel.
122: */
123: public AnnouncementChannelEdit addAnnouncementChannel(String ref)
124: throws IdUsedException, IdInvalidException,
125: PermissionException;
126:
127: }
|