org.sakaiproject.service.legacy.site
Interface SiteService

All Superinterfaces:
EntityProducer
All Known Implementing Classes:
BaseSiteService

public interface SiteService
extends EntityProducer

SiteService manages Sites.

Author:
Sakai Software Development Team

Nested Class Summary
static class SiteService.SelectionType
           SelectionType enumerates different supported types of selection criteria for getting / counting sites.
static class SiteService.SortType
           SortType enumerates different supported types of site sorting.
 
Nested classes inherited from class org.sakaiproject.service.legacy.entity.EntityProducer
EntityProducer.ChangeType
 
Field Summary
static String GROUP_SUBTYPE
          The Entity Reference sub-type for Group references.
static String MAIN_CONTAINER
          The name of the main container for a resource in a site (channel, calendar, etc.).
static String PAGE_SUBTYPE
          The Entity Reference sub-type for Page references.
static String REFERENCE_ROOT
          This string starts the references to resources in this service.
static String SECURE_ADD_SITE
          Name for the event of adding a site.
static String SECURE_ADD_USER_SITE
          Name for the event of adding a user's My Workspace site.
static String SECURE_REMOVE_SITE
          Name for the event of removing a site.
static String SECURE_UPDATE_GROUP_MEMBERSHIP
          Name for the event of updating a site's groups' memberships.
static String SECURE_UPDATE_SITE
          Name for the event of updating a site.
static String SECURE_UPDATE_SITE_MEMBERSHIP
          Name for the event of updating a site's membership.
static String SECURE_VIEW_ROSTER
          Name for the event of viewing project site participants.
static String SERVICE_NAME
          This string can be used to find the service in the service manager.
static String SITE_ERROR
          The name of a special site that is used if the requested site is not available.
static String SITE_SUBTYPE
          The Entity Reference sub-type for Site references.
static String SITE_TEMPLATE
          The name of a special site that is a template for non-user sites.
static String SITE_VISIT
          Name for the event of visiting a site.
static String SITE_VISIT_UNPUBLISHED
          Name for the event of visiting an unpublished site.
static String TOOL_SUBTYPE
          The Entity Reference sub-type for Tool references.
static String URL_ERROR
          The name of a special site that is used if the requested url is not understood.
static String USER_SITE_TEMPLATE
          The name of a special site that is a template for user sites.
 
Method Summary
 Site addSite(String id, Site other)
          Add a new site.
 Site addSite(String id, String type)
          Add a new site.
 boolean allowAccessSite(String id)
          check permissions for accessing (i.e. visiting) a site
 boolean allowAddSite(String id)
          check permissions for addSite().
 boolean allowRemoveSite(String id)
          check permissions for removeSite().
 boolean allowUnjoinSite(String id)
          check permissions for unjoin() - unjoining the site and removing all role relationships.
 boolean allowUpdateGroupMembership(String id)
          check permissions for updating a site's groups' memberships
 boolean allowUpdateSite(String id)
          check permissions for updating a site
 boolean allowUpdateSiteMembership(String id)
          check permissions for updating a site's membership
 boolean allowViewRoster(String id)
          check permissions for viewing project site participants
 int countSites(SiteService.SelectionType type, Object ofType, String criteria, Map propertyCriteria)
          Count the Site objets that meet specified criteria.
 Group findGroup(String refOrId)
          Access a Group object, given a reference string or id.
 SitePage findPage(String id)
          Access the Page that has this id, if one is defined, else return null.
 ToolConfiguration findTool(String id)
          Access the ToolConfiguration that has this id, if one is defined, else return null.
 Site getSite(String id)
          Access a site object.
 String getSiteDisplay(String id)
          Form a display of the site title and id for this site.
 List getSites(SiteService.SelectionType type, Object ofType, String criteria, Map propertyCriteria, SiteService.SortType sort, PagingPosition page)
          Access a list of Site objets that meet specified criteria.
 String getSiteSkin(String id)
          Compute the skin to use for the (optional) site specified in the id parameter.
 String getSiteSpecialId(String site)
          Extract the special id for this special site from the site id or reference.
 List getSiteTypes()
          Access a unique list of String site types for any site type defined for any site, sorted by type.
 String getSiteUserId(String site)
          Extract the user id for this user site from the site id or reference.
 Site getSiteVisit(String id)
          Access a site object for purposes of having the user visit the site - visitation permissions are in effect.
 String getSpecialSiteId(String special)
          Form the site id for this special site.
 String getUserSiteId(String userId)
          Form the site id for this user's site.
 boolean isSpecialSite(String site)
          Is this site (id or reference) a special site?
 boolean isUserSite(String site)
          Is this site (id or reference) a user site?
 void join(String id)
          Cause the current user to join the site as defined by the site's joinable flag and joiner role.
 String merge(String toSiteId, Element e, String creatorId)
          Merge the site information from the archive into the given site.
 void removeSite(Site site)
          Remove this site's information.
 void save(Site site)
          Save any updates to this site - it must be a defined site (the id must exist) and the user must have update permissions.
 void saveGroupMembership(Site site)
          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.
 void saveSiteInfo(String id, String description, String infoUrl)
          Save a site's information display fields: description and info url
 void saveSiteMembership(Site site)
          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.
 void setSiteSecurity(String siteId, Set updateUsers, Set visitUnpUsers, Set visitUsers)
          Establish the internal security for this site.
 void setUserSecurity(String userId, Set updateSites, Set visitUnpSites, Set visitSites)
          Establish the internal security for user for all sites.
 boolean siteExists(String id)
          Is this a valid site id?
 String siteGroupReference(String siteId, String groupId)
          Access the internal reference which can be used to access the site group from within the system.
 String sitePageReference(String siteId, String pageId)
          Access the internal reference which can be used to access the site page from within the system.
 String siteReference(String id)
          Access the internal reference which can be used to access the site from within the system.
 String siteToolReference(String siteId, String toolId)
          Access the internal reference which can be used to access the site tool from within the system.
 void unjoin(String id)
          Cause the current user to unjoin the site, removing all role relationships.
 
Methods inherited from interface org.sakaiproject.service.legacy.entity.EntityProducer
archive, getEntity, getEntityAuthzGroups, getEntityDescription, getEntityResourceProperties, getEntityUrl, getHttpAccess, getLabel, importEntities, merge, parseEntityReference, syncWithSiteChange, willArchiveMerge, willImport
 

Field Detail

SERVICE_NAME

public static final String SERVICE_NAME
This string can be used to find the service in the service manager.


SITE_SUBTYPE

public static final String SITE_SUBTYPE
The Entity Reference sub-type for Site references.

See Also:
Constant Field Values

GROUP_SUBTYPE

public static final String GROUP_SUBTYPE
The Entity Reference sub-type for Group references.

See Also:
Constant Field Values

PAGE_SUBTYPE

public static final String PAGE_SUBTYPE
The Entity Reference sub-type for Page references.

See Also:
Constant Field Values

TOOL_SUBTYPE

public static final String TOOL_SUBTYPE
The Entity Reference sub-type for Tool references.

See Also:
Constant Field Values

REFERENCE_ROOT

public static final String REFERENCE_ROOT
This string starts the references to resources in this service.

See Also:
Constant Field Values

SITE_VISIT

public static final String SITE_VISIT
Name for the event of visiting a site.

See Also:
Constant Field Values

SITE_VISIT_UNPUBLISHED

public static final String SITE_VISIT_UNPUBLISHED
Name for the event of visiting an unpublished site.

See Also:
Constant Field Values

SECURE_ADD_SITE

public static final String SECURE_ADD_SITE
Name for the event of adding a site.

See Also:
Constant Field Values

SECURE_ADD_USER_SITE

public static final String SECURE_ADD_USER_SITE
Name for the event of adding a user's My Workspace site.

See Also:
Constant Field Values

SECURE_REMOVE_SITE

public static final String SECURE_REMOVE_SITE
Name for the event of removing a site.

See Also:
Constant Field Values

SECURE_UPDATE_SITE

public static final String SECURE_UPDATE_SITE
Name for the event of updating a site.

See Also:
Constant Field Values

SECURE_UPDATE_SITE_MEMBERSHIP

public static final String SECURE_UPDATE_SITE_MEMBERSHIP
Name for the event of updating a site's membership.

See Also:
Constant Field Values

SECURE_UPDATE_GROUP_MEMBERSHIP

public static final String SECURE_UPDATE_GROUP_MEMBERSHIP
Name for the event of updating a site's groups' memberships.

See Also:
Constant Field Values

SECURE_VIEW_ROSTER

public static final String SECURE_VIEW_ROSTER
Name for the event of viewing project site participants.

See Also:
Constant Field Values

MAIN_CONTAINER

public static final String MAIN_CONTAINER
The name of the main container for a resource in a site (channel, calendar, etc.).

See Also:
Constant Field Values

SITE_TEMPLATE

public static final String SITE_TEMPLATE
The name of a special site that is a template for non-user sites.

See Also:
Constant Field Values

USER_SITE_TEMPLATE

public static final String USER_SITE_TEMPLATE
The name of a special site that is a template for user sites.

See Also:
Constant Field Values

SITE_ERROR

public static final String SITE_ERROR
The name of a special site that is used if the requested site is not available.

See Also:
Constant Field Values

URL_ERROR

public static final String URL_ERROR
The name of a special site that is used if the requested url is not understood.

See Also:
Constant Field Values
Method Detail

allowAccessSite

public boolean allowAccessSite(String id)
check permissions for accessing (i.e. visiting) a site

Parameters:
id - The site id.
Returns:
true if the site is allowed to access the site, false if not.

siteExists

public boolean siteExists(String id)
Is this a valid site id?

Parameters:
id - The site id string.
Returns:
True if a site with this id is defined, false if not.

getSite

public Site getSite(String id)
             throws IdUnusedException
Access a site object.

Parameters:
id - The site id string.
Returns:
A site object containing the site information.
Throws:
IdUnusedException - if not found.

getSiteVisit

public Site getSiteVisit(String id)
                  throws IdUnusedException,
                         PermissionException
Access a site object for purposes of having the user visit the site - visitation permissions are in effect.

Parameters:
id - The site id string.
Returns:
A site object containing the site information.
Throws:
IdUnusedException - if not found.
PermissionException - if the current user does not have permission to visit this site.

allowUpdateSite

public boolean allowUpdateSite(String id)
check permissions for updating a site

Parameters:
id - The site id.
Returns:
true if the site is allowed to update the site, false if not.

allowUpdateSiteMembership

public boolean allowUpdateSiteMembership(String id)
check permissions for updating a site's membership

Parameters:
id - The site id.
Returns:
true if the site is allowed to update the site's membership, false if not.

allowUpdateGroupMembership

public boolean allowUpdateGroupMembership(String id)
check permissions for updating a site's groups' memberships

Parameters:
id - The site id.
Returns:
true if the site is allowed to update the site's groups' memberships, false if not.

save

public void save(Site site)
          throws IdUnusedException,
                 PermissionException
Save any updates to this site - it must be a defined site (the id must exist) and the user must have update permissions.

Parameters:
site - The site, modified, to save.
Throws:
IdUnusedException - If the site's id is not a defined site id.
PermissionException - If the end user does not have permission to update the site.

saveSiteMembership

public void saveSiteMembership(Site site)
                        throws IdUnusedException,
                               PermissionException
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.

Parameters:
site - The site, modified, to save.
Throws:
IdUnusedException - If the site's id is not a defined site id.
PermissionException - If the end user does not have permission to update the membership of the site.

saveGroupMembership

public void saveGroupMembership(Site site)
                         throws IdUnusedException,
                                PermissionException
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.

Parameters:
site - The site, modified, to save.
Throws:
IdUnusedException - If the site's id is not a defined site id.
PermissionException - If the end user does not have permission to update the membership of the site.

saveSiteInfo

public void saveSiteInfo(String id,
                         String description,
                         String infoUrl)
                  throws IdUnusedException,
                         PermissionException
Save a site's information display fields: description and info url

Parameters:
id - The site id to update.
description - The updated description.
infoUrl - The updated infoUrl
Throws:
IdUnusedException - If the site's id is not a defined site id.
PermissionException - If the end user does not have permission to update the site.

allowAddSite

public boolean allowAddSite(String id)
check permissions for addSite().

Parameters:
id - The site id.
Returns:
true if the site is allowed to addSite(id), false if not.

addSite

public Site addSite(String id,
                    String type)
             throws IdInvalidException,
                    IdUsedException,
                    PermissionException
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.

Parameters:
id - The site id.
type - The site type.
Returns:
The new site object.
Throws:
IdInvalidException - if the site id is invalid.
IdUsedException - if the site id is already used.
PermissionException - if the current user does not have permission to add a site.

addSite

public Site addSite(String id,
                    Site other)
             throws IdInvalidException,
                    IdUsedException,
                    PermissionException
Add a new site. Will be structured just like .

Parameters:
id - The site id.
other - The site to make this site a structural copy of.
Returns:
The new site object.
Throws:
IdInvalidException - if the site id is invalid.
IdUsedException - if the site id is already used.
PermissionException - if the current user does not have permission to add a site.

allowRemoveSite

public boolean allowRemoveSite(String id)
check permissions for removeSite().

Parameters:
id - The site id.
Returns:
true if the site is allowed to removeSite(id), false if not.

removeSite

public void removeSite(Site site)
                throws PermissionException
Remove this site's information.

Throws:
PermissionException - if the current user does not have permission to remove this site.

siteReference

public String siteReference(String id)
Access the internal reference which can be used to access the site from within the system.

Parameters:
id - The site id.
Returns:
The the internal reference which can be used to access the site from within the system.

sitePageReference

public String sitePageReference(String siteId,
                                String pageId)
Access the internal reference which can be used to access the site page from within the system.

Parameters:
siteId - The site id.
pageId - The page id.
Returns:
The the internal reference which can be used to access the site page from within the system.

siteToolReference

public String siteToolReference(String siteId,
                                String toolId)
Access the internal reference which can be used to access the site tool from within the system.

Parameters:
siteId - The site id.
toolId - The tool id.
Returns:
The the internal reference which can be used to access the site tool from within the system.

siteGroupReference

public String siteGroupReference(String siteId,
                                 String groupId)
Access the internal reference which can be used to access the site group from within the system.

Parameters:
siteId - The site id.
groupId - The group id.
Returns:
The the internal reference which can be used to access the site group from within the system.

isUserSite

public boolean isUserSite(String site)
Is this site (id or reference) a user site?

Parameters:
site - The site id or reference.
Returns:
true if this is a user site, false if not.

getSiteUserId

public String getSiteUserId(String site)
Extract the user id for this user site from the site id or reference.

Parameters:
site - The site id or reference.
Returns:
The user id associated with this site.

getUserSiteId

public String getUserSiteId(String userId)
Form the site id for this user's site.

Parameters:
userId - The user id.
Returns:
The site id for this user's site.

isSpecialSite

public boolean isSpecialSite(String site)
Is this site (id or reference) a special site?

Parameters:
site - The site id or reference.
Returns:
true if this is a special site, false if not.

getSiteSpecialId

public String getSiteSpecialId(String site)
Extract the special id for this special site from the site id or reference.

Parameters:
site - The site id or reference.
Returns:
The special id associated with this site.

getSpecialSiteId

public String getSpecialSiteId(String special)
Form the site id for this special site.

Parameters:
special - The special id.
Returns:
The site id for this user's site.

getSiteDisplay

public String getSiteDisplay(String id)
Form a display of the site title and id for this site.

Parameters:
id - The site id.
Returns:
A display of the site title and id for this site.

findTool

public ToolConfiguration findTool(String id)
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.

Parameters:
id - The id of the tool.
Returns:
The ToolConfiguration that has this id, if one is defined, else return null.

findPage

public SitePage findPage(String id)
Access the Page that has this id, if one is defined, else return null. The page may be on any Site.

Parameters:
id - The id of the page.
Returns:
The SitePage that has this id, if one is defined, else return null.

allowViewRoster

public boolean allowViewRoster(String id)
check permissions for viewing project site participants

Parameters:
id - The site id.
Returns:
true if the site is allowed to addSite(id), false if not.

join

public void join(String id)
          throws IdUnusedException,
                 PermissionException
Cause the current user to join the site as defined by the site's joinable flag and joiner role.

Parameters:
id - The site id.
Throws:
IdUnusedException - if the id is not a valid site id.
PermissionException - if the current user does not have permission to join this site.
InUseException - if the site is otherwise being edited.

allowUnjoinSite

public boolean allowUnjoinSite(String id)
check permissions for unjoin() - unjoining the site and removing all role relationships.

Parameters:
id - The site id.
Returns:
true if the user is allowed to unjoin(id), false if not.

unjoin

public void unjoin(String id)
            throws IdUnusedException,
                   PermissionException
Cause the current user to unjoin the site, removing all role relationships.

Parameters:
id - The site id.
Throws:
IdUnusedException - if the id is not a valid site id.
PermissionException - if the current user does not have permission to unjoin this site.
InUseException - if the site is otherwise being edited.

getSiteSkin

public String getSiteSkin(String id)
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.

Parameters:
id - The (optional) site id.
Returns:
A skin to use for this site.

getSiteTypes

public List getSiteTypes()
Access a unique list of String site types for any site type defined for any site, sorted by type.

Returns:
A list (String) of all used site types.

getSites

public List getSites(SiteService.SelectionType type,
                     Object ofType,
                     String criteria,
                     Map propertyCriteria,
                     SiteService.SortType sort,
                     PagingPosition page)
Access a list of Site objets that meet specified criteria.

Parameters:
type - The SelectionType specifying what sort of selection is intended.
ofType - 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.
criteria - Additional selection criteria: sites returned will match this string somewhere in their id, title, description, or skin.
propertyCriteria - 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).
sort - A SortType indicating the desired sort. For no sort, set to SortType.NONE.
page - The PagePosition subset of items to return.
Returns:
The List (Site) of Site objets that meet specified criteria.

countSites

public int countSites(SiteService.SelectionType type,
                      Object ofType,
                      String criteria,
                      Map propertyCriteria)
Count the Site objets that meet specified criteria.

Parameters:
type - The SelectionType specifying what sort of selection is intended.
ofType - 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.
criteria - Additional selection criteria: sits returned will match this string somewhere in their id, title, description, or skin.
propertyCriteria - 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).
Returns:
The count of Site objets that meet specified criteria.

setSiteSecurity

public void setSiteSecurity(String siteId,
                            Set updateUsers,
                            Set visitUnpUsers,
                            Set visitUsers)
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.

Parameters:
siteId - The id of the site.
updateUsers - The set of String User Ids who have update access.
visitUnpUsers - The set of String User Ids who have visit unpublished access.
visitUsers - The set of String User Ids who have visit access.

setUserSecurity

public void setUserSecurity(String userId,
                            Set updateSites,
                            Set visitUnpSites,
                            Set visitSites)
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.

Parameters:
userId - The id of the user.
updateSites - The set of String site ids where the user has update access.
visitUnpSites - The set of String site ids where the user has visit unpublished access.
visitSites - The set of String site ids where the user has visit access.

merge

public String merge(String toSiteId,
                    Element e,
                    String creatorId)
Merge the site information from the archive into the given site.

Parameters:
toSiteId - The target site id.
e - The XML DOM tree of content to merge.
creatorId - The site creator id for target site.
Returns:
A log of status messages from the archive.

findGroup

public Group findGroup(String refOrId)
Access a Group object, given a reference string or id.

Parameters:
refOrId - The group reference or id string.
Returns:
The Group object if found, or null if not.