org.dspace.core
Class Context

java.lang.Object
  org.dspace.core.Context

public class Context
extends Object

Class representing the context of a particular DSpace operation. This stores information such as the current authenticated user and the database connection being used.

Typical use of the context object will involve constructing one, and setting the current user if one is authenticated. Several operations may be performed using the context object. If all goes well, complete is called to commit the changes and free up any resources used by the context. If anything has gone wrong, abort is called to roll back any changes and free up the resources.

The context object is also used as a cache for CM API objects.

Version:

$Revision$

Constructor Summary

Context()
Construct a new context object.

Method Summary

void	abort() Close the context, without committing any of the changes performed using this context.
void	addEvent(Event event) Add an event to be dispatched when this context is committed.
void	cache(Object o, int id) Store an object in the object cache.
void	clearCache() Remove all the objects from the object cache
void	commit() Commit any transaction that is currently in progress, but do not close the context.
void	complete() Close the context object after all of the operations performed in the context have completed successfully.
protected void	finalize()
Object	fromCache(Class<?> objectClass, int id) Store an object in the object cache.
int	getCacheSize() Get the count of cached objects, which you can use to instrument an application to track whether it is "leaking" heap space by letting cached objects build up.
Locale	getCurrentLocale() Gets the current Locale
EPerson	getCurrentUser() Get the current (authenticated) user
Connection	getDBConnection() Get the database connection associated with the context
LinkedList<Event>	getEvents() Get the current event list.
String	getExtraLogInfo() Get extra information to be logged with message logged in the scope of this context.
Group[]	getSpecialGroups() gets an array of all of the special groups that current user is a member of
boolean	hasEvents()
boolean	ignoreAuthorization() Find out if the authorisation system should be ignored for this context.
boolean	inSpecialGroup(int groupID) test if member of special group
boolean	isValid() Find out if this context is valid.
Event	pollEvent() Retrieves the first element in the events list & removes it from the list of events once retrieved
void	removeCached(Object o, int id) Remove an object from the object cache.
void	restoreAuthSystemState() Restore the previous Authorisation System State.
void	setCurrentLocale(Locale locale) set the current Locale
void	setCurrentUser(EPerson user) Set the current user.
void	setDispatcher(String dispatcher) Select an event dispatcher, null selects the default
void	setExtraLogInfo(String info) Set extra information that should be added to any message logged in the scope of this context.
void	setIgnoreAuthorization(boolean b) Deprecated. use turnOffAuthorisationSystem() for make the change and restoreAuthSystemState() when change are not more required
void	setSpecialGroup(int groupID) set membership in a special group
void	turnOffAuthorisationSystem() Turn Off the Authorisation System for this context and store this change in a history for future use.

Methods inherited from class java.lang.Object

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

Constructor Detail

Context

public Context()
        throws SQLException

Construct a new context object. A database connection is opened. No user is authenticated.

Throws:

SQLException - if there was an error obtaining a database connection

Method Detail

getDBConnection

public Connection getDBConnection()

Get the database connection associated with the context

Returns:

the database connection

setCurrentUser

public void setCurrentUser(EPerson user)

Set the current user. Authentication must have been performed by the caller - this call does not attempt any authentication.

Parameters:

user - the new current user, or null if no user is authenticated

getCurrentUser

public EPerson getCurrentUser()

Get the current (authenticated) user

Returns:

the current user, or null if no user is authenticated

getCurrentLocale

public Locale getCurrentLocale()

Gets the current Locale

Returns:

Locale the current Locale

setCurrentLocale

public void setCurrentLocale(Locale locale)

set the current Locale

Parameters:

locale - the current Locale

ignoreAuthorization

public boolean ignoreAuthorization()

Find out if the authorisation system should be ignored for this context.

Returns:

true if authorisation should be ignored for this session.

turnOffAuthorisationSystem

public void turnOffAuthorisationSystem()

Turn Off the Authorisation System for this context and store this change in a history for future use.

restoreAuthSystemState

public void restoreAuthSystemState()

Restore the previous Authorisation System State. If the state was not changed by the current caller a warning will be displayed in log. Use: mycontext.turnOffAuthorisationSystem(); some java code that require no authorisation check mycontext.restoreAuthSystemState(); If Context debug is enabled, the correct sequence calling will be checked and a warning will be displayed if not.

setIgnoreAuthorization

public void setIgnoreAuthorization(boolean b)

Deprecated. use turnOffAuthorisationSystem() for make the change and restoreAuthSystemState() when change are not more required

Specify whether the authorisation system should be ignored for this context. This should be used sparingly.

Parameters:

b - if true, authorisation should be ignored for this session.

setExtraLogInfo

public void setExtraLogInfo(String info)

Set extra information that should be added to any message logged in the scope of this context. An example of this might be the session ID of the current Web user's session:

setExtraLogInfo("session_id="+request.getSession().getId());

Parameters:

info - the extra information to log

getExtraLogInfo

public String getExtraLogInfo()

Get extra information to be logged with message logged in the scope of this context.

Returns:

the extra log info - guaranteed non- null

complete

public void complete()
              throws SQLException

Close the context object after all of the operations performed in the context have completed successfully. Any transaction with the database is committed.

Throws:

SQLException - if there was an error completing the database transaction or closing the connection

commit

public void commit()
            throws SQLException

Commit any transaction that is currently in progress, but do not close the context.

Throws:

SQLException - if there was an error completing the database transaction or closing the connection

setDispatcher

public void setDispatcher(String dispatcher)

Select an event dispatcher, null selects the default

addEvent

public void addEvent(Event event)

Add an event to be dispatched when this context is committed.

Parameters:

event -

getEvents

public LinkedList<Event> getEvents()

Get the current event list. If there is a separate list of events from already-committed operations combine that with current list.

Returns:

List of all available events.

hasEvents

public boolean hasEvents()

pollEvent

public Event pollEvent()

Retrieves the first element in the events list & removes it from the list of events once retrieved

Returns:

The first event of the list or null if the list is empty

abort

public void abort()

Close the context, without committing any of the changes performed using this context. The database connection is freed. No exception is thrown if there is an error freeing the database connection, since this method may be called as part of an error-handling routine where an SQLException has already been thrown.

isValid

public boolean isValid()

Find out if this context is valid. Returns false if this context has been aborted or completed.

Returns:

true if the context is still valid, otherwise false

fromCache

public Object fromCache(Class<?> objectClass,
                        int id)

Store an object in the object cache.

Parameters:

objectClass - Java Class of object to check for in cache

id - ID of object in cache

Returns:

the object from the cache, or null if it's not cached.

cache

public void cache(Object o,
                  int id)

Store an object in the object cache.

Parameters:

o - the object to store

id - the object's ID

removeCached

public void removeCached(Object o,
                         int id)

Remove an object from the object cache.

Parameters:

o - the object to remove

id - the object's ID

clearCache

public void clearCache()

Remove all the objects from the object cache

getCacheSize

public int getCacheSize()

Get the count of cached objects, which you can use to instrument an application to track whether it is "leaking" heap space by letting cached objects build up. We recommend logging a cache count periodically or episodically at the INFO or DEBUG level, but ONLY when you are diagnosing cache leaks.

Returns:

count of entries in the cache.

setSpecialGroup

public void setSpecialGroup(int groupID)

set membership in a special group

Parameters:

groupID - special group's ID

inSpecialGroup

public boolean inSpecialGroup(int groupID)

test if member of special group

Parameters:

groupID - ID of special group to test

Returns:

true if member

getSpecialGroups

public Group[] getSpecialGroups()
                         throws SQLException

gets an array of all of the special groups that current user is a member of

Returns:

Throws:

SQLException

finalize

protected void finalize()
                 throws Throwable

Overrides:

finalize in class Object

Throws:

Throwable