blackboard.cms.filesystem
Class CSContext

java.lang.Object
  blackboard.cms.filesystem.CSContext

public class CSContext

extends java.lang.Object

A Context is the top level state manager for a series of Blackboard Content System calls. For every set of actions grouped together into one transaction, a new context is created and used. A Context instance contains transactional state for that request (ie commit, rollback). All permission checking is done through calls on the Context object.

Without a Context, whenever an exception is thrown, the state of the transactions involved would be unknown. It would not be possible to know which transaction(s) needed to be committed or rolled back. The Context object is used to keep track of that state and allow or block commit attempts. Thus, the Context object can be used to find out if the current transaction can be committed or not.

It is extremely important when using the Context object to ensure that you properly use a try{},catch{},finally{} block to commit() or rollback() each transaction. Not doing so properly can cause deadlocks to occur and cause performance degradation and unexpected behavior.

It is recommended to always use CSContext in the following way:

 CSContext ctxCS=null;
 try {
      ctxCS = CSContext.getContext();
 
      //your code here
 
 } catch (Exception e) {
      ctxCS.rollback();
 } finally {
      if (ctxCS!=null) {
          ctxCS.commit();
      } 
 }
 

bb-manifest note: In order to use these methods, please be sure to include the following permissions within the bb-manifest under the permissions section:
<permission type="java.lang.RuntimePermission" name="db.connection.*" />
<permission type="attribute" name="user.authinfo" actions="get,set" />
<permission type="attribute" name="user.personalinfo" actions="get,set" />
<permission type="persist" name="user" actions="create,modify,delete" />
<permission type="persist" name="userrole" actions="create,modify,delete" />
<permission type="persist" name="course" actions="create,modify,delete" />

Since:

Bb CS 1.2

Version:

$Revision: $

Method Summary

boolean	canDelete(CSEntry cse) Checks whether delete permission is granted for the CSEntry named and in this Context instance.
boolean	canManage(CSEntry cse) Checks whether manage permission is granted for the CSEntry named and in this Context instance.
boolean	canRead(CSEntry cse) Checks whether read permission is granted for the CSEntry named and in this Context instance.
boolean	canWrite(CSEntry cse) Checks whether write permission is granted for the CSEntry named and in this Context instance.
void	commit() Commits changes for the transaction in this Context instance.
CSDirectory	createDirectory(java.lang.String parentDir, java.lang.String dirName) Creates a new Directory
CSFile	createFile(java.lang.String parentDir, java.lang.String fileName, java.io.InputStream is) Creates a new File
CSEntry	findEntry(java.lang.String path) Returns a CSEntry for the given file/directory path.
static CSContext	getContext() Returns the CSContext object.
static CSContext	getContext(blackboard.data.user.User user) Returns the CSContext object based on the User object supplied.
CSDirectory	getCourseDirectory(blackboard.data.course.Course crs) Returns a CSDirectory representing the course/org home directory.
CSDirectory	getCourseEReservesDirectory(blackboard.data.course.Course crs) Returns a CSDirectory representing the course/org ereserve directory.
CSDirectory	getUserDirectory(blackboard.data.user.User usr) Returns a CSDirectory representing the user's home directory.
boolean	isOwner(CSEntry cse) Checks whether the user identified by the Context instance is the owner of the file named.
boolean	isSuperUser() Returns the SuperUser attribute for the Context instance.
void	isSuperUser(boolean isSuperUser) Sets the SuperUser attribute for the Context instance.
void	rollback() Rolls back changes for the transaction in this Context instance.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getContext

public static CSContext getContext(blackboard.data.user.User user)
                            throws CSFileSystemException

Returns the CSContext object based on the User object supplied.

Parameters:

user - the User for the Context

Returns:

a CSContext.

Throws:

CSFileSystemException

getContext

public static CSContext getContext()
                            throws CSFileSystemException

Returns the CSContext object.

Returns:

a CSContext.

Throws:

CSFileSystemException

commit

public void commit()
            throws CSFileSystemException

Commits changes for the transaction in this Context instance.

Throws:

CSFileSystemException

rollback

public void rollback()
              throws CSFileSystemException

Rolls back changes for the transaction in this Context instance.

Throws:

CSFileSystemException

isSuperUser

public boolean isSuperUser()

Returns the SuperUser attribute for the Context instance.

Returns:

a boolean denoting the SuperUser status for this Context.

isSuperUser

public void isSuperUser(boolean isSuperUser)

Sets the SuperUser attribute for the Context instance.

Parameters:

isSuperUser - true if this Context instance should have the SuperUser attribute, false otherwise

canRead

public boolean canRead(CSEntry cse)
                throws CSFileSystemException

Checks whether read permission is granted for the CSEntry named and in this Context instance. Since every Context instance has a user associated with it , this checks to see if that user has Read permission.

Returns:

a boolean denoting the whether the Context user has Read permissions.

Throws:

CSFileSystemException

canWrite

public boolean canWrite(CSEntry cse)
                 throws CSFileSystemException

Checks whether write permission is granted for the CSEntry named and in this Context instance. Since every Context instance has a user associated with it, this checks to see if that user has Write permission.

Returns:

a boolean denoting the whether the Context user has Write permissions.

Throws:

CSFileSystemException

canDelete

public boolean canDelete(CSEntry cse)
                  throws CSFileSystemException

Checks whether delete permission is granted for the CSEntry named and in this Context instance. Since every Context instance has a user associated with it, this checks to see if that user has Delete permission.

Returns:

a boolean denoting the whether the Context user has Delete permissions.

Throws:

CSFileSystemException

canManage

public boolean canManage(CSEntry cse)
                  throws CSFileSystemException

Checks whether manage permission is granted for the CSEntry named and in this Context instance. Since every Context instance has a user associated with it, this checks to see if that user has Manage permission.

Returns:

a boolean denoting the whether the Context user has Manage permissions.

Throws:

CSFileSystemException

isOwner

public boolean isOwner(CSEntry cse)
                throws CSFileSystemException

Checks whether the user identified by the Context instance is the owner of the file named.

Returns:

a boolean denoting the whether the Context user is the owner.

Throws:

CSFileSystemException

findEntry

public CSEntry findEntry(java.lang.String path)
                  throws CSFileSystemException

Returns a CSEntry for the given file/directory path.

Parameters:

path - a string representing the file/directory path.

Returns:

a CSEntry representing the file/directory from the given path.

Throws:

CSFileSystemException

createFile

public CSFile createFile(java.lang.String parentDir,
                         java.lang.String fileName,
                         java.io.InputStream is)
                  throws CSFileSystemException

Creates a new File

Parameters:

parentDir - a String representing the parent directory for where the file will reside

fileName - a String representing the name of the file

is - The Input Stream for the file contents.

Returns:

a CSFile representing the new file.

Throws:

CSFileSystemException

createDirectory

public CSDirectory createDirectory(java.lang.String parentDir,
                                   java.lang.String dirName)
                            throws CSFileSystemException

Creates a new Directory

Parameters:

parentDir - a String representing the parent directory for where the directory will reside

dirName - a String representing the name of the directory

Returns:

a CSDirectory representing the new directory.

Throws:

CSFileSystemException

getUserDirectory

public CSDirectory getUserDirectory(blackboard.data.user.User usr)
                             throws CSFileSystemException

Returns a CSDirectory representing the user's home directory. Returns null if the user does not get a home directory.

Returns:

a CSDirectory representing the user's home directory.

Throws:

CSFileSystemException

getCourseDirectory

public CSDirectory getCourseDirectory(blackboard.data.course.Course crs)
                               throws CSFileSystemException

Returns a CSDirectory representing the course/org home directory. Returns null if the course/org does not get a home directory.

Parameters:

crs - the specified course/org

Returns:

a CSDirectory representing the course/org home directory.

Throws:

CSFileSystemException

getCourseEReservesDirectory

public CSDirectory getCourseEReservesDirectory(blackboard.data.course.Course crs)
                                        throws CSFileSystemException

Returns a CSDirectory representing the course/org ereserve directory. Returns null if the course does not get a ereserve directory. Returns null if it is an org.

Parameters:

crs - the specified course

Returns:

a CSDirectory representing the course/org ereserve directory.

Throws:

CSFileSystemException