001: /**********************************************************************************
002: * $URL: https://source.sakaiproject.org/svn/site/tags/sakai_2-4-1/site-api/api/src/java/org/sakaiproject/site/api/SiteService.java $
003: * $Id: SiteService.java 18632 2006-12-05 02:04:19Z ggolden@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.site.api;
021:
022: import java.util.List;
023: import java.util.Map;
024: import java.util.Set;
025:
026: import org.sakaiproject.entity.api.Entity;
027: import org.sakaiproject.entity.api.EntityProducer;
028: import org.sakaiproject.exception.IdInvalidException;
029: import org.sakaiproject.exception.IdUnusedException;
030: import org.sakaiproject.exception.IdUsedException;
031: import org.sakaiproject.exception.InUseException;
032: import org.sakaiproject.exception.PermissionException;
033: import org.sakaiproject.javax.PagingPosition;
034: import org.w3c.dom.Element;
035:
036: /**
037: * <p>
038: * SiteService manages Sites.
039: * </p>
040: */
041: public interface SiteService extends EntityProducer {
042: /** The type string for this application: should not change over time as it may be stored in various parts of persistent entities. */
043: static final String APPLICATION_ID = "sakai:site";
044:
045: /** The Entity Reference sub-type for Site references. */
046: static final String SITE_SUBTYPE = "site";
047:
048: /** The Entity Reference sub-type for Group references. */
049: static final String GROUP_SUBTYPE = "group";
050:
051: /** The Entity Reference sub-type for Page references. */
052: static final String PAGE_SUBTYPE = "page";
053:
054: /** The Entity Reference sub-type for Tool references. */
055: static final String TOOL_SUBTYPE = "tool";
056:
057: /** This string starts the references to resources in this service. */
058: static final String REFERENCE_ROOT = Entity.SEPARATOR
059: + SITE_SUBTYPE;
060:
061: /** Name for the event of visiting a site. */
062: static final String SITE_VISIT = "site.visit";
063:
064: /** Name for the event of visiting an unpublished site. */
065: static final String SITE_VISIT_UNPUBLISHED = "site.visit.unp";
066:
067: /** Name for the event of accessing a site. */
068: // static final String SECURE_ACCESS_SITE = "site.access";
069: /** Name for the event of adding a site. */
070: static final String SECURE_ADD_SITE = "site.add";
071:
072: /** Name for the event of adding a user's My Workspace site. */
073: static final String SECURE_ADD_USER_SITE = "site.add.usersite";
074:
075: /** Name for the event of removing a site. */
076: static final String SECURE_REMOVE_SITE = "site.del";
077:
078: /** Name for the event of updating a site. */
079: static final String SECURE_UPDATE_SITE = "site.upd";
080:
081: /** Name for the event of updating a site's membership. */
082: static final String SECURE_UPDATE_SITE_MEMBERSHIP = "site.upd.site.mbrshp";
083:
084: /** Name for the event of updating a site's groups' memberships. */
085: static final String SECURE_UPDATE_GROUP_MEMBERSHIP = "site.upd.grp.mbrshp";
086:
087: /** Name for the event of viewing project site participants. */
088: static final String SECURE_VIEW_ROSTER = "site.viewRoster";
089:
090: /** The name of the main container for a resource in a site (channel, calendar, etc.). */
091: static final String MAIN_CONTAINER = "main";
092:
093: /** The name of a special site that is a template for non-user sites. */
094: static final String SITE_TEMPLATE = "!worksite";
095:
096: /** The name of a special site that is a template for user sites. */
097: static final String USER_SITE_TEMPLATE = "!user";
098:
099: /** The name of a special site that is used if the requested site is not available. */
100: static final String SITE_ERROR = "!error";
101:
102: /** The name of a special site that is used if the requested url is not understood. */
103: static final String URL_ERROR = "!urlError";
104:
105: /**
106: * <p>
107: * SelectionType enumerates different supported types of selection criteria for getting / counting sites.
108: * </p>
109: */
110: public class SelectionType {
111: private final String m_id;
112:
113: private final boolean m_ignoreSpecial;
114:
115: private final boolean m_ignoreUser;
116:
117: private final boolean m_ignoreUnpublished;
118:
119: private SelectionType(String id, boolean ignoreSpecial,
120: boolean ignoreUser, boolean ignoreUnpublished) {
121: m_id = id;
122: m_ignoreSpecial = ignoreSpecial;
123: m_ignoreUser = ignoreUser;
124: m_ignoreUnpublished = ignoreUnpublished;
125: }
126:
127: public String toString() {
128: return m_id;
129: }
130:
131: public boolean isIgnoreSpecial() {
132: return m_ignoreSpecial;
133: }
134:
135: public boolean isIgnoreUser() {
136: return m_ignoreUser;
137: }
138:
139: public boolean isIgnoreUnpublished() {
140: return m_ignoreUnpublished;
141: }
142:
143: /** Get sites that the current user has read access to (non-myWorkspace, non-special). */
144: public static final SelectionType ACCESS = new SelectionType(
145: "access", true, true, false);
146:
147: /** Get sites that the current user has write access to (non-myWorkspace, non-special). */
148: public static final SelectionType UPDATE = new SelectionType(
149: "update", true, true, false);
150:
151: /** Get sites that the current user does not have read access to but are joinable (non-myWorkspace, non-special). */
152: public static final SelectionType JOINABLE = new SelectionType(
153: "joinable", true, true, true);
154:
155: /** Get sites that are marked for view (non-myWorkspace, non-special). */
156: public static final SelectionType PUBVIEW = new SelectionType(
157: "pubView", true, true, true);
158:
159: /** Get any sites. */
160: public static final SelectionType ANY = new SelectionType(
161: "any", false, false, false);
162:
163: /** Get any non-user sites. */
164: public static final SelectionType NON_USER = new SelectionType(
165: "nonUser", false, true, false);
166: }
167:
168: /**
169: * <p>
170: * SortType enumerates different supported types of site sorting.
171: * </p>
172: */
173: public class SortType {
174: private final String m_id;
175:
176: private final boolean m_asc;
177:
178: private SortType(String id, boolean asc) {
179: m_id = id;
180: m_asc = asc;
181: }
182:
183: public String toString() {
184: return m_id;
185: }
186:
187: public boolean isAsc() {
188: return m_asc;
189: }
190:
191: /** Sort on title ASC */
192: public static final SortType NONE = new SortType("none", true);
193:
194: /** Sort on id ASC */
195: public static final SortType ID_ASC = new SortType("id", true);
196:
197: /** Sort on id DESC */
198: public static final SortType ID_DESC = new SortType("id", false);
199:
200: /** Sort on title ASC */
201: public static final SortType TITLE_ASC = new SortType("title",
202: true);
203:
204: /** Sort on title DESC */
205: public static final SortType TITLE_DESC = new SortType("title",
206: false);
207:
208: /** Sort on type ASC */
209: public static final SortType TYPE_ASC = new SortType("type",
210: true);
211:
212: /** Sort on type DESC */
213: public static final SortType TYPE_DESC = new SortType("type",
214: false);
215:
216: /** Sort on published ASC */
217: public static final SortType PUBLISHED_ASC = new SortType(
218: "published", true);
219:
220: /** Sort on published DESC */
221: public static final SortType PUBLISHED_DESC = new SortType(
222: "published", false);
223:
224: /** Sort on created by ASC */
225: public static final SortType CREATED_BY_ASC = new SortType(
226: "created by", true);
227:
228: /** Sort on created by DESC */
229: public static final SortType CREATED_BY_DESC = new SortType(
230: "created by", false);
231:
232: /** Sort on modified by ASC */
233: public static final SortType MODIFIED_BY_ASC = new SortType(
234: "modified by", true);
235:
236: /** Sort on modified by DESC */
237: public static final SortType MODIFIED_BY_DESC = new SortType(
238: "modified by", false);
239:
240: /** Sort on created time ASC */
241: public static final SortType CREATED_ON_ASC = new SortType(
242: "created on", true);
243:
244: /** Sort on created time DESC */
245: public static final SortType CREATED_ON_DESC = new SortType(
246: "created on", false);
247:
248: /** Sort on modified time ASC */
249: public static final SortType MODIFIED_ON_ASC = new SortType(
250: "modified on", true);
251:
252: /** Sort on modified time DESC */
253: public static final SortType MODIFIED_ON_DESC = new SortType(
254: "modified on", false);
255: }
256:
257: /**
258: * Get an array of names to match the site page layout options.
259: *
260: * @return The array of human readable layout titles possible for any site page.
261: */
262: String[] getLayoutNames();
263:
264: /**
265: * check permissions for accessing (i.e. visiting) a site
266: *
267: * @param id
268: * The site id.
269: * @return true if the site is allowed to access the site, false if not.
270: */
271: boolean allowAccessSite(String id);
272:
273: /**
274: * Is this a valid site id?
275: *
276: * @param id
277: * The site id string.
278: * @return True if a site with this id is defined, false if not.
279: */
280: boolean siteExists(String id);
281:
282: /**
283: * Access a site object.
284: *
285: * @param id
286: * The site id string.
287: * @return A site object containing the site information.
288: * @exception IdUnusedException
289: * if not found.
290: */
291: Site getSite(String id) throws IdUnusedException;
292:
293: /**
294: * Access a site object for purposes of having the user visit the site - visitation permissions are in effect.
295: *
296: * @param id
297: * The site id string.
298: * @return A site object containing the site information.
299: * @exception IdUnusedException
300: * if not found.
301: * @exception PermissionException
302: * if the current user does not have permission to visit this site.
303: */
304: Site getSiteVisit(String id) throws IdUnusedException,
305: PermissionException;
306:
307: /**
308: * check permissions for updating a site
309: *
310: * @param id
311: * The site id.
312: * @return true if the site is allowed to update the site, false if not.
313: */
314: boolean allowUpdateSite(String id);
315:
316: /**
317: * check permissions for updating a site's membership
318: *
319: * @param id
320: * The site id.
321: * @return true if the site is allowed to update the site's membership, false if not.
322: */
323: boolean allowUpdateSiteMembership(String id);
324:
325: /**
326: * check permissions for updating a site's groups' memberships
327: *
328: * @param id
329: * The site id.
330: * @return true if the site is allowed to update the site's groups' memberships, false if not.
331: */
332: boolean allowUpdateGroupMembership(String id);
333:
334: /**
335: * Save any updates to this site - it must be a defined site (the id must exist) and the user must have update permissions.
336: *
337: * @param site
338: * The site, modified, to save.
339: * @throws IdUnusedException
340: * If the site's id is not a defined site id.
341: * @throws PermissionException
342: * If the end user does not have permission to update the site.
343: */
344: void save(Site site) throws IdUnusedException, PermissionException;
345:
346: /**
347: * Save only site membership updates to this site - it must be a defined site (the id must exist) and the user must have site membership update permissions.
348: *
349: * @param site
350: * The site, modified, to save.
351: * @throws IdUnusedException
352: * If the site's id is not a defined site id.
353: * @throws PermissionException
354: * If the end user does not have permission to update the membership of the site.
355: */
356: void saveSiteMembership(Site site) throws IdUnusedException,
357: PermissionException;
358:
359: /**
360: * Save only site group membership updates to this site - it must be a defined site (the id must exist) and the user must have site group membership update permissions.
361: *
362: * @param site
363: * The site, modified, to save.
364: * @throws IdUnusedException
365: * If the site's id is not a defined site id.
366: * @throws PermissionException
367: * If the end user does not have permission to update the membership of the site.
368: */
369: void saveGroupMembership(Site site) throws IdUnusedException,
370: PermissionException;
371:
372: /**
373: * Save a site's information display fields: description and info url
374: *
375: * @param id
376: * The site id to update.
377: * @param description
378: * The updated description.
379: * @param infoUrl
380: * The updated infoUrl
381: * @throws IdUnusedException
382: * If the site's id is not a defined site id.
383: * @throws PermissionException
384: * If the end user does not have permission to update the site.
385: */
386: void saveSiteInfo(String id, String description, String infoUrl)
387: throws IdUnusedException, PermissionException;
388:
389: /**
390: * check permissions for addSite().
391: *
392: * @param id
393: * The site id.
394: * @return true if the site is allowed to addSite(id), false if not.
395: */
396: boolean allowAddSite(String id);
397:
398: /**
399: * Add a new site. The site will exist with just an id once done, so remove() it if you don't want to keep it.
400: *
401: * @param id
402: * The site id.
403: * @param type
404: * The site type.
405: * @return The new site object.
406: * @exception IdInvalidException
407: * if the site id is invalid.
408: * @exception IdUsedException
409: * if the site id is already used.
410: * @exception PermissionException
411: * if the current user does not have permission to add a site.
412: */
413: Site addSite(String id, String type) throws IdInvalidException,
414: IdUsedException, PermissionException;
415:
416: /**
417: * Add a new site. Will be structured just like <other>.
418: *
419: * @param id
420: * The site id.
421: * @param other
422: * The site to make this site a structural copy of.
423: * @return The new site object.
424: * @exception IdInvalidException
425: * if the site id is invalid.
426: * @exception IdUsedException
427: * if the site id is already used.
428: * @exception PermissionException
429: * if the current user does not have permission to add a site.
430: */
431: Site addSite(String id, Site other) throws IdInvalidException,
432: IdUsedException, PermissionException;
433:
434: /**
435: * check permissions for removeSite().
436: *
437: * @param id
438: * The site id.
439: * @return true if the site is allowed to removeSite(id), false if not.
440: */
441: boolean allowRemoveSite(String id);
442:
443: /**
444: * Remove this site's information.
445: *
446: * @param id
447: * The site id.
448: * @exception PermissionException
449: * if the current user does not have permission to remove this site.
450: */
451: void removeSite(Site site) throws PermissionException;
452:
453: /**
454: * Access the internal reference which can be used to access the site from within the system.
455: *
456: * @param id
457: * The site id.
458: * @return The the internal reference which can be used to access the site from within the system.
459: */
460: String siteReference(String id);
461:
462: /**
463: * Access the internal reference which can be used to access the site page from within the system.
464: *
465: * @param siteId
466: * The site id.
467: * @param pageId
468: * The page id.
469: * @return The the internal reference which can be used to access the site page from within the system.
470: */
471: String sitePageReference(String siteId, String pageId);
472:
473: /**
474: * Access the internal reference which can be used to access the site tool from within the system.
475: *
476: * @param siteId
477: * The site id.
478: * @param toolId
479: * The tool id.
480: * @return The the internal reference which can be used to access the site tool from within the system.
481: */
482: String siteToolReference(String siteId, String toolId);
483:
484: /**
485: * Access the internal reference which can be used to access the site group from within the system.
486: *
487: * @param siteId
488: * The site id.
489: * @param groupId
490: * The group id.
491: * @return The the internal reference which can be used to access the site group from within the system.
492: */
493: String siteGroupReference(String siteId, String groupId);
494:
495: /**
496: * Is this site (id or reference) a user site?
497: *
498: * @param site
499: * The site id or reference.
500: * @return true if this is a user site, false if not.
501: */
502: boolean isUserSite(String site);
503:
504: /**
505: * Extract the user id for this user site from the site id or reference.
506: *
507: * @param site
508: * The site id or reference.
509: * @return The user id associated with this site.
510: */
511: String getSiteUserId(String site);
512:
513: /**
514: * Form the site id for this user's site.
515: *
516: * @param userId
517: * The user id.
518: * @return The site id for this user's site.
519: */
520: String getUserSiteId(String userId);
521:
522: /**
523: * Is this site (id or reference) a special site?
524: *
525: * @param site
526: * The site id or reference.
527: * @return true if this is a special site, false if not.
528: */
529: boolean isSpecialSite(String site);
530:
531: /**
532: * Extract the special id for this special site from the site id or reference.
533: *
534: * @param site
535: * The site id or reference.
536: * @return The special id associated with this site.
537: */
538: String getSiteSpecialId(String site);
539:
540: /**
541: * Form the site id for this special site.
542: *
543: * @param special
544: * The special id.
545: * @return The site id for this user's site.
546: */
547: String getSpecialSiteId(String special);
548:
549: /**
550: * Form a display of the site title and id for this site.
551: *
552: * @param id
553: * The site id.
554: * @return A display of the site title and id for this site.
555: */
556: String getSiteDisplay(String id);
557:
558: /**
559: * Access the ToolConfiguration that has this id, if one is defined, else return null. The tool may be on any Site and on any SitePage.
560: *
561: * @param id
562: * The id of the tool.
563: * @return The ToolConfiguration that has this id, if one is defined, else return null.
564: */
565: ToolConfiguration findTool(String id);
566:
567: /**
568: * Access the Page that has this id, if one is defined, else return null. The page may be on any Site.
569: *
570: * @param id
571: * The id of the page.
572: * @return The SitePage that has this id, if one is defined, else return null.
573: */
574: SitePage findPage(String id);
575:
576: /**
577: * check permissions for viewing project site participants
578: *
579: * @param id
580: * The site id.
581: * @return true if the site is allowed to addSite(id), false if not.
582: */
583: boolean allowViewRoster(String id);
584:
585: /**
586: * Cause the current user to join the site as defined by the site's joinable flag and joiner role.
587: *
588: * @param id
589: * The site id.
590: * @throws IdUnusedException
591: * if the id is not a valid site id.
592: * @exception PermissionException
593: * if the current user does not have permission to join this site.
594: * @exception InUseException
595: * if the site is otherwise being edited.
596: */
597: void join(String id) throws IdUnusedException, PermissionException;
598:
599: /**
600: * check permissions for unjoin() - unjoining the site and removing all role relationships.
601: *
602: * @param id
603: * The site id.
604: * @return true if the user is allowed to unjoin(id), false if not.
605: */
606: boolean allowUnjoinSite(String id);
607:
608: /**
609: * Cause the current user to unjoin the site, removing all role relationships.
610: *
611: * @param id
612: * The site id.
613: * @throws IdUnusedException
614: * if the id is not a valid site id.
615: * @exception PermissionException
616: * if the current user does not have permission to unjoin this site.
617: * @exception InUseException
618: * if the site is otherwise being edited.
619: */
620: void unjoin(String id) throws IdUnusedException,
621: PermissionException;
622:
623: /**
624: * Compute the skin to use for the (optional) site specified in the id parameter. If no site specified, or if the site has no skin defined, use the configured default skin.
625: *
626: * @param id
627: * The (optional) site id.
628: * @return A skin to use for this site.
629: */
630: String getSiteSkin(String id);
631:
632: /**
633: * Access a unique list of String site types for any site type defined for any site, sorted by type.
634: *
635: * @return A list (String) of all used site types.
636: */
637: List getSiteTypes();
638:
639: /**
640: * Access a list of Site objets that meet specified criteria.
641: *
642: * @param type
643: * The SelectionType specifying what sort of selection is intended.
644: * @param ofType
645: * Site type criteria: null for any type; a String to match a single type; A String[], List or Set to match any type in the collection.
646: * @param criteria
647: * Additional selection criteria: sites returned will match this string somewhere in their id, title, description, or skin.
648: * @param propertyCriteria
649: * Additional selection criteria: sites returned will have a property named to match each key in the map, whose values match (somewhere in their value) the value in the map (may be null or empty).
650: * @param sort
651: * A SortType indicating the desired sort. For no sort, set to SortType.NONE.
652: * @param page
653: * The PagePosition subset of items to return.
654: * @return The List (Site) of Site objets that meet specified criteria.
655: */
656: List getSites(SelectionType type, Object ofType, String criteria,
657: Map propertyCriteria, SortType sort, PagingPosition page);
658:
659: /**
660: * Count the Site objets that meet specified criteria.
661: *
662: * @param type
663: * The SelectionType specifying what sort of selection is intended.
664: * @param ofType
665: * Site type criteria: null for any type; a String to match a single type; A String[], List or Set to match any type in the collection.
666: * @param criteria
667: * Additional selection criteria: sits returned will match this string somewhere in their id, title, description, or skin.
668: * @param propertyCriteria
669: * Additional selection criteria: sites returned will have a property named to match each key in the map, whose values match (somewhere in their value) the value in the map (may be null or empty).
670: * @return The count of Site objets that meet specified criteria.
671: */
672: int countSites(SelectionType type, Object ofType, String criteria,
673: Map propertyCriteria);
674:
675: /**
676: * Establish the internal security for this site. Previous security settings are replaced for this site. Assigning a user with update implies the two reads; assigning a user with unp read implies the other read.
677: *
678: * @param siteId
679: * The id of the site.
680: * @param updateUsers
681: * The set of String User Ids who have update access.
682: * @param visitUnpUsers
683: * The set of String User Ids who have visit unpublished access.
684: * @param visitUsers
685: * The set of String User Ids who have visit access.
686: */
687: void setSiteSecurity(String siteId, Set updateUsers,
688: Set visitUnpUsers, Set visitUsers);
689:
690: /**
691: * Establish the internal security for user for all sites. Previous security settings are replaced for this user. Assigning a user with update implies the two reads; assigning a user with unp read implies the other read.
692: *
693: * @param userId
694: * The id of the user.
695: * @param updateSites
696: * The set of String site ids where the user has update access.
697: * @param visitUnpSites
698: * The set of String site ids where the user has visit unpublished access.
699: * @param visitSites
700: * The set of String site ids where the user has visit access.
701: */
702: void setUserSecurity(String userId, Set updateSites,
703: Set visitUnpSites, Set visitSites);
704:
705: /**
706: * Merge the site information from the archive into the given site.
707: *
708: * @param toSiteId
709: * The target site id.
710: * @param fromSite
711: * The source site id
712: * @param e
713: * The XML DOM tree of content to merge.
714: * @param creatorId
715: * The site creator id for target site.
716: * @return A log of status messages from the archive.
717: */
718: String merge(String toSiteId, Element e, String creatorId);
719:
720: /**
721: * Access a Group object, given a reference string or id.
722: *
723: * @param refOrId
724: * The group reference or id string.
725: * @return The Group object if found, or null if not.
726: */
727: Group findGroup(String refOrId);
728:
729: /**
730: * Registers a SiteAdvisor with the SiteService. Each registered advisor will be
731: * called immediately upon a call to save(Site).
732: *
733: * @param advisor The SiteAdvisor to add
734: */
735: public void addSiteAdvisor(SiteAdvisor advisor);
736:
737: /**
738: * Removes a SiteAdvisor.
739: *
740: * @param advisor The SiteAdvisor to remove
741: * @return Whether the SiteAdvisor was previously registered and hence removed.
742: */
743: public boolean removeSiteAdvisor(SiteAdvisor advisor);
744:
745: /**
746: * Lists the current SiteAdvisors registered with the SiteService.
747: *
748: * @return An unmodifiable List containing the currently registered SiteAdvisors
749: */
750: public List<SiteAdvisor> getSiteAdvisors();
751: }
|