Context (DSpace Kernel :: API and Implementation 6.0-rc2 API)

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$

Field Summary

Fields
Modifier and Type Field and Description

protected EventService eventService

static short READ_ONLY
option flags

Fields
Modifier and Type	Field and Description
`protected EventService`	`eventService`
`static short`	`READ_ONLY` option flags

Constructor Summary

Constructors
Modifier	Constructor and Description
	`Context()` Construct a new context object with default options.
`protected`	`Context(EventService eventService, DBConnection dbConnection)`
	`Context(short options)` Construct a new context object with passed options.

Method Summary

Methods
Modifier and Type	Method and Description
`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`	`clearCache()` Clear the cache of all object that have been read from the database so far.
`void`	`commit()` Commit the current transaction with the database, persisting any pending changes.
`void`	`complete()` Close the context object after all of the operations performed in the context have completed successfully.
`void`	`dispatchEvents()`
`void`	`enableBatchMode(boolean batchModeEnabled)` Enable or disable "batch processing mode" for this context.
`protected void`	`finalize()`
`long`	`getCacheSize()` Returns the size of the cache of all object that have been read from the database so far.
`Locale`	`getCurrentLocale()` Gets the current Locale
`EPerson`	`getCurrentUser()` Get the current (authenticated) user
`DatabaseConfigVO`	`getDBConfig()`
`String`	`getDbType()`
`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.
`List<Group>`	`getSpecialGroups()` Get 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(UUID groupID)` test if member of special group
`boolean`	`isBatchModeEnabled()` Check if "batch processing mode" is enabled for this context.
`boolean`	`isReadOnly()` Reports whether context supports updating DSpaceObjects, or only reading.
`boolean`	`isValid()` Find out if this context is valid.
`Event`	`pollEvent()` Retrieves the first element in the events list and removes it from the list of events once retrieved
`<E extends ReloadableEntity> E`	`reloadEntity(E entity)` Reload an entity from the database into the 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(UUID groupID)`
`void`	`shutDownDatabase()`
`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

- Field Detail
  - READ_ONLY
```
public static final short READ_ONLY
```
    option flags
    
    See Also:
    Constant Field Values
  - eventService
```
protected EventService eventService
```
- Constructor Detail
  - Context
```
protected Context(EventService eventService,
       DBConnection dbConnection)
```
  - Context
```
public Context()
```
    Construct a new context object with default options. A database connection is opened. No user is authenticated.
    
    Throws:
    
    SQLException - if there was an error obtaining a database connection
  - Context
```
public Context(short options)
```
    Construct a new context object with passed options. A database connection is opened. No user is authenticated.
    
    Parameters:
    options - context operation flags
- Method Detail
  - getDBConfig
```
public DatabaseConfigVO getDBConfig()
                             throws SQLException
```
    Throws:
    
    SQLException
  - getDbType
```
public String getDbType()
```
  - 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.
    Calling complete() on a Context which is no longer valid (isValid()==false), is a no-op.
    
    Throws:
    
    SQLException - if there was an error completing the database transaction or closing the connection
  - commit
```
public void commit()
            throws SQLException
```
    Commit the current transaction with the database, persisting any pending changes. The database connection is not closed and can be reused afterwards. WARNING: After calling this method all previously fetched entities are "detached" (pending changes are not tracked anymore). You have to reload all entities you still want to work with manually after this method call (see reloadEntity(ReloadableEntity)).
    
    Throws:
    
    SQLException - When committing the transaction in the database fails.
  - dispatchEvents
```
public void dispatchEvents()
```
  - setDispatcher
```
public void setDispatcher(String dispatcher)
```
    Select an event dispatcher, null selects the default
    
    Parameters:
    dispatcher - dispatcher
  - 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 and 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.
    Calling abort() on a Context which is no longer valid (isValid()==false), is a no-op.
  - 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
  - isReadOnly
```
public boolean isReadOnly()
```
    Reports whether context supports updating DSpaceObjects, or only reading.
    
    Returns:
    true if the context is read-only, otherwise false
  - setSpecialGroup
```
public void setSpecialGroup(UUID groupID)
```
  - inSpecialGroup
```
public boolean inSpecialGroup(UUID groupID)
```
    test if member of special group
    
    Parameters:
    groupID - ID of special group to test
    
    Returns:
    true if member
  - getSpecialGroups
```
public List<Group> getSpecialGroups()
                             throws SQLException
```
    Get an array of all of the special groups that current user is a member of.
    
    Returns:
    list of groups
    
    Throws:
    
    SQLException - if database error
  - finalize
```
protected void finalize()
                 throws Throwable
```
    Overrides:
    
    finalize in class Object
    
    Throws:
    
    Throwable
  - shutDownDatabase
```
public void shutDownDatabase()
                      throws SQLException
```
    Throws:
    
    SQLException
  - clearCache
```
public void clearCache()
                throws SQLException
```
    Clear the cache of all object that have been read from the database so far. This will also free up (heap space) memory. You should use this method when processing a large number of records. WARNING: After calling this method all previously fetched entities are "detached" (pending changes are not tracked anymore). You have to reload all entities you still want to work with manually after this method call (see reloadEntity(ReloadableEntity)). This method will take care of reloading the current user.
    
    Throws:
    
    SQLException - When clearing the entity cache fails
  - getCacheSize
```
public long getCacheSize()
                  throws SQLException
```
    Returns the size of the cache of all object that have been read from the database so far. A larger number means that more memory is consumed by the cache. This also has a negative impact on the query performance. In that case you should consider clearing the cache (see clearCache).
    
    Throws:
    
    SQLException - When connecting to the active cache fails.
  - enableBatchMode
```
public void enableBatchMode(boolean batchModeEnabled)
                     throws SQLException
```
    Enable or disable "batch processing mode" for this context. Enabling batch processing mode means that the database connection is configured so that it is optimized to process a large number of records. Disabling batch processing mode restores the normal behaviour that is optimal for querying and updating a small number of records.
    
    Parameters:
    batchModeEnabled - When true, batch processing mode will be enabled. If false, it will be disabled.
    
    Throws:
    
    SQLException - When configuring the database connection fails.
  - isBatchModeEnabled
```
public boolean isBatchModeEnabled()
```
    Check if "batch processing mode" is enabled for this context.
    
    Returns:
    True if batch processing mode is enabled, false otherwise.
  - reloadEntity
```
public <E extends ReloadableEntity> E reloadEntity(E entity)
                                        throws SQLException
```
    Reload an entity from the database into the cache. This method will return a reference to the "attached" entity. This means changes to the entity will be tracked and persisted to the database.
    
    Type Parameters:
    E - The class of the enity. The entity must implement the ReloadableEntity interface.
    Parameters:
    entity - The entity to reload
    
    Returns:
    A (possibly) NEW reference to the entity that should be used for further processing.
    
    Throws:
    
    SQLException - When reloading the entity from the database fails.

Class Context

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

READ_ONLY

eventService

Constructor Detail

Context

Context

Context

Method Detail

getDBConfig

getDbType

setCurrentUser

getCurrentUser

getCurrentLocale

setCurrentLocale

ignoreAuthorization

turnOffAuthorisationSystem

restoreAuthSystemState

setIgnoreAuthorization

setExtraLogInfo

getExtraLogInfo

complete

commit

dispatchEvents

setDispatcher

addEvent

getEvents

hasEvents

pollEvent

abort

isValid

isReadOnly

setSpecialGroup

inSpecialGroup

getSpecialGroups

finalize

shutDownDatabase

clearCache

getCacheSize

enableBatchMode

isBatchModeEnabled

reloadEntity