Context (DSpace Kernel :: API and Implementation 6.4 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$

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static class Context.Mode

Nested Classes
Modifier and Type	Class and Description
`static class`	`Context.Mode`

Field Summary

Fields
Modifier and Type Field and Description

protected EventService eventService

Fields
Modifier and Type	Field and Description
`protected EventService`	`eventService`

Constructor Summary

Constructors
Modifier	Constructor and Description
	`Context()` Construct a new context object with default options.
	`Context(Context.Mode mode)` Construct a new context object with the given mode enabled.
`protected`	`Context(EventService eventService, DBConnection dbConnection)`

Method Summary

All Methods Instance Methods Concrete Methods Deprecated 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`	`cacheAllMemberGroupsSet(EPerson ePerson, Set<Group> groups)`
`void`	`cacheAuthorizedAction(DSpaceObject dspaceObject, int action, EPerson eperson, Boolean result, ResourcePolicy rp)`
`void`	`cacheGroupMembership(Group group, EPerson eperson, Boolean isMember)`
`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)` Deprecated.
`protected void`	`finalize()`
`Set<Group>`	`getCachedAllMemberGroupsSet(EPerson ePerson)`
`Boolean`	`getCachedAuthorizationResult(DSpaceObject dspaceObject, int action, EPerson eperson)`
`Boolean`	`getCachedGroupMembership(Group group, EPerson eperson)`
`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
`Context.Mode`	`getCurrentMode()` The current database mode of this context.
`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()` Deprecated.
`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`	`setMode(Context.Mode newMode)` Change the mode of this current context.
`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.
`<E extends ReloadableEntity> void`	`uncacheEntity(E entity)` Remove an entity from the cache.

Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - 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.
  - Context
```
public Context(Context.Mode mode)
```
    Construct a new context object with the given mode enabled. A database connection is opened. No user is authenticated.
    
    Parameters:
    
    mode - The mode to use when opening the context.
- 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.
  - 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
  - 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 uncaching entities when they are no longer needed (see uncacheEntity(ReloadableEntity) () uncacheEntity}).
    
    Throws:
    
    SQLException - When connecting to the active cache fails.
  - setMode
```
public void setMode(Context.Mode newMode)
```
    Change the mode of this current context. BATCH_EDIT: Enabling batch edit mode means that the database connection is configured so that it is optimized to process a large number of records. READ_ONLY: READ ONLY mode will tell the database we are nog going to do any updates. This means it can disable optimalisations for delaying or grouping updates. READ_WRITE: This is the default mode and enables the normal database behaviour. This behaviour is optimal for querying and updating a small number of records.
    
    Parameters:
    
    newMode - The mode to put this context in
  - getCurrentMode
```
public Context.Mode getCurrentMode()
```
    The current database mode of this context.
    
    Returns:
    
    The current mode
  - enableBatchMode
```
@Deprecated
public void enableBatchMode(boolean batchModeEnabled)
                                  throws SQLException
```
    Deprecated.
    
    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
```
@Deprecated
public boolean isBatchModeEnabled()
```
    Deprecated.
    
    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.
  - uncacheEntity
```
public <E extends ReloadableEntity> void uncacheEntity(E entity)
                                                throws SQLException
```
    Remove an entity from the cache. This is necessary when batch processing a large number of items.
    
    Type Parameters:
    
    E - The class of the enity. The entity must implement the ReloadableEntity interface.
    
    Parameters:
    
    entity - The entity to reload
    
    Throws:
    
    SQLException - When reloading the entity from the database fails.
  - getCachedAuthorizationResult
```
public Boolean getCachedAuthorizationResult(DSpaceObject dspaceObject,
                                            int action,
                                            EPerson eperson)
```
  - cacheAuthorizedAction
```
public void cacheAuthorizedAction(DSpaceObject dspaceObject,
                                  int action,
                                  EPerson eperson,
                                  Boolean result,
                                  ResourcePolicy rp)
```
  - getCachedGroupMembership
```
public Boolean getCachedGroupMembership(Group group,
                                        EPerson eperson)
```
  - cacheGroupMembership
```
public void cacheGroupMembership(Group group,
                                 EPerson eperson,
                                 Boolean isMember)
```
  - cacheAllMemberGroupsSet
```
public void cacheAllMemberGroupsSet(EPerson ePerson,
                                    Set<Group> groups)
```
  - getCachedAllMemberGroupsSet
```
public Set<Group> getCachedAllMemberGroupsSet(EPerson ePerson)
```

Class Context

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

eventService

Constructor Detail

Context

Context

Context

Method Detail

getDBConfig

getDbType

setCurrentUser

getCurrentUser

getCurrentLocale

setCurrentLocale

ignoreAuthorization

turnOffAuthorisationSystem

restoreAuthSystemState

setExtraLogInfo

getExtraLogInfo

complete

commit

dispatchEvents

setDispatcher

addEvent

getEvents

hasEvents

pollEvent

abort

isValid

isReadOnly

setSpecialGroup

inSpecialGroup

getSpecialGroups

finalize

shutDownDatabase

getCacheSize

setMode

getCurrentMode

enableBatchMode

isBatchModeEnabled

reloadEntity

uncacheEntity

getCachedAuthorizationResult

cacheAuthorizedAction

getCachedGroupMembership

cacheGroupMembership

cacheAllMemberGroupsSet

getCachedAllMemberGroupsSet