001: /**********************************************************************************
002: * $URL: https://source.sakaiproject.org/svn/podcasts/tags/sakai_2-4-1/podcasts-api/src/java/org/sakaiproject/api/app/podcasts/PodcastService.java $
003: * $Id: PodcastService.java 20203 2007-01-09 16:32:52Z josrodri@iupui.edu $
004: ***********************************************************************************
005: *
006: * Copyright (c) 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.api.app.podcasts;
021:
022: import java.util.Date;
023: import java.util.List;
024:
025: import org.sakaiproject.content.api.ContentCollection;
026: import org.sakaiproject.content.api.ContentCollectionEdit;
027: import org.sakaiproject.content.api.ContentHostingService;
028: import org.sakaiproject.content.api.ContentResourceEdit;
029: import org.sakaiproject.entity.api.ResourceProperties;
030: import org.sakaiproject.exception.IdInvalidException;
031: import org.sakaiproject.exception.IdLengthException;
032: import org.sakaiproject.exception.IdUniquenessException;
033: import org.sakaiproject.exception.IdUnusedException;
034: import org.sakaiproject.exception.IdUsedException;
035: import org.sakaiproject.exception.InUseException;
036: import org.sakaiproject.exception.InconsistentException;
037: import org.sakaiproject.exception.OverQuotaException;
038: import org.sakaiproject.exception.PermissionException;
039: import org.sakaiproject.exception.ServerOverloadException;
040: import org.sakaiproject.exception.TypeException;
041: import org.sakaiproject.tool.api.ToolManager;
042:
043: // import org.sakaiproject.entity.api.EntityProducer;
044:
045: public interface PodcastService // extends EntityProducer
046: {
047: /** This string can be used to find the service in the service manager. */
048: public static final String COLLECTION_PODCASTS = "Podcasts";
049:
050: /** This string can be used as an alternate method to finding the podcasts folder */
051: public static final String COLLECTION_PODCASTS_ALT = "podcasts";
052:
053: /** This string used as part of URL for podcast feed **/
054: public static final String COLLECTION_PODCASTS_FEED = "podcastsFeed";
055:
056: /** This string used for Title of the podcast collection **/
057: public static final String COLLECTION_PODCASTS_TITLE = "Podcasts";
058:
059: /** This string gives description for podcasts folder **/
060: public static final String COLLECTION_PODCASTS_DESCRIPTION = "Common Folder for All Site Podcasts";
061:
062: /** This string gives the Service name (class w/ package prefix) for podcast service **/
063: public static final String PODCASTS_SERVICE_NAME = "org.sakaiproject.api.app.syllabus.PodcastService";
064:
065: /** This string is the name of the property used when displaying and sorting the podcasts **/
066: public static final String DISPLAY_DATE = "displayDate";
067:
068: /** This string is the name of the property for the title of a podcast in the feed **/
069: public static final String DISPLAY_TITLE = "displayTitle";
070:
071: /** This string gives the update function (permission) string for checking permissions **/
072: public static final String UPDATE_PERMISSIONS = "site.upd";
073: public static final String NEW_PERMISSIONS = "content.new";
074: public static final String READ_PERMISSIONS = "content.read";
075: public static final String REVISE_ANY_PERMISSIONS = "content.revise.any";
076: public static final String REVISE_OWN_PERMISSIONS = "content.revise.own";
077: public static final String DELETE_ANY_PERMISSIONS = "content.delete.any";
078: public static final String DELETE_OWN_PERMISSIONS = "content.delete.own";
079:
080: /**
081: * Determines if podcast folder is part of Resources of site.
082: * If not, creates it.
083: *
084: * @return true if folder exists/created, false otherwise.
085: */
086: public boolean checkPodcastFolder() throws InUseException,
087: PermissionException;
088:
089: /**
090: * Will check if any podcasts were added in Resources and do not have their DISPLAY_DATE property set.
091: *
092: * @param resourcesList The List of podcasts to check
093: *
094: * @return List of updated podcasts
095: */
096: public List checkDISPLAY_DATE(List resourcesList);
097:
098: /**
099: * Determines if there are actual podcasts in the folder
100: *
101: * @return true if there are actual podcasts, false otherwise
102: */
103: public boolean checkForActualPodcasts() throws PermissionException;
104:
105: /**
106: * Used to inject the ContentHostingService
107: *
108: * @param chs The application's ContentHostingService
109: */
110: public void setContentHostingService(ContentHostingService chs);
111:
112: /**
113: * Used to inject the ToolManager
114: *
115: * @param tm The application's ToolManager
116: */
117: public void setToolManager(ToolManager tm);
118:
119: /**
120: * Returns a list of the podcasts stored in site/podcasts folder
121: *
122: * @return List of podcasts
123: */
124: public List getPodcasts() throws PermissionException,
125: InUseException, IdInvalidException, InconsistentException,
126: IdUsedException;
127:
128: /**
129: * Returns a list of the podcasts stored in site/podcasts folder
130: *
131: * @param siteID Passed in by the podfeed server
132: *
133: * @return List of podcasts
134: *
135: * @throws PermissionException
136: * @throws InUseException
137: * @throws IdInvalidException
138: * @throws InconsistentException
139: * @throws IdUsedException
140: */
141: public List getPodcasts(String siteID) throws PermissionException,
142: InUseException, IdInvalidException, InconsistentException,
143: IdUsedException;
144:
145: /**
146: * Returns SiteId for the site this tool is a part of
147: *
148: * @return String of the site id
149: */
150: public String getSiteId();
151:
152: /**
153: * Returns UserId for the current user
154: *
155: * @return String of the user ID
156: */
157: public String getUserId();
158:
159: /**
160: * Returns user display name for current user
161: *
162: * @return String of the user display name
163: */
164: public String getUserName();
165:
166: /**
167: * Returns the full URL of the file from ContentHostingService
168: *
169: * @param resourceId The ID for the file whose URL is wanted
170: *
171: * @return String The full URL for the file
172: */
173: public String getPodcastFileURL(String resourceId)
174: throws PermissionException, IdUnusedException;
175:
176: /**
177: * Returns an editable resource if ID exists.
178: *
179: * @param String
180: * The resourceId of the resource to get
181: *
182: * @return ContentResourceEdit
183: * If found, null otherwise
184: */
185: public ContentResourceEdit getAResource(String resourceId)
186: throws PermissionException, IdUnusedException;
187:
188: /**
189: * Sets the DISPLAY_DATE property of a podcast to CREATION_DATE
190: *
191: * @param rp The ResourceProperties of the podcast to set
192: */
193: public void setDISPLAY_DATE(ResourceProperties rp);
194:
195: /**
196: * Does the actual adding of podcast to Resources
197: *
198: * @param title User specified title for the podcast
199: * @param displayDate Date when podcast will be available for viewing
200: * @param description User specified description for the podcast
201: * @param body The actual contents of the podcast
202: * @param filename The filename of the podcast being saved
203: */
204: public void addPodcast(String title, Date displayDate,
205: String description, byte[] body, String filename,
206: String contentType) throws OverQuotaException,
207: ServerOverloadException, InconsistentException,
208: IdInvalidException, IdLengthException, PermissionException,
209: IdUniquenessException;
210:
211: /**
212: * Removes a podcast from site/podcasts folder
213: *
214: * @param resourceId resourceId of the podcast to be deleted
215: */
216: public void removePodcast(String resourceId)
217: throws IdUnusedException, InUseException, TypeException,
218: PermissionException;
219:
220: /**
221: * Returns an editable resource if ID exists.
222: *
223: * @return ContentResourceEdit object if ID valid, null otherwise
224: */
225: public void revisePodcast(String resourceId, String title,
226: Date date, String description, byte[] body, String filename)
227: throws PermissionException, InUseException,
228: OverQuotaException, ServerOverloadException;
229:
230: /**
231: * Determines if user can modify the site. Used by feed.
232: *
233: * @return boolean true if user can modify, false otherwise
234: */
235: public boolean canUpdateSite(String siteId);
236:
237: /**
238: * Determines if user can modify the site. Used within the tool.
239: *
240: * @return boolean true if user can modify, false otherwise
241: */
242: public boolean canUpdateSite();
243:
244: /**
245: * Determines if user has the function (permission) passed in
246: *
247: * @return boolean true if user has function (permission), false otherwise.
248: */
249: public boolean hasPerm(String function);
250:
251: /**
252: * Returns the ContentCollection that contains the podcasts.
253: *
254: * @param siteId The site id to pull the correct collection
255: *
256: * @return ContentCollection
257: */
258: public ContentCollection getContentCollection(String siteId)
259: throws IdUnusedException, PermissionException;
260:
261: /**
262: * Returns the ContentCollection that contains the podcasts.
263: *
264: * @param siteId The site id to pull the correct collection
265: *
266: * @return ContentCollection
267: */
268: public ContentCollectionEdit getContentCollectionEditable(
269: String siteId) throws IdUnusedException,
270: PermissionException, InUseException;
271:
272: /**
273: * Changes whether the podcast folder is public/private
274: *
275: * @param option int that sets the public/private option
276: */
277: public void reviseOptions(boolean option);
278:
279: /**
280: * Only add podcast resources whose DISPLAY_DATE is today or earlier
281: *
282: * @param resourcesList List of podcasts
283: *
284: * @return List of podcasts whose DISPLAY_DATE is today or before
285: */
286: public List filterPodcasts(List resourcesList);
287:
288: /**
289: * Gets whether the podcast folder is Publicly viewable or not.
290: *
291: * @return int 0 = Public 1 = Site
292: */
293: public int getOptions();
294:
295: /**
296: * Commit the changes made to the ContentCollection.
297: *
298: * @param contentCollectionEdit The ContentCollection object that needs to be commited.
299: */
300: public void commitContentCollection(
301: ContentCollectionEdit contentCollectionEdit);
302:
303: /**
304: * Cancels attempt at changing this collection (releases the lock)
305: *
306: * @param cce
307: * The ContentCollectionEdit that is not to be changed
308: */
309: public void cancelContentCollection(ContentCollectionEdit cce);
310:
311: /**
312: * Returns podcast folder id using either 'podcasts' or 'Podcasts'. If it
313: * does not exist in either form, will create it.
314: *
315: * @param siteId
316: * The site to search
317: * @return String containing the complete id for the podcast folder
318: *
319: * @throws PermissionException
320: */
321: public String retrievePodcastFolderId(String siteId)
322: throws PermissionException;
323:
324: /**
325: * Returns whether site is Public (true) or Site (false)
326: * @param siteId
327: * @return
328: */
329: public boolean isPublic(String siteId);
330:
331: /**
332: * Takes the date String passed in and converts it to a Date object
333: * using GMT time
334: *
335: * @param date
336: * A long value representing the date to be converted`
337: *
338: * @return
339: * Date object created
340: */
341: public Date getGMTdate(long date);
342:
343: /**
344: * Determines if authenticated user has 'read' access to podcast collection folder
345: *
346: * @param id
347: * The id for the podcast collection folder
348: *
349: * @return
350: * TRUE - has read access, FALSE - does not
351: */
352: public boolean allowAccess(String id);
353:
354: }
|