ContentHostingService API

The ContentHostingService is the interface for Sakai Content Hosting services. This service manages shared content resources and collections based on WebDAV terminology and capabilities.

Overview

Package: org.sakaiproject.content.api The ContentHostingService provides:

File and resource storage and retrieval
Collection (folder) management
Access control and permissions
Resource properties and metadata
Attachment management
Quota management
File versioning support

Key Concepts

Resource: A file with content, MIME type, properties, and a resource ID (URI)
Collection: A folder containing resources and other collections
Properties: Name-value pairs (DAV: namespace for live properties, custom namespaces for dead properties)
Reference: Internal URI for accessing resources (e.g., /content/group/site-id/folder/file.pdf)

Constants

APPLICATION_ID

String

default:"sakai:content"

Application identifier for the content service

REFERENCE_ROOT

String

default:"/content"

Root path for content resource references

ATTACHMENTS_COLLECTION

String

default:"/attachment/"

Collection ID for attachments

COLLECTION_USER

String

default:"/user/"

Collection ID for user sites

COLLECTION_SITE

String

default:"/group/"

Collection ID for non-user sites

COLLECTION_DROPBOX

String

default:"/group-user/"

Root collection for dropboxes

MAXIMUM_RESOURCE_ID_LENGTH

int

default:"247"

Maximum characters in a resource ID

Security Functions

AUTH_RESOURCE_ADD

String

default:"content.new"

Permission to create a resource

AUTH_RESOURCE_READ

String

default:"content.read"

Permission to read a resource

AUTH_RESOURCE_WRITE_ANY

String

default:"content.revise.any"

Permission to write any resource

AUTH_RESOURCE_WRITE_OWN

String

default:"content.revise.own"

Permission to write own resource

AUTH_RESOURCE_REMOVE_ANY

String

default:"content.delete.any"

Permission to remove any resource

AUTH_RESOURCE_REMOVE_OWN

String

default:"content.delete.own"

Permission to remove own resource

AUTH_RESOURCE_HIDDEN

String

default:"content.hidden"

Permission to access hidden entities

AUTH_DROPBOX_OWN

String

default:"dropbox.own"

Permission to own a dropbox

AUTH_DROPBOX_MAINTAIN

String

default:"dropbox.maintain"

Permission to maintain dropboxes

Events

EVENT_RESOURCE_ADD

String

default:"content.new"

Event when creating a resource

EVENT_RESOURCE_READ

String

default:"content.read"

Event when reading a resource

EVENT_RESOURCE_WRITE

String

default:"content.revise"

Event when writing a resource

EVENT_RESOURCE_REMOVE

String

default:"content.delete"

Event when removing a resource

EVENT_RESOURCE_AVAILABLE

String

default:"content.available"

Event when a resource becomes available

Collection Methods

Collection Access

getCollection

ContentCollection getCollection(String id) 
    throws IdUnusedException, TypeException, PermissionException

Access a collection with this resource ID.

String

required

The collection ID

ContentCollection

The ContentCollection object

Throws:

IdUnusedException - if the ID does not exist
TypeException - if the resource exists but is not a collection
PermissionException - if user lacks permissions

Example:

try {
    ContentCollection collection = contentHostingService.getCollection("/group/site-id/folder/");
    List<String> members = collection.getMembers();
    for (String memberId : members) {
        // Process each member
    }
} catch (IdUnusedException e) {
    // Collection not found
}

checkCollection

void checkCollection(String id) 
    throws IdUnusedException, TypeException, PermissionException

Check access to a collection without retrieving it.

String

required

The collection ID

Throws:

IdUnusedException - if the ID does not exist
TypeException - if not a collection
PermissionException - if user lacks permissions

getAllResources

List<ContentResource> getAllResources(String id)

Access all ContentResource objects in this path and below.

String

required

A collection ID (cannot be root collection)

List<ContentResource>

List of all resources the user has access to

Example:

List<ContentResource> resources = contentHostingService.getAllResources("/group/site-id/");
for (ContentResource resource : resources) {
    System.out.println(resource.getUrl() + " - " + resource.getContentLength() + " bytes");
}

getCollectionSize

int getCollectionSize(String id) 
    throws IdUnusedException, TypeException, PermissionException

Count the number of recursive children for a collection.

String

required

The collection ID

int

Number of internal members (recursive)

Collection Creation

addCollection

ContentCollectionEdit addCollection(String id) 
    throws IdUsedException, IdInvalidException, PermissionException, InconsistentException

Create a new collection, locked for update. Must call commitCollection() or cancelCollection().

String

required

The ID of the collection (must end with ’/’)

ContentCollectionEdit

A new editable ContentCollection object

Throws:

IdUsedException - if the ID is already in use
IdInvalidException - if the ID is invalid
PermissionException - if user lacks permission
InconsistentException - if containing collection does not exist

Example:

try {
    ContentCollectionEdit collection = contentHostingService.addCollection("/group/site-id/new-folder/");
    ResourcePropertiesEdit props = collection.getPropertiesEdit();
    props.addProperty(ResourceProperties.PROP_DISPLAY_NAME, "New Folder");
    contentHostingService.commitCollection(collection);
} catch (IdUsedException e) {
    // Collection already exists
}

commitCollection

void commitCollection(ContentCollectionEdit edit)

Commit changes to a ContentCollectionEdit and release the lock.

edit

ContentCollectionEdit

required

The ContentCollectionEdit object to commit

cancelCollection

void cancelCollection(ContentCollectionEdit edit)

Cancel changes to a ContentCollectionEdit and release the lock.

edit

ContentCollectionEdit

required

The ContentCollectionEdit object to cancel

Collection Modification

editCollection

ContentCollectionEdit editCollection(String id) 
    throws IdUnusedException, TypeException, PermissionException, InUseException

Get a collection locked for update.

String

required

The collection ID

ContentCollectionEdit

The collection locked for editing

Throws:

IdUnusedException - if not found
TypeException - if not a collection
PermissionException - if user lacks permission
InUseException - if locked by someone else

Collection Removal

removeCollection

void removeCollection(String id) 
    throws IdUnusedException, TypeException, PermissionException, 
           InUseException, ServerOverloadException

Remove a collection and all its members.

String

required

The collection ID

Throws:

IdUnusedException - if not found
TypeException - if not a collection
PermissionException - if user lacks permission
InUseException - if collection or member is locked
ServerOverloadException - if filesystem write fails

Resource Methods

Resource Access

getResource

ContentResource getResource(String id) 
    throws PermissionException, IdUnusedException, TypeException

Access a resource by ID.

String

required

The resource ID

ContentResource

The ContentResource object

Example:

try {
    ContentResource resource = contentHostingService.getResource("/group/site-id/file.pdf");
    
    // Get metadata
    String contentType = resource.getContentType();
    long size = resource.getContentLength();
    String url = resource.getUrl();
    
    // Get content
    byte[] content = resource.getContent();
    InputStream stream = resource.streamContent();
    
    // Get properties
    ResourceProperties props = resource.getProperties();
    String displayName = props.getProperty(ResourceProperties.PROP_DISPLAY_NAME);
} catch (IdUnusedException e) {
    // Resource not found
}

Resource Creation

addResource (Simple)

ContentResourceEdit addResource(String id) 
    throws PermissionException, IdUsedException, IdInvalidException, 
           InconsistentException, ServerOverloadException

Create a new resource, locked for update. Must call commitResource() or cancelResource().

String

required

The resource ID

ContentResourceEdit

A new editable ContentResource object

Example:

try {
    ContentResourceEdit resource = contentHostingService.addResource("/group/site-id/document.pdf");
    
    // Set content type
    resource.setContentType("application/pdf");
    
    // Set content
    resource.setContent(fileBytes);
    
    // Set properties
    ResourcePropertiesEdit props = resource.getPropertiesEdit();
    props.addProperty(ResourceProperties.PROP_DISPLAY_NAME, "Course Document");
    props.addProperty(ResourceProperties.PROP_DESCRIPTION, "Important reading material");
    
    // Commit
    contentHostingService.commitResource(resource);
} catch (OverQuotaException e) {
    // Would exceed quota
}

addResource (Complete)

ContentResource addResource(String id, String type, InputStream content, 
                            ResourceProperties properties, int priority)
    throws PermissionException, IdUsedException, IdInvalidException, 
           InconsistentException, OverQuotaException, ServerOverloadException

Create a new resource in one operation.

String

required

The resource ID

type

String

required

The MIME type (e.g., “application/pdf”)

content

InputStream

required

Stream containing the resource content

properties

ResourceProperties

required

Properties to add to the resource

priority

int

required

Notification priority for this commit

addResource (With Groups)

ContentResource addResource(String id, String type, InputStream content,
                            ResourceProperties properties, Collection groups, int priority)
    throws PermissionException, IdUsedException, IdInvalidException,
           InconsistentException, OverQuotaException, ServerOverloadException

Create a new resource with group access control.

groups

Collection<String>

Collection of group reference strings for access control

Resource Modification

editResource

ContentResourceEdit editResource(String id)
    throws PermissionException, IdUnusedException, TypeException, InUseException

Get a resource locked for update.

String

required

The resource ID

ContentResourceEdit

The resource locked for editing

Example:

try {
    ContentResourceEdit resource = contentHostingService.editResource(resourceId);
    
    // Update content
    resource.setContent(newBytes);
    
    // Update properties
    ResourcePropertiesEdit props = resource.getPropertiesEdit();
    props.addProperty(ResourceProperties.PROP_MODIFIED_DATE, 
                     TimeService.newTime().toString());
    
    contentHostingService.commitResource(resource);
} catch (InUseException e) {
    // Resource is being edited by someone else
}

commitResource

void commitResource(ContentResourceEdit edit) 
    throws OverQuotaException, ServerOverloadException

Commit changes to a ContentResourceEdit and release the lock.

edit

ContentResourceEdit

required

The ContentResourceEdit object to commit

Throws:

OverQuotaException - if this would exceed quota
ServerOverloadException - if filesystem write fails

cancelResource

void cancelResource(ContentResourceEdit edit)

Cancel changes to a ContentResourceEdit and release the lock.

edit

ContentResourceEdit

required

The ContentResourceEdit object to cancel

Resource Removal

removeResource

void removeResource(String id)
    throws PermissionException, IdUnusedException, TypeException, InUseException

Remove a resource.

String

required

The resource ID

Throws:

PermissionException - if user lacks permission
IdUnusedException - if not found
TypeException - if not a resource
InUseException - if locked by someone else

Attachment Methods

addAttachmentResource

ContentResource addAttachmentResource(String name, String type, InputStream content,
                                     ResourceProperties properties)
    throws IdInvalidException, InconsistentException, IdUsedException,
           PermissionException, OverQuotaException, ServerOverloadException

Create a new resource as an attachment with an auto-generated ID.

name

String

required

The name of the resource (filename)

type

String

required

The MIME type

content

InputStream

required

Stream containing the content

properties

ResourceProperties

required

Properties for the resource

ContentResource

The created attachment resource

Example:

ResourcePropertiesEdit props = contentHostingService.newResourceProperties();
props.addProperty(ResourceProperties.PROP_DISPLAY_NAME, "attachment.pdf");

ContentResource attachment = contentHostingService.addAttachmentResource(
    "attachment.pdf",
    "application/pdf",
    fileInputStream,
    props
);

String attachmentId = attachment.getId();

isAttachmentResource

boolean isAttachmentResource(String id)

Check if a resource ID references an entity in the attachments collection.

String

required

The resource or collection ID

boolean

true if this is an attachment resource

UUID Methods

getUuid

String getUuid(String id)

For a given ID, return its UUID (creating it if it doesn’t exist).

String

required

The resource ID

String

The UUID for this resource

resolveUuid

String resolveUuid(String uuid)

For a given UUID, lookup and return the corresponding ID.

uuid

String

required

The UUID to resolve

String

The resource ID, or null if not found

Permission Check Methods

allowGetCollection

boolean allowGetCollection(String id)

Check if user is allowed to get a collection.

String

required

The collection ID

boolean

true if allowed, false otherwise

allowAddCollection

boolean allowAddCollection(String id)

Check if user is allowed to add a collection.

allowUpdateCollection

boolean allowUpdateCollection(String id)

Check if user is allowed to update a collection.

allowRemoveCollection

boolean allowRemoveCollection(String id)

Check if user is allowed to remove a collection.

allowAddResource

boolean allowAddResource(String id)

Check if user is allowed to add a resource.

allowGetResource

boolean allowGetResource(String id)

Check if user is allowed to get a resource.

allowUpdateResource

boolean allowUpdateResource(String id)

Check if user is allowed to update a resource.

allowRemoveResource

boolean allowRemoveResource(String id)

Check if user is allowed to remove a resource.

ContentResource Object

The ContentResource interface provides access to file content and metadata:

ContentResource resource = contentHostingService.getResource(id);

// Identity
String id = resource.getId();
String url = resource.getUrl();
String reference = resource.getReference();

// Content
String contentType = resource.getContentType();
long contentLength = resource.getContentLength();
byte[] content = resource.getContent();
InputStream stream = resource.streamContent();

// Properties
ResourceProperties props = resource.getProperties();
String displayName = props.getProperty(ResourceProperties.PROP_DISPLAY_NAME);
String description = props.getProperty(ResourceProperties.PROP_DESCRIPTION);
String creator = props.getProperty(ResourceProperties.PROP_CREATOR);

// Access Control
Collection<String> groups = resource.getGroups();
AccessMode access = resource.getAccess();
boolean isHidden = resource.isHidden();
Time releaseDate = resource.getReleaseDate();
Time retractDate = resource.getRetractDate();

ContentCollection Object

The ContentCollection interface provides access to collection information:

ContentCollection collection = contentHostingService.getCollection(id);

// Members
List<String> members = collection.getMembers();
int memberCount = collection.getMemberCount();

// Properties
ResourceProperties props = collection.getProperties();
String displayName = props.getProperty(ResourceProperties.PROP_DISPLAY_NAME);

// Identity
String id = collection.getId();
String url = collection.getUrl();

MIME Type Constants

HTML_MIMETYPE

String

default:"text/html"

HTML MIME type

PDF_MIMETYPE

String

default:"application/pdf"

PDF MIME type

DOC_MIMETYPE

String

default:"application/msword"

Word document MIME type

DOCX_MIMETYPE

String

Word 2007+ document MIME type

Overview

Kernel Services

Tool APIs

REST API

​Overview

​Key Concepts

​Constants

​Security Functions

​Events

​Collection Methods

​Collection Access

​getCollection

​checkCollection

​getAllResources

​getCollectionSize

​Collection Creation

​addCollection

​commitCollection

​cancelCollection

​Collection Modification

​editCollection

​Collection Removal

​removeCollection

​Resource Methods

​Resource Access

​getResource

​Resource Creation

​addResource (Simple)

​addResource (Complete)

​addResource (With Groups)

​Resource Modification

​editResource

​commitResource

​cancelResource

​Resource Removal

​removeResource

​Attachment Methods

​addAttachmentResource

​isAttachmentResource

​UUID Methods

​getUuid

​resolveUuid

​Permission Check Methods

​allowGetCollection

​allowAddCollection

​allowUpdateCollection

​allowRemoveCollection

​allowAddResource

​allowGetResource

​allowUpdateResource

​allowRemoveResource

​ContentResource Object

​ContentCollection Object

​MIME Type Constants

​See Also

Build docs developers (and LLMs) love

Overview

Key Concepts

Constants

Security Functions

Events

Collection Methods

Collection Access

getCollection

checkCollection

getAllResources

getCollectionSize

Collection Creation

addCollection

commitCollection

cancelCollection

Collection Modification

editCollection

Collection Removal

removeCollection

Resource Methods

Resource Access

getResource

Resource Creation

addResource (Simple)

addResource (Complete)

addResource (With Groups)

Resource Modification

editResource

commitResource

cancelResource

Resource Removal

removeResource

Attachment Methods

addAttachmentResource

isAttachmentResource

UUID Methods

getUuid

resolveUuid

Permission Check Methods

allowGetCollection

allowAddCollection

allowUpdateCollection

allowRemoveCollection

allowAddResource

allowGetResource

allowUpdateResource

allowRemoveResource

ContentResource Object

ContentCollection Object

MIME Type Constants

See Also