org.sakaiproject.service.legacy.content
Interface ContentHostingService

All Superinterfaces:
EntityProducer
All Known Implementing Classes:
BaseContentService

public interface ContentHostingService
extends EntityProducer

ContentHostingService is the Interface for Sakai Content Hosting services. This service is based on WebDAV for terminology and capability, although it may be implemented using some other content management framework.

The ContentHostingService manages shared content resources and collections. A resource is a file of some media type (MIME, such as image/gif, text/html, etc), with a resource id (a URI) and properties (name value pairs), as described in WebDAV.

Resources are organized in collections. A collection is a list of resource ids, and is itself a resource with a resource id. In the spirit of WebDAV, a resource must be placed into a collection, and the containing collection must exist before the resource is added.

Resource ids used in the API with the service are relative to the root "/" collection of the service. The full URL to a resource can be accessed from the service or from a resource object.

Resources have any number of properties. A property is defined by a name, which includes an XML namespace, and a value, which is any string. Some properties are pre-defined (by the DAV: namespace), and are "live"; the value is generated by the service. Other properties are "dead", the values are maintained by the users. Properties from namespaces other than "DAV:" are accepted.

TO DO:

The ContentHostingService can be asked:

See the methods in this API for details.

Security is enforced and Usage Events are generated when there are these accesses:

Version:
$Revision: 6409 $
Author:
University of Michigan, Sakai Software Development Team

Nested Class Summary
 
Nested classes inherited from class org.sakaiproject.service.legacy.entity.EntityProducer
EntityProducer.ChangeType
 
Field Summary
static String EVENT_DROPBOX_MAINTAIN
          Security function for those who may maintain dropboxes.
static String EVENT_DROPBOX_OWN
          Security function for those who may OWN a dropbox.
static String EVENT_RESOURCE_ADD
          Name of the event when creating a resource.
static String EVENT_RESOURCE_READ
          Name of the event when reading a resource.
static String EVENT_RESOURCE_REMOVE
          Name of the event when removing a resource.
static String EVENT_RESOURCE_WRITE
          Name of the event when writing a resource.
static String PROP_ALTERNATE_REFERENCE
          Property name on a Resource that will cause getUrl() and getRefernce() to return an alternal root reference.
static String REFERENCE_ROOT
          This string starts the references to resources in this service.
static String SERVICE_NAME
          This string can be used to find the service in the service manager.
 
Method Summary
 ContentResourceEdit addAttachmentResource(String name)
          Create a new resource as an attachment to some other resource in the system, locked for update.
 ContentResource addAttachmentResource(String name, String type, byte[] content, ResourceProperties properties)
          Create a new resource as an attachment to some other resource in the system.
 ContentResource addAttachmentResource(String name, String site, String tool, String type, byte[] content, ResourceProperties properties)
          Create a new resource as an attachment to some other resource in the system.
 ContentCollectionEdit addCollection(String id)
          Create a new collection with the given resource id, locked for update.
 ContentCollection addCollection(String id, ResourceProperties properties)
          Create a new collection with the given resource id.
 ResourceProperties addProperty(String id, String name, String value)
          Add / update a property for a collection or resource.
 ContentResourceEdit addResource(String id)
          Create a new resource with the given resource id, locked for update.
 ContentResource addResource(String id, String type, byte[] content, ResourceProperties properties, int priority)
          Create a new resource with the given resource id.
 ContentResource addResource(String name, String collectionId, int limit, String type, byte[] content, ResourceProperties properties, int priority)
          Create a new resource with the given resource name used as a resource id within the specified collection or (if that id is already in use) with a resource id based on a variation on the name to achieve a unique id, provided a unique id can be found before a limit is reached on the number of attempts to achieve uniqueness.
 boolean allowAddAttachmentResource()
          check permissions for addAttachmentResource().
 boolean allowAddCollection(String id)
          check permissions for addCollection().
 boolean allowAddProperty(String id)
          check permissions for addProperty().
 boolean allowAddResource(String id)
          check permissions for addResource().
 boolean allowCopy(String id, String new_id)
          check permissions for copy().
 boolean allowGetCollection(String id)
          Check permissions for getCollection().
 boolean allowGetProperties(String id)
          check permissions for getProperties().
 boolean allowGetResource(String id)
          check permissions for getResource().
 boolean allowRemoveCollection(String id)
          check permissions for removeCollection().
 boolean allowRemoveProperty(String id)
          check permissions for removeProperty().
 boolean allowRemoveResource(String id)
          check permissions for removeResource().
 boolean allowRename(String id, String new_id)
          check permissions for rename().
 boolean allowUpdateCollection(String id)
          check permissions for editCollection()
 boolean allowUpdateResource(String id)
          check permissions for updateResource().
 String archiveResources(List resources, Document doc, Stack stack, String archivePath)
          Archive the specified list of resources.
 void cancelCollection(ContentCollectionEdit edit)
          Cancel the changes made object, and release the lock.
 void cancelResource(ContentResourceEdit edit)
          Cancel the changes made object, and release the lock.
 void checkCollection(String id)
          Check access to the collection with this local resource id.
 void checkResource(String id)
          Check access to the resource with this local resource id.
 void commitCollection(ContentCollectionEdit edit)
          Commit the changes made, and release the lock.
 void commitResource(ContentResourceEdit edit)
          Commit the changes made, and release the lock.
 void commitResource(ContentResourceEdit edit, int priority)
          Commit the changes made, and release the lock.
 boolean containsLockedNode(String id)
          Returns true if this Collection or any of its contents has a lock.
 String copy(String id, String new_id)
          Copy a resource.
 String copyIntoFolder(String id, String folder_id)
          Copy a collection or resource from one location to another.
 void createDropboxCollection()
          Create the current site's dropbox collection and one for each qualified user that the current user can make.
 void createDropboxCollection(String siteId)
          Create the site's dropbox collection and one for each qualified user that the current user can make.
 ContentCollectionEdit editCollection(String id)
          Access the collection with this local resource id, locked for update.
 ContentResourceEdit editResource(String id)
          Access the resource with this resource id, locked for update.
 void eliminateDuplicates(Collection resourceIds)
          Eliminate from the collection any duplicates as well as any items that are contained within another item whose resource-id is in the collection.
 List findResources(String type, String primaryMimeType, String subMimeType)
          Find the resources this user has read access to from all worksites of the appropriate type.
 List getAllResources(String id)
          Access a List of all the ContentResource objects in this path (and below) which the current user has access.
 ContentCollection getCollection(String id)
          Access the collection with this local resource id.
 Map getCollectionMap()
          Return a map of Worksite collections roots that the user has access to.
 int getCollectionSize(String id)
          Count the number of (recursive) children for a given id. examples: With a nested collection structure exactly like this: /a /a/b /a/b/1 /a/b/2 getCollectionSize(/a) returns 3 (due to these three children: /a/b /a/b/1 /a/b/2) getCollectionSize(/a/b) returns 2 (due to these two children: /a/b/1 /a/b/2) getCollectionSize(/a/b/1) returns 0 (nothing falls below this collection)
 String getContainingCollectionId(String id)
          Access the resource id of the collection which contains this collection or resource.
 int getDepth(String resourceId, String baseCollectionId)
          Get the depth of the resource/collection object in the hireachy based on the given collection id
 String getDropboxCollection()
          Access the default dropbox collection id for the current request.
 String getDropboxCollection(String siteId)
          Access the default dropbox collection id for the current request.
 String getDropboxDisplayName()
          Access the default dropbox collection display name for the current request.
 String getDropboxDisplayName(String siteId)
          Access the default dropbox collection display name for the site.
 Collection getLocks(String id)
          Gets all locks set on the resource with this local resource id.
 ResourceProperties getProperties(String id)
          Access the properties of a resource with this resource id, either collection or resource.
 String getReference(String id)
          Access the internal reference from a resource id.
 ContentResource getResource(String id)
          Access the resource with this resource id.
 String getSiteCollection(String siteId)
          Return the collection id of the root collection for this site id.
 String getUrl(String id)
          Access the resource URL from a resource id.
 String getUrl(String id, String rootProperty)
          Access the alternate URL which can be used to access the entity.
 String getUuid(String id)
          For a given id, return its UUID (creating it if it does not already exist)
 boolean isAttachmentResource(String id)
          Check whether a resource id or collection id references an entity in the attachments collection.
 boolean isDropboxMaintainer()
          Determine whether the default dropbox collection id for this user in this site is the site's entire dropbox collection or just the current user's collection within the site's dropbox.
 boolean isDropboxMaintainer(String siteId)
          Determine whether the default dropbox collection id for this user in some site is the site's entire dropbox collection or just the current user's collection within the site's dropbox.
 boolean isInheritingPubView(String id)
          Does this resource inherit public view by having it set in a containing folder (not counting it's own setting)?
 boolean isLocked(String id)
          Convenience method to determine whether any locks exist for the Resource or Collection with the given local resource id
 boolean isPubView(String id)
          Does this resource support public view?
 boolean isRootCollection(String id)
          Test if this id (reference, or URL) refers to the root collection.
 void lockObject(String id, String lockId, String subject, boolean system)
          Locks an object (resource or collection) with specified local resource id.
 String moveIntoFolder(String id, String folder_id)
          Move a resource or collection to a (different) folder.
 ResourcePropertiesEdit newResourceProperties()
          Construct a stand-alone, not associated with any particular resource, ResourceProperties object.
 void removeAllLocks(String id)
          Convenience method that permanently removes any lock associated with qualifier
 void removeCollection(ContentCollectionEdit edit)
          Remove just a collection.
 void removeCollection(String id)
          Remove a collection and all members of the collection, internal or deeper.
 void removeLock(String id, String lockId)
          Removes lock with given Id from object (resource or collection) specified by this local resource id.
 ResourceProperties removeProperty(String id, String name)
          Remove a property from a collection or resource.
 void removeResource(ContentResourceEdit edit)
          Remove a resource that is locked for update.
 void removeResource(String id)
          Remove a resource.
 String rename(String id, String new_id)
          Rename a resource or collection.
 String resolveUuid(String uuid)
          For a given UUID, attempt to lookup and return the corresponding id (URI)
 void setPubView(String id, boolean pubview)
          Set this resource or collection to the pubview setting.
 void setUuid(String id, String uuid)
           
 ContentResource updateResource(String id, String type, byte[] content)
          Update the body and or content type of an existing resource with the given resource id.
 
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.


REFERENCE_ROOT

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

See Also:
Constant Field Values

EVENT_RESOURCE_ADD

public static final String EVENT_RESOURCE_ADD
Name of the event when creating a resource.

See Also:
Constant Field Values

EVENT_RESOURCE_READ

public static final String EVENT_RESOURCE_READ
Name of the event when reading a resource.

See Also:
Constant Field Values

EVENT_RESOURCE_WRITE

public static final String EVENT_RESOURCE_WRITE
Name of the event when writing a resource.

See Also:
Constant Field Values

EVENT_RESOURCE_REMOVE

public static final String EVENT_RESOURCE_REMOVE
Name of the event when removing a resource.

See Also:
Constant Field Values

EVENT_DROPBOX_OWN

public static final String EVENT_DROPBOX_OWN
Security function for those who may OWN a dropbox.

See Also:
Constant Field Values

EVENT_DROPBOX_MAINTAIN

public static final String EVENT_DROPBOX_MAINTAIN
Security function for those who may maintain dropboxes.

See Also:
Constant Field Values

PROP_ALTERNATE_REFERENCE

public static final String PROP_ALTERNATE_REFERENCE
Property name on a Resource that will cause getUrl() and getRefernce() to return an alternal root reference.

See Also:
Constant Field Values
Method Detail

getUuid

public String getUuid(String id)
For a given id, return its UUID (creating it if it does not already exist)


setUuid

public void setUuid(String id,
                    String uuid)
             throws IdInvalidException
Parameters:
id - id of the resource to set the UUID for
uuid - the new UUID of the resource
Throws:
IdInvalidException - if the given resource already has a UUID set

resolveUuid

public String resolveUuid(String uuid)
For a given UUID, attempt to lookup and return the corresponding id (URI)


allowAddCollection

public boolean allowAddCollection(String id)
check permissions for addCollection().

Returns:
true if the user is allowed to addCollection(id), false if not.

addCollection

public ContentCollection addCollection(String id,
                                       ResourceProperties properties)
                                throws IdUsedException,
                                       IdInvalidException,
                                       PermissionException,
                                       InconsistentException
Create a new collection with the given resource id.

Parameters:
id - The id of the collection.
properties - A ResourceProperties object with the properties to add to the new collection.
Returns:
a new ContentCollection object.
Throws:
IdUsedException - if the id is already in use.
IdInvalidException - if the id is invalid.
PermissionException - if the user does not have permission to add a collection, or add a member to a collection.
InconsistentException - if the containing collection does not exist.

addCollection

public ContentCollectionEdit addCollection(String id)
                                    throws IdUsedException,
                                           IdInvalidException,
                                           PermissionException,
                                           InconsistentException
Create a new collection with the given resource id, locked for update. Must commitCollection() to make official, or cancelCollection() when done!

Parameters:
id - The id of the collection.
Returns:
a new ContentCollection object.
Throws:
IdUsedException - if the id is already in use.
IdInvalidException - if the id is invalid.
PermissionException - if the user does not have permission to add a collection, or add a member to a collection.
InconsistentException - if the containing collection does not exist.

allowGetCollection

public boolean allowGetCollection(String id)
Check permissions for getCollection().

Parameters:
id - The id of the collection.
Returns:
true if the user is allowed to getCollection(id), false if not.

checkCollection

public void checkCollection(String id)
                     throws IdUnusedException,
                            TypeException,
                            PermissionException
Check access to the collection with this local resource id.

Parameters:
id - The id of the collection.
Throws:
IdUnusedException - if the id does not exist.
TypeException - if the resource exists but is not a collection.
PermissionException - if the user does not have permissions to see this collection (or read through containing collections).

getCollection

public ContentCollection getCollection(String id)
                                throws IdUnusedException,
                                       TypeException,
                                       PermissionException
Access the collection with this local resource id. The collection internal members and properties are accessible from the returned Collection object.

Parameters:
id - The id of the collection.
Returns:
The ContentCollection object found.
Throws:
IdUnusedException - if the id does not exist.
TypeException - if the resource exists but is not a collection.
PermissionException - if the user does not have permissions to see this collection (or read through containing collections).

getCollectionSize

public int getCollectionSize(String id)
                      throws IdUnusedException,
                             TypeException,
                             PermissionException
Count the number of (recursive) children for a given id. examples: With a nested collection structure exactly like this: /a /a/b /a/b/1 /a/b/2 getCollectionSize(/a) returns 3 (due to these three children: /a/b /a/b/1 /a/b/2) getCollectionSize(/a/b) returns 2 (due to these two children: /a/b/1 /a/b/2) getCollectionSize(/a/b/1) returns 0 (nothing falls below this collection)

Parameters:
id - The id of the collection.
Returns:
The number of internal members
Throws:
IdUnusedException - if the id does not exist.
TypeException - if the resource exists but is not a collection.
PermissionException - if the user does not have permissions to see this collection (or read through containing collections).

getAllResources

public List getAllResources(String id)
Access a List of all the ContentResource objects in this path (and below) which the current user has access.

Parameters:
id - A collection id.
Returns:
a List of the ContentResource objects.

allowUpdateCollection

public boolean allowUpdateCollection(String id)
check permissions for editCollection()

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

editCollection

public ContentCollectionEdit editCollection(String id)
                                     throws IdUnusedException,
                                            TypeException,
                                            PermissionException,
                                            InUseException
Access the collection with this local resource id, locked for update. Must commitCollection() to make official, or cancelCollection() when done! The collection internal members and properties are accessible from the returned Collection object.

Parameters:
id - The id of the collection.
Returns:
The ContentCollection object found.
Throws:
IdUnusedException - if the id does not exist.
TypeException - if the resource exists but is not a collection.
PermissionException - if the user does not have permissions to see this collection (or read through containing collections).
InUseException - if the Collection is locked by someone else.

allowRemoveCollection

public boolean allowRemoveCollection(String id)
check permissions for removeCollection().

Parameters:
id - The id of the collection.
Returns:
true if the user is allowed to removeCollection(id), false if not.

removeCollection

public void removeCollection(String id)
                      throws IdUnusedException,
                             TypeException,
                             PermissionException,
                             InUseException,
                             ServerOverloadException
Remove a collection and all members of the collection, internal or deeper.

Parameters:
id - The id of the collection.
Throws:
IdUnusedException - if the id does not exist.
TypeException - if the resource exists but is not a collection.
PermissionException - if the user does not have permissions to remove this collection, read through any containing
InUseException - if the collection or a contained member is locked by someone else. collections, or remove any members of the collection.
ServerOverloadException - if the server is configured to write the resource body to the filesystem and an attempt to access the resource body of any collection member fails.

removeCollection

public void removeCollection(ContentCollectionEdit edit)
                      throws TypeException,
                             PermissionException,
                             InconsistentException,
                             ServerOverloadException
Remove just a collection. It must be empty.

Throws:
TypeException - if the resource exists but is not a collection.
PermissionException - if the user does not have permissions to remove this collection, read through any containing
InconsistentException - if the collection has members, so that the removal would leave things in an inconsistent state.
ServerOverloadException - if the server is configured to write the resource body to the filesystem and an attempt to access the resource body of any collection member fails.

commitCollection

public void commitCollection(ContentCollectionEdit edit)
Commit the changes made, and release the lock. The Object is disabled, and not to be used after this call.

Parameters:
edit - The ContentCollectionEdit object to commit.

cancelCollection

public void cancelCollection(ContentCollectionEdit edit)
Cancel the changes made object, and release the lock. The Object is disabled, and not to be used after this call.

Parameters:
edit - The ContentCollectionEdit object to commit.

allowAddResource

public boolean allowAddResource(String id)
check permissions for addResource().

Parameters:
id - The id of the new resource.
Returns:
true if the user is allowed to addResource(id), false if not.

addResource

public ContentResource addResource(String id,
                                   String type,
                                   byte[] content,
                                   ResourceProperties properties,
                                   int priority)
                            throws PermissionException,
                                   IdUsedException,
                                   IdInvalidException,
                                   InconsistentException,
                                   OverQuotaException,
                                   ServerOverloadException
Create a new resource with the given resource id.

Parameters:
id - The id of the new resource.
type - The mime type string of the resource.
content - An array containing the bytes of the resource's content.
properties - A ResourceProperties object with the properties to add to the new resource.
priority - The notification priority for this commit.
Returns:
a new ContentResource object.
Throws:
PermissionException - if the user does not have permission to add a resource to the containing collection.
IdUsedException - if the resource id is already in use.
IdInvalidException - if the resource id is invalid.
InconsistentException - if the containing collection does not exist.
OverQuotaException - if this would result in being over quota.
ServerOverloadException - if the server is configured to write the resource body to the filesystem and the save fails.

addResource

public ContentResource addResource(String name,
                                   String collectionId,
                                   int limit,
                                   String type,
                                   byte[] content,
                                   ResourceProperties properties,
                                   int priority)
                            throws PermissionException,
                                   IdUniquenessException,
                                   IdLengthException,
                                   IdInvalidException,
                                   InconsistentException,
                                   IdLengthException,
                                   OverQuotaException,
                                   ServerOverloadException
Create a new resource with the given resource name used as a resource id within the specified collection or (if that id is already in use) with a resource id based on a variation on the name to achieve a unique id, provided a unique id can be found before a limit is reached on the number of attempts to achieve uniqueness.

Parameters:
name - The name of the new resource (such as a filename).
collectionId - The id of the collection to which the resource should be added.
limit - The maximum number of attempts at finding a unique id based on the given id.
type - The mime type string of the resource.
content - An array containing the bytes of the resource's content.
properties - A ResourceProperties object with the properties to add to the new resource.
priority - The notification priority for this commit.
Returns:
a new ContentResource object.
Throws:
PermissionException - if the user does not have permission to add a resource to the containing collection.
IdUniquenessException - if a unique resource id cannot be found before the limit on the number of attempts is reached.
IdLengthException - if the resource id exceeds the maximum number of characters for a valid resource id.
IdInvalidException - if the resource id is invalid.
InconsistentException - if the containing collection does not exist.
OverQuotaException - if this would result in being over quota.
ServerOverloadException - if the server is configured to write the resource body to the filesystem and the save fails.

addResource

public ContentResourceEdit addResource(String id)
                                throws PermissionException,
                                       IdUsedException,
                                       IdInvalidException,
                                       InconsistentException,
                                       ServerOverloadException
Create a new resource with the given resource id, locked for update. Must commitResource() to make official, or cancelResource() when done!

Parameters:
id - The id of the new resource.
Returns:
a new ContentResource object.
Throws:
PermissionException - if the user does not have permission to add a resource to the containing collection.
IdUsedException - if the resource id is already in use.
IdInvalidException - if the resource id is invalid.
InconsistentException - if the containing collection does not exist.
ServerOverloadException - if the server is configured to write the resource body to the filesystem and the save fails.

allowAddAttachmentResource

public boolean allowAddAttachmentResource()
check permissions for addAttachmentResource().

Returns:
true if the user is allowed to addAttachmentResource(), false if not.

isAttachmentResource

public boolean isAttachmentResource(String id)
Check whether a resource id or collection id references an entity in the attachments collection. This method makes no guarantees that a resource actually exists with this id.

Parameters:
id - Assumed to be a valid resource id or collection id.
Returns:
true if the id (assuming it is a valid id for an existing resource or collection) references an entity in the hidden attachments area created through one of this class's addAttachmentResource methods.

addAttachmentResource

public ContentResource addAttachmentResource(String name,
                                             String type,
                                             byte[] content,
                                             ResourceProperties properties)
                                      throws IdInvalidException,
                                             InconsistentException,
                                             IdUsedException,
                                             PermissionException,
                                             OverQuotaException,
                                             ServerOverloadException
Create a new resource as an attachment to some other resource in the system. The new resource will be placed into a newly created collecion in the attachment collection, with an auto-generated id, and given the specified resource name within this collection.

Parameters:
name - The name of the new resource, i.e. a partial id relative to the collection where it will live.
type - The mime type string of the resource.
content - An array containing the bytes of the resource's content.
properties - A ResourceProperties object with the properties to add to the new resource.
Returns:
a new ContentResource object.
Throws:
IdUsedException - if the resource name is already in use (not likely, as the containing collection is auto-generated!)
IdInvalidException - if the resource name is invalid.
InconsistentException - if the containing collection (or it's containing collection...) does not exist.
PermissionException - if the user does not have permission to add a collection, or add a member to a collection.
OverQuotaException - if this would result in being over quota.
ServerOverloadException - if the server is configured to write the resource body to the filesystem and the save fails.

addAttachmentResource

public ContentResource addAttachmentResource(String name,
                                             String site,
                                             String tool,
                                             String type,
                                             byte[] content,
                                             ResourceProperties properties)
                                      throws IdInvalidException,
                                             InconsistentException,
                                             IdUsedException,
                                             PermissionException,
                                             OverQuotaException,
                                             ServerOverloadException
Create a new resource as an attachment to some other resource in the system. The new resource will be placed into a newly created collection in the site collection within the attachment collection. The new collection will have an auto-generated id, and it will be given the specified resource name within the site collection.

Parameters:
name - The name of the new resource, i.e. a partial id relative to the collection where it will live.
site - The string identifier for the site where the attachment is being added within the attachments collection.
tool - The display-name for the tool through which the attachment is being added within the site's attachments collection.
type - The mime type string of the resource.
content - An array containing the bytes of the resource's content.
properties - A ResourceProperties object with the properties to add to the new resource.
Returns:
a new ContentResource object.
Throws:
IdUsedException - if the resource name is already in use (not likely, as the containing collection is auto-generated!)
IdInvalidException - if the resource name is invalid.
InconsistentException - if the containing collection (or it's containing collection...) does not exist.
PermissionException - if the user does not have permission to add a collection, or add a member to a collection.
OverQuotaException - if this would result in being over quota.
ServerOverloadException - if the server is configured to write the resource body to the filesystem and the save fails.

addAttachmentResource

public ContentResourceEdit addAttachmentResource(String name)
                                          throws IdInvalidException,
                                                 InconsistentException,
                                                 IdUsedException,
                                                 PermissionException,
                                                 ServerOverloadException
Create a new resource as an attachment to some other resource in the system, locked for update. Must commitResource() to make official, or cancelResource() when done! The new resource will be placed into a newly created collecion in the attachment collection, with an auto-generated id, and given the specified resource name within this collection.

Parameters:
name - The name of the new resource, i.e. a partial id relative to the collection where it will live.
Returns:
a new ContentResource object.
Throws:
IdUsedException - if the resource name is already in use (not likely, as the containing collection is auto-generated!)
IdInvalidException - if the resource name is invalid.
InconsistentException - if the containing collection (or it's containing collection...) does not exist.
PermissionException - if the user does not have permission to add a collection, or add a member to a collection.
ServerOverloadException - if the server is configured to write the resource body to the filesystem and the save fails.

allowUpdateResource

public boolean allowUpdateResource(String id)
check permissions for updateResource().

Parameters:
id - The id of the new resource.
Returns:
true if the user is allowed to updateResource(id), false if not.

updateResource

public ContentResource updateResource(String id,
                                      String type,
                                      byte[] content)
                               throws PermissionException,
                                      IdUnusedException,
                                      TypeException,
                                      InUseException,
                                      OverQuotaException,
                                      ServerOverloadException
Update the body and or content type of an existing resource with the given resource id.

Parameters:
id - The id of the resource.
type - The mime type string of the resource (if null, no change).
content - An array containing the bytes of the resource's content (if null, no change).
Returns:
a new ContentResource object.
Throws:
PermissionException - if the user does not have permission to add a resource to the containing collection or write the resource.
IdUnusedException - if the resource id is not defined.
TypeException - if the resource is a collection.
InUseException - if the resource is locked by someone else.
OverQuotaException - if this would result in being over quota.
ServerOverloadException - if the server is configured to write the resource body to the filesystem and the save fails.

editResource

public ContentResourceEdit editResource(String id)
                                 throws PermissionException,
                                        IdUnusedException,
                                        TypeException,
                                        InUseException
Access the resource with this resource id, locked for update. For non-collection resources only. Must commitEdit() to make official, or cancelEdit() when done! The resource content and properties are accessible from the returned Resource object.

Parameters:
id - The id of the resource.
Returns:
the ContentResource object found.
Throws:
PermissionException - if the user does not have permissions to read the resource or read through any containing collection.
IdUnusedException - if the resource id is not found.
TypeException - if the resource is a collection.
InUseException - if the resource is locked by someone else.

allowGetResource

public boolean allowGetResource(String id)
check permissions for getResource().

Parameters:
id - The id of the new resource.
Returns:
true if the user is allowed to getResource(id), false if not.

checkResource

public void checkResource(String id)
                   throws PermissionException,
                          IdUnusedException,
                          TypeException
Check access to the resource with this local resource id. For non-collection resources only.

Parameters:
id - The id of the resource.
Throws:
PermissionException - if the user does not have permissions to read the resource or read through any containing collection.
IdUnusedException - if the resource id is not found.
TypeException - if the resource is a collection.

getResource

public ContentResource getResource(String id)
                            throws PermissionException,
                                   IdUnusedException,
                                   TypeException
Access the resource with this resource id. For non-collection resources only. The resource content and properties are accessible from the returned Resource object.

Parameters:
id - The id of the resource.
Returns:
the ContentResource object found.
Throws:
PermissionException - if the user does not have permissions to read the resource or read through any containing collection.
IdUnusedException - if the resource id is not found.
TypeException - if the resource is a collection.

allowRemoveResource

public boolean allowRemoveResource(String id)
check permissions for removeResource().

Parameters:
id - The id of the new resource.
Returns:
true if the user is allowed to removeResource(id), false if not.

removeResource

public void removeResource(String id)
                    throws PermissionException,
                           IdUnusedException,
                           TypeException,
                           InUseException
Remove a resource. For non-collection resources only.

Parameters:
id - The id of the resource.
Throws:
PermissionException - if the user does not have permissions to read a containing collection, or to remove this resource.
IdUnusedException - if the resource id is not found.
TypeException - if the resource is a collection.
InUseException - if the resource is locked by someone else.

removeResource

public void removeResource(ContentResourceEdit edit)
                    throws PermissionException
Remove a resource that is locked for update.

Parameters:
edit - The ContentResourceEdit object to remove.
Throws:
PermissionException - if the user does not have permissions to read a containing collection, or to remove this resource.

allowRename

public boolean allowRename(String id,
                           String new_id)
check permissions for rename().

Parameters:
id - The id of the existing resource.
Returns:
true if the user is allowed to rename(id), false if not.

rename

public String rename(String id,
                     String new_id)
              throws PermissionException,
                     IdUnusedException,
                     TypeException,
                     InUseException,
                     OverQuotaException,
                     InconsistentException,
                     IdUsedException,
                     ServerOverloadException
Rename a resource or collection.

Parameters:
id - The id of the resource or collection.
new_id - The desired id of the resource or collection.
Returns:
The full id of the resource after the rename is completed.
Throws:
PermissionException - if the user does not have permissions to read a containing collection, or to rename this resource.
IdUnusedException - if the resource id is not found.
TypeException - if the resource is a collection.
InUseException - if the resource is locked by someone else.
IdUsedException - if copied item is a collection and the new id is already in use or if the copied item is not a collection and a unique id cannot be found in some arbitrary number of attempts (@see MAXIMUM_ATTEMPTS_FOR_UNIQUENESS).
ServerOverloadException - if the server is configured to write the resource body to the filesystem and the save fails.
OverQuotaException
InconsistentException

allowCopy

public boolean allowCopy(String id,
                         String new_id)
check permissions for copy().

Parameters:
id - The id of the new resource.
new_id - The desired id of the new resource.
Returns:
true if the user is allowed to copy(id,new_id), false if not.

copy

public String copy(String id,
                   String new_id)
            throws PermissionException,
                   IdUnusedException,
                   TypeException,
                   InUseException,
                   OverQuotaException,
                   IdUsedException,
                   ServerOverloadException
Copy a resource.

Parameters:
id - The id of the resource.
new_id - The desired id of the new resource.
Returns:
The full id of the new copy of the resource.
Throws:
PermissionException - if the user does not have permissions to read a containing collection, or to remove this resource.
IdUnusedException - if the resource id is not found.
TypeException - if the resource is a collection.
InUseException - if the resource is locked by someone else.
IdUsedException - if copied item is a collection and the new id is already in use or if the copied item is not a collection and a unique id cannot be found in some arbitrary number of attempts (@see MAXIMUM_ATTEMPTS_FOR_UNIQUENESS).
ServerOverloadException - if the server is configured to write the resource body to the filesystem and the save fails.
OverQuotaException

copyIntoFolder

public String copyIntoFolder(String id,
                             String folder_id)
                      throws PermissionException,
                             IdUnusedException,
                             TypeException,
                             InUseException,
                             OverQuotaException,
                             IdUsedException,
                             ServerOverloadException,
                             InconsistentException,
                             IdLengthException,
                             IdUniquenessException
Copy a collection or resource from one location to another. Creates a new collection with an id similar to new_folder_id and recursively copies all nested collections and resources within thisCollection to the new collection.

Parameters:
id - The id of the resource.
folder_id - The id of the folder in which the copy should be created.
Returns:
The full id of the new copy of the resource.
Throws:
PermissionException - if the user does not have permissions to read a containing collection, or to remove this resource.
IdUnusedException - if the resource id is not found.
TypeException - if the resource is a collection.
InUseException - if the resource is locked by someone else.
IdLengthException - if the new id of the copied item (or any nested item) is longer than the maximum length of an id.
IdUniquenessException - if a unique id cannot be found in the new folder.
InconsistentException - if the destination folder (folder_id) is contained within the source folder (id).
IdUsedException - if a unique resource id cannot be found after some arbitrary number of attempts (@see MAXIMUM_ATTEMPTS_FOR_UNIQUENESS).
ServerOverloadException - if the server is configured to write the resource body to the filesystem and the save fails.
OverQuotaException

moveIntoFolder

public String moveIntoFolder(String id,
                             String folder_id)
                      throws PermissionException,
                             IdUnusedException,
                             TypeException,
                             InUseException,
                             OverQuotaException,
                             IdUsedException,
                             InconsistentException,
                             ServerOverloadException
Move a resource or collection to a (different) folder. This may be accomplished by renaming the resource or by recursively renaming the collection and all enclosed members (no matter how deep) to effectively change their locations. Alternatively, it may be accomplished by copying the resource and recursively copying collections from their existing collection to the new collection and ultimately deleting the original resource(s) and/or collections(s).

Parameters:
id - The id of the resource or collection to be moved.
folder_id - The id of the folder to which the resource should be moved.
Returns:
The full id of the resource after the move is completed.
Throws:
PermissionException - if the user does not have permissions to read a containing collection, or to remove this resource.
IdUnusedException - if the resource id is not found.
TypeException - if the resource is a collection.
InUseException - if the resource is locked by someone else.
InconsistentException - if the containing collection does not exist.
InconsistentException - if the destination folder (folder_id) is contained within the source folder (id).
IdUsedException - if a unique resource id cannot be found after some arbitrary number of attempts (@see MAXIMUM_ATTEMPTS_FOR_UNIQUENESS).
ServerOverloadException - if the server is configured to write the resource body to the filesystem and the save fails.
OverQuotaException

commitResource

public void commitResource(ContentResourceEdit edit)
                    throws OverQuotaException,
                           ServerOverloadException
Commit the changes made, and release the lock. The Object is disabled, and not to be used after this call.

Parameters:
edit - The ContentResourceEdit object to commit.
Throws:
OverQuotaException - if this would result in being over quota (the edit is then cancled).
ServerOverloadException - if the server is configured to write the resource body to the filesystem and the save fails.

commitResource

public void commitResource(ContentResourceEdit edit,
                           int priority)
                    throws OverQuotaException,
                           ServerOverloadException
Commit the changes made, and release the lock. The Object is disabled, and not to be used after this call.

Parameters:
edit - The ContentResourceEdit object to commit.
priority - The notification priority of this commit.
Throws:
OverQuotaException - if this would result in being over quota (the edit is then cancled).
ServerOverloadException - if the server is configured to write the resource body to the filesystem and the save fails.

cancelResource

public void cancelResource(ContentResourceEdit edit)
Cancel the changes made object, and release the lock. The Object is disabled, and not to be used after this call.

Parameters:
edit - The ContentResourceEdit object to commit.

allowGetProperties

public boolean allowGetProperties(String id)
check permissions for getProperties().

Parameters:
id - The id of the new resource.
Returns:
true if the user is allowed to getProperties(id), false if not.

getProperties

public ResourceProperties getProperties(String id)
                                 throws PermissionException,
                                        IdUnusedException
Access the properties of a resource with this resource id, either collection or resource.

Parameters:
id - The id of the resource.
Returns:
the ResourceProperties object for this resource.
Throws:
PermissionException - if the user does not have permissions to read properties on this object or read through containing collections.
IdUnusedException - if the resource id is not found.

allowAddProperty

public boolean allowAddProperty(String id)
check permissions for addProperty().

Parameters:
id - The id of the new resource.
Returns:
true if the user is allowed to addProperty(id), false if not.

addProperty

public ResourceProperties addProperty(String id,
                                      String name,
                                      String value)
                               throws PermissionException,
                                      IdUnusedException,
                                      TypeException,
                                      InUseException,
                                      ServerOverloadException
Add / update a property for a collection or resource.

Parameters:
id - The id of the resource.
name - The properties name to add or update
value - The new value for the property.
Returns:
the ResourceProperties object for this resource.
Throws:
PermissionException - if the user does not have premissions to write properties on this object or read through containing collections.
IdUnusedException - if the resource id is not found.
TypeException - if any property requested cannot be set (it may be live).
InUseException - if the resource is locked by someone else.
ServerOverloadException - if the server is configured to write the resource body to the filesystem and the save fails.

allowRemoveProperty

public boolean allowRemoveProperty(String id)
check permissions for removeProperty().

Parameters:
id - The id of the new resource.
Returns:
true if the user is allowed to removeProperty(id), false if not.

removeProperty

public ResourceProperties removeProperty(String id,
                                         String name)
                                  throws PermissionException,
                                         IdUnusedException,
                                         TypeException,
                                         InUseException,
                                         ServerOverloadException
Remove a property from a collection or resource.

Parameters:
id - The id of the resource.
name - The property name to be removed from the resource.
Returns:
the ResourceProperties object for this resource.
Throws:
PermissionException - if the user does not have premissions to write properties on this object or read through containing collections.
IdUnusedException - if the resource id is not found.
TypeException - if the property named cannot be removed.
InUseException - if the resource is locked by someone else.
ServerOverloadException - if the server is configured to write the resource body to the filesystem and the save fails.

getUrl

public String getUrl(String id)
Access the resource URL from a resource id.

Parameters:
id - The resource id.
Returns:
The resource URL.

getUrl

public String getUrl(String id,
                     String rootProperty)
Access the alternate URL which can be used to access the entity.

Parameters:
id - The resource id.
rootProperty - The name of the entity property whose value controls which alternate reference URL is requested. If null, the native 'raw' URL is requested.
Returns:
The resource URL.

getReference

public String getReference(String id)
Access the internal reference from a resource id.

Parameters:
id - The resource id.
Returns:
The internal reference from a resource id.

getContainingCollectionId

public String getContainingCollectionId(String id)
Access the resource id of the collection which contains this collection or resource.

Parameters:
id - The resource id (reference, or URL) of the ContentCollection or ContentResource
Returns:
the resource id (reference, or URL, depending on the id parameter) of the collection which contains this resource.

getDepth

public int getDepth(String resourceId,
                    String baseCollectionId)
Get the depth of the resource/collection object in the hireachy based on the given collection id

Parameters:
resourceId - The Id of the resource/collection object to be tested
baseCollectionId - The Id of the collection as the relative root level
Returns:
the integer value reflecting the relative hierarchy depth of the test resource/collection object based on the given base collection level

isRootCollection

public boolean isRootCollection(String id)
Test if this id (reference, or URL) refers to the root collection.

Parameters:
id - The resource id (reference, or URL) of a ContentCollection
Returns:
true if this is the root collection

newResourceProperties

public ResourcePropertiesEdit newResourceProperties()
Construct a stand-alone, not associated with any particular resource, ResourceProperties object.

Returns:
The new ResourceProperties object.

getSiteCollection

public String getSiteCollection(String siteId)
Return the collection id of the root collection for this site id.

Parameters:
siteId - The site id.
Returns:
The collection id which is the root collection for this site.

archiveResources

public String archiveResources(List resources,
                               Document doc,
                               Stack stack,
                               String archivePath)
Archive the specified list of resources.

Parameters:
resources - A list of the resources to archive.
doc - The document to contain the xml.
stack - The stack of elements, the top of which will be the containing element of the "service.name" element.
archivePath - The path to the folder where we are writing auxilary files.
Returns:
A log of status messages from the archive.

getLocks

public Collection getLocks(String id)
Gets all locks set on the resource with this local resource id.

Parameters:
id -
Returns:

lockObject

public void lockObject(String id,
                       String lockId,
                       String subject,
                       boolean system)
Locks an object (resource or collection) with specified local resource id. Initially, the WebDAV concepts of expiration, exclusive vs shared, and inheritable are not supported; instead, all locks are exclusive. Programmatically created locks may be designated as "system" locks, in which case, users may not remove them via WebDAV lock management tools. Since only exclusive locks are permitted, a user can only lock a resource if it is not already locked; however, multiple system locks can be put in place, because system locks imply that no user is permitted to change the resource.

Parameters:
id -
lockId -
subject - - the reason for this lock e.g. "being graded"
system - - when true, it is not possible for a user to remove this lock

removeLock

public void removeLock(String id,
                       String lockId)
Removes lock with given Id from object (resource or collection) specified by this local resource id. Note that other locks could exist, so it does not necessarily fully unlock the object.

Parameters:
id -
lockId -

isLocked

public boolean isLocked(String id)
Convenience method to determine whether any locks exist for the Resource or Collection with the given local resource id

Parameters:
id -
Returns:
true when there are one or more locks on the given id

containsLockedNode

public boolean containsLockedNode(String id)
Returns true if this Collection or any of its contents has a lock. It is likely much more efficient than recursively iterating through all of the contained resources.

Parameters:
id -
Returns:

removeAllLocks

public void removeAllLocks(String id)
Convenience method that permanently removes any lock associated with qualifier

Parameters:
id -

isPubView

public boolean isPubView(String id)
Does this resource support public view?

Parameters:
id - The resource id to check.
Returns:
true if this resource supports public view, false if not.

isInheritingPubView

public boolean isInheritingPubView(String id)
Does this resource inherit public view by having it set in a containing folder (not counting it's own setting)?

Parameters:
id - The resource id to check.
Returns:
true if this resource inherits public view, false if not.

setPubView

public void setPubView(String id,
                       boolean pubview)
Set this resource or collection to the pubview setting.

Parameters:
id - The resource or collection id.
pubview - The desired public view setting.

findResources

public List findResources(String type,
                          String primaryMimeType,
                          String subMimeType)
Find the resources this user has read access to from all worksites of the appropriate type.

Parameters:
type - this is the ResourceProperties.PROP_STRUCTOBJ_TYPE for stuctured objects or ResourceProperties.FILE_TYPE for file resources or null for all resources.
primaryMimeType - The primary mime type (ie. the "text" of "text/xml") This may be null to include all resources
subMimeType - The sub type (ie, the "xml" of "text/xml") This may be null to include all resources of the primary mime type if specified.
Returns:
List of ContentResource objects that match the search criteria

getCollectionMap

public Map getCollectionMap()
Return a map of Worksite collections roots that the user has access to.

Returns:
Map of worksite title (String) to worksite resource root id (String)

eliminateDuplicates

public void eliminateDuplicates(Collection resourceIds)
Eliminate from the collection any duplicates as well as any items that are contained within another item whose resource-id is in the collection.

Parameters:
resourceIds - A collection of strings (possibly empty) identifying items and/or collections.

createDropboxCollection

public void createDropboxCollection()
Create the current site's dropbox collection and one for each qualified user that the current user can make.


createDropboxCollection

public void createDropboxCollection(String siteId)
Create the site's dropbox collection and one for each qualified user that the current user can make.

Parameters:
siteId - the Site id.

getDropboxCollection

public String getDropboxCollection()
Access the default dropbox collection id for the current request.
If the current user is a dropbox maintainer for the current site, return the site's dropbox area.
Otherwis return the current user's collection within the site's dropbox.

Returns:
The default dropbox collection id for the current request.

getDropboxCollection

public String getDropboxCollection(String siteId)
Access the default dropbox collection id for the current request.
If the current user is a dropbox maintainer for the current site, return the site's dropbox area.
Otherwis return the current user's collection within the site's dropbox.

Parameters:
siteId - The site id.
Returns:
The default dropbox collection id for the site.

isDropboxMaintainer

public boolean isDropboxMaintainer()
Determine whether the default dropbox collection id for this user in this site is the site's entire dropbox collection or just the current user's collection within the site's dropbox.

Returns:
True if user sees all dropboxes in the site, false otherwise.

isDropboxMaintainer

public boolean isDropboxMaintainer(String siteId)
Determine whether the default dropbox collection id for this user in some site is the site's entire dropbox collection or just the current user's collection within the site's dropbox.

Returns:
True if user sees all dropboxes in the site, false otherwise.

getDropboxDisplayName

public String getDropboxDisplayName()
Access the default dropbox collection display name for the current request. If the current user has permission to modify the site's dropbox collection, this is returned. Otherwise, the current user's collection within the site's dropbox is returned.

Returns:
The default dropbox collection display name for the current request.

getDropboxDisplayName

public String getDropboxDisplayName(String siteId)
Access the default dropbox collection display name for the site. If the current user has permission to modify the site's dropbox collection, this is returned. Otherwise, the current user's collection within the site's dropbox is returned.

Parameters:
siteId - the Site id.
Returns:
The default dropbox collection display name for the site.