Context (OpenMRS 1.8.5-SNAPSHOT API)

java.lang.Object
- org.openmrs.api.context.Context

```
public class Context
extends Object
```
Represents an OpenMRS Context, which may be used to authenticate to the database and obtain services in order to interact with the system.

The Context is split into a UserContext and ServiceContext. The UserContext is lightweight and there is an instance for every user logged into the system. The ServiceContext is heavier and contains each service class. This is more static and there is only one ServiceContext per OpenMRS instance.

Both the UserContext and the ServiceContext should not be used directly. This Context class has methods to pass through to the currently defined UserContext for the thread and the currently defined ServiceContext.

To use the OpenMRS api there are four things that have to be done:
1. Call startup(String, String, String, Properties) to let the Context contact the database
2. Call openSession() to start a "unit of work".
3. Call authenticate(String, String) to authenticate the current user on the current thread
4. Call closeSession() to end your "unit of work" and commit all changes to the database.
Example usage:
```
        public static void main(String[] args) {
                Context.startup("jdbc:mysql://localhost:3306/db-name?autoReconnect=true", "openmrs-db-user", "3jknfjkn33ijt", new Properties());
                try {
                        Context.openSession();
                        Context.authenticate("admin", "test");
                        List patients = Context.getPatientService().getPatientsByName("Fred");
                        patients.get(0).setBirthdate(new Date());
                        Context.getPatientService().savePatient(patients.get(0));
                        ...
                }
                finally {
                        Context.closeSession();
                }
        }
 
```
See Also:

UserContext, ServiceContext

Constructor Summary

Constructors
Constructor and Description

Context()
Default public constructor

Constructors
Constructor and Description
`Context()` Default public constructor

Method Summary

All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`static void`	`addAdvice(Class cls, org.aopalliance.aop.Advice advice)` Adds an AOP advice object around the given Class `cls`
`static void`	`addAdvisor(Class cls, org.springframework.aop.Advisor advisor)` Adds an AOP advisor around the given Class `cls`
`static void`	`addProxyPrivilege(String privilege)` Convenience method.
`static void`	`authenticate(String username, String password)` Used to authenticate user within the context
`static void`	`becomeUser(String systemId)` Become a different user.
`static void`	`checkCoreDataset()` Runs through the core data (e.g.
`static void`	`clearSession()` Clears cached changes made so far during this unit of work without writing them to the database.
`static void`	`clearUserContext()` Clears the user context from the threadlocal.
`static void`	`closeSession()` Used to define a unit of work.
`static void`	`evictFromSession(Object obj)` Used to clear a cached object out of a session in the middle of a unit of work.
`static void`	`flushSession()` Forces any changes made so far in this unit of work to be written to the database
`static ActiveListService`	`getActiveListService()`
`static AdministrationService`	`getAdministrationService()`
`static AlertService`	`getAlertService()`
`static Set<Role>`	`getAllRoles(User user)` Convenience method.
`static ArdenService`	`getArdenService()`
`static User`	`getAuthenticatedUser()`
`static CohortService`	`getCohortService()`
`static ConceptService`	`getConceptService()`
`static DataSetService`	`getDataSetService()` Deprecated. see reportingcompatibility module
`static SimpleDateFormat`	`getDateFormat()` Gets the simple date format for the current user's locale.
`static EncounterService`	`getEncounterService()`
`static FormService`	`getFormService()`
`static HL7Service`	`getHL7Service()`
`static Locale`	`getLocale()` Convenience method.
`static LocationService`	`getLocationService()`
`static LogicService`	`getLogicService()`
`static MessageService`	`getMessageService()` Get the message service.
`static MessageSourceService`	`getMessageSourceService()`
`static ObsService`	`getObsService()`
`static OrderService`	`getOrderService()`
`static PatientService`	`getPatientService()`
`static PatientSetService`	`getPatientSetService()`
`static PersonService`	`getPersonService()`
`static ProgramWorkflowService`	`getProgramWorkflowService()`
`static <T> List<T>`	`getRegisteredComponents(Class<T> type)`
`static ReportObjectService`	`getReportObjectService()` Deprecated. see reportingcompatibility module
`static ReportService`	`getReportService()` Deprecated. see reportingcompatibility module
`static Properties`	`getRuntimeProperties()` Get the runtime properties that this OpenMRS instance was started with
`static SchedulerService`	`getSchedulerService()`
`static SerializationService`	`getSerializationService()`
`static <T> T`	`getService(Class<? extends T> cls)` Used for getting services not in the previous get*Service() calls
`static UserContext`	`getUserContext()` Gets the user context from the thread local.
`static UserService`	`getUserService()`
`static Object`	`getVolatileUserData(String key)` Get a piece of information for the currently authenticated user.
`static boolean`	`hasPrivilege(String privilege)` Convenience method.
`static boolean`	`isAuthenticated()`
`static boolean`	`isRefreshingContext()`
`static boolean`	`isSessionOpen()` This method tells whether `openSession()` has been called or not already.
`static boolean`	`isUseSystemClassLoader()`
`static Class<?>`	`loadClass(String className)` Loads a class with an instance of the OpenmrsClassLoader.
`static void`	`logout()` logs out the "active" (authenticated) user within context
`static void`	`openSession()` Used to define a unit of work.
`static void`	`refreshAuthenticatedUser()` Refresh the authenticated user object in the current UserContext.
`static void`	`removeAdvice(Class cls, org.aopalliance.aop.Advice advice)` Removes the given AOP advice object from Class `cls`
`static void`	`removeAdvisor(Class cls, org.springframework.aop.Advisor advisor)` Removes the given AOP advisor from Class `cls`
`static void`	`removeProxyPrivilege(String privilege)` Convenience method.
`static void`	`requirePrivilege(String privilege)` Throws an exception if the currently authenticated user does not have the specified privilege.
`void`	`setContextDAO(ContextDAO dao)` Used to set the context's DAO for the application.
`static void`	`setLocale(Locale locale)` Convenience method.
`static void`	`setRuntimeProperties(Properties props)` Set the runtime properties to be used by this OpenMRS instance
`void`	`setServiceContext(ServiceContext ctx)` Sets the service context.
`static void`	`setUserContext(UserContext ctx)` Sets the user context on the thread local so that the service layer can perform authentication/authorization checks. TODO Make thread-safe because this might be accessed by several thread at the same time.
`static void`	`setUseSystemClassLoader(boolean useSystemClassLoader)`
`static void`	`setVolatileUserData(String key, Object value)` Set a piece of information for the currently authenticated user.
`static void`	`shutdown()` Stops the OpenMRS System Should be called after all activity has ended and application is closing
`static void`	`startup(Properties props)` Starts the OpenMRS System Should be called prior to any kind of activity If an `InputRequiredException` is thrown, a call to `DatabaseUpdater#update(Map)` will be required with a mapping from question prompt to user answer before startup can be called again.
`static void`	`startup(String url, String username, String password, Properties properties)` Starts the OpenMRS System in a _non-webapp_ environment If an `InputRequiredException` is thrown, a call to `DatabaseUpdater#update(Map)` will be required with a mapping from question prompt to user answer before startup can be called again.
`static void`	`updateDatabase(Map<String,Object> userInput)` Updates the openmrs database to the latest.

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

- Constructor Detail
  - Context
```
public Context()
```
    Default public constructor
- Method Detail
  - setContextDAO
```
public void setContextDAO(ContextDAO dao)
```
    Used to set the context's DAO for the application.
    
    Parameters:
    
    dao - ContextDAO to set
  - loadClass
```
public static Class<?> loadClass(String className)
                          throws ClassNotFoundException
```
    Loads a class with an instance of the OpenmrsClassLoader. Convenience method equivalent to OpenmrsClassLoader.getInstance().loadClass(className);
    
    Parameters:
    
    className - the class to load
    
    Returns:
    
    the class that was loaded
    
    Throws:
    
    ClassNotFoundException
    
    Should:
    
    load class with the OpenmrsClassLoader
  - setUserContext
```
public static void setUserContext(UserContext ctx)
```
    Sets the user context on the thread local so that the service layer can perform authentication/authorization checks.
    
    TODO Make thread-safe because this might be accessed by several thread at the same time. Making this thread safe might make this a bottleneck.
    
    Parameters:
    
    ctx - UserContext to set
  - clearUserContext
```
public static void clearUserContext()
```
    Clears the user context from the threadlocal.
  - getUserContext
```
public static UserContext getUserContext()
```
    Gets the user context from the thread local. This might be accessed by several threads at the same time.
    
    Returns:
    
    The current UserContext for this thread.
    
    Should:
    
    fail if session hasnt been opened
  - setServiceContext
```
public void setServiceContext(ServiceContext ctx)
```
    Sets the service context.
    
    Parameters:
    
    ctx -
  - authenticate
```
public static void authenticate(String username,
                                String password)
                         throws ContextAuthenticationException
```
    Used to authenticate user within the context
    
    Parameters:
    
    username - user's identifier token for login
    
    password - user's password for authenticating to context
    
    Throws:
    
    ContextAuthenticationException
    
    Should:
    
    not authenticate with null username and password, not authenticate with null password, not authenticate with null username, not authenticate with null password and proper username, not authenticate with null password and proper system id
  - refreshAuthenticatedUser
```
public static void refreshAuthenticatedUser()
```
    Refresh the authenticated user object in the current UserContext. This should be used when updating information in the database about the current user and it needs to be reflecting in the (cached) getAuthenticatedUser() User object.
    
    Since:
    
    1.5
    
    Should:
    
    get fresh values from the database
  - becomeUser
```
public static void becomeUser(String systemId)
                       throws ContextAuthenticationException
```
    Become a different user. (You should only be able to do this as a superuser.)
    
    Parameters:
    
    systemId -
    
    Throws:
    
    ContextAuthenticationException
    
    Should:
    
    change locale when become another user
  - getRuntimeProperties
```
public static Properties getRuntimeProperties()
```
    Get the runtime properties that this OpenMRS instance was started with
    
    Returns:
    
    copy of the runtime properties
  - setRuntimeProperties
```
public static void setRuntimeProperties(Properties props)
```
    Set the runtime properties to be used by this OpenMRS instance
    
    Parameters:
    
    props - runtime properties
  - getConceptService
```
public static ConceptService getConceptService()
```
    Returns:
    
    concept dictionary-related services
  - getEncounterService
```
public static EncounterService getEncounterService()
```
    Returns:
    
    encounter-related services
  - getLocationService
```
public static LocationService getLocationService()
```
    Returns:
    
    location services
  - getObsService
```
public static ObsService getObsService()
```
    Returns:
    
    observation services
  - getPatientService
```
public static PatientService getPatientService()
```
    Returns:
    
    patient-related services
  - getCohortService
```
public static CohortService getCohortService()
```
  - getPersonService
```
public static PersonService getPersonService()
```
    Returns:
    
    person-related services
  - getHL7Service
```
public static HL7Service getHL7Service()
```
    Returns:
    
    Returns the hl7Service.
  - getPatientSetService
```
public static PatientSetService getPatientSetService()
```
    Returns:
    
    patientset-related services
  - getUserService
```
public static UserService getUserService()
```
    Returns:
    
    user-related services
  - getOrderService
```
public static OrderService getOrderService()
```
    Returns:
    
    order service
  - getFormService
```
public static FormService getFormService()
```
    Returns:
    
    form service
  - getSerializationService
```
public static SerializationService getSerializationService()
```
    Returns:
    
    serialization service
    
    Since:
    
    1.5
  - getReportService
```
@Deprecated
public static ReportService getReportService()
```
    Deprecated. see reportingcompatibility module
    
    Returns:
    
    report service
  - getReportObjectService
```
@Deprecated
public static ReportObjectService getReportObjectService()
```
    Deprecated. see reportingcompatibility module
    
    Returns:
    
    report object service
  - getDataSetService
```
@Deprecated
public static DataSetService getDataSetService()
```
    Deprecated. see reportingcompatibility module
    
    Returns:
    
    dataset service
  - getLogicService
```
public static LogicService getLogicService()
```
    Returns:
    
    logic service
  - getAdministrationService
```
public static AdministrationService getAdministrationService()
```
    Returns:
    
    admin-related services
  - getMessageSourceService
```
public static MessageSourceService getMessageSourceService()
```
    Returns:
    
    MessageSourceService
  - getSchedulerService
```
public static SchedulerService getSchedulerService()
```
    Returns:
    
    scheduler service
  - getAlertService
```
public static AlertService getAlertService()
```
    Returns:
    
    alert service
  - getArdenService
```
public static ArdenService getArdenService()
```
    Returns:
    
    arden service
  - getProgramWorkflowService
```
public static ProgramWorkflowService getProgramWorkflowService()
```
    Returns:
    
    program- and workflow-related services
  - getMessageService
```
public static MessageService getMessageService()
```
    Get the message service.
    
    Returns:
    
    message service
  - getActiveListService
```
public static ActiveListService getActiveListService()
```
    Returns:
    
    active list service
  - getAuthenticatedUser
```
public static User getAuthenticatedUser()
```
    Returns:
    
    "active" user who has been authenticated, otherwise null
  - isAuthenticated
```
public static boolean isAuthenticated()
```
    Returns:
    
    true if user has been authenticated in this context
  - logout
```
public static void logout()
```
    logs out the "active" (authenticated) user within context
    
    See Also:
    
    authenticate(java.lang.String, java.lang.String)
    
    Should:
    
    not fail if session hasnt been opened yet
  - getAllRoles
```
public static Set<Role> getAllRoles(User user)
                             throws Exception
```
    Convenience method. Passes through to userContext.getAllRoles(User)
    
    Throws:
    
    Exception
  - hasPrivilege
```
public static boolean hasPrivilege(String privilege)
```
    Convenience method. Passes through to userContext.hasPrivilege(String)
    
    Should:
    
    give daemon user full privileges
  - requirePrivilege
```
public static void requirePrivilege(String privilege)
                             throws ContextAuthenticationException
```
    Throws an exception if the currently authenticated user does not have the specified privilege.
    
    Parameters:
    
    privilege -
    
    Throws:
    
    ContextAuthenticationException
  - addProxyPrivilege
```
public static void addProxyPrivilege(String privilege)
```
    Convenience method. Passes through to UserContext.addProxyPrivilege(String)
  - removeProxyPrivilege
```
public static void removeProxyPrivilege(String privilege)
```
    Convenience method. Passes through to UserContext.removeProxyPrivilege(String)
  - setLocale
```
public static void setLocale(Locale locale)
```
    Convenience method. Passes through to UserContext.setLocale(Locale)
  - getLocale
```
public static Locale getLocale()
```
    Convenience method. Passes through to UserContext.getLocale()
    
    Should:
    
    not fail if session hasnt been opened
  - openSession
```
public static void openSession()
```
    Used to define a unit of work. All "units of work" should be surrounded by openSession and closeSession calls.
  - closeSession
```
public static void closeSession()
```
    Used to define a unit of work. All "units of work" should be surrounded by openSession and closeSession calls.
  - clearSession
```
public static void clearSession()
```
    Clears cached changes made so far during this unit of work without writing them to the database. If you call this method, and later call closeSession() or flushSession() your changes are still lost.
  - flushSession
```
public static void flushSession()
```
    Forces any changes made so far in this unit of work to be written to the database
    
    Since:
    
    1.6
  - isSessionOpen
```
public static boolean isSessionOpen()
```
    This method tells whether openSession() has been called or not already. If it hasn't been called, some methods won't work correctly because a UserContext isn't available.
    
    Returns:
    
    true if openSession() has been called already.
    
    Since:
    
    1.5
    
    Should:
    
    return true if session is closed
  - evictFromSession
```
public static void evictFromSession(Object obj)
```
    Used to clear a cached object out of a session in the middle of a unit of work. Future updates to this object will not be saved. Future gets of this object will not fetch this cached copy
    
    Parameters:
    
    obj - The object to evict/remove from the session
  - startup
```
public static void startup(Properties props)
                    throws DatabaseUpdateException,
                           InputRequiredException,
                           ModuleMustStartException
```
    Starts the OpenMRS System Should be called prior to any kind of activity
    
    If an InputRequiredException is thrown, a call to DatabaseUpdater#update(Map) will be required with a mapping from question prompt to user answer before startup can be called again.
    
    Parameters:
    
    props - Runtime properties to use for startup
    
    Throws:
    
    InputRequiredException - if the DatabaseUpdater has determined that updates cannot continue without input from the user
    
    DatabaseUpdateException - if database updates are required, see DatabaseUpdater.executeChangelog()
    
    ModuleMustStartException - if a module that should be started is not able to
    
    See Also:
    
    InputRequiredException#getRequiredInput() for the required question/datatypes
  - startup
```
public static void startup(String url,
                           String username,
                           String password,
                           Properties properties)
                    throws DatabaseUpdateException,
                           InputRequiredException,
                           ModuleMustStartException
```
    Starts the OpenMRS System in a _non-webapp_ environment
    
    If an InputRequiredException is thrown, a call to DatabaseUpdater#update(Map) will be required with a mapping from question prompt to user answer before startup can be called again.
    
    Note: This method calls openSession(), so you must call closeSession() somewhere on the same thread of this application so as to not leak memory.
    
    Parameters:
    
    url - database url like "jdbc:mysql://localhost:3306/openmrs?autoReconnect=true"
    
    username - Connection username
    
    password - Connection password
    
    properties - Other startup properties
    
    Throws:
    
    InputRequiredException - if the DatabaseUpdater has determined that updates cannot continue without input from the user
    
    DatabaseUpdateException - if the database must be updated. See DatabaseUpdater
    
    ModuleMustStartException - if a module that should start is not able to
    
    See Also:
    
    startup(Properties), InputRequiredException#getRequiredInput() for the required question/datatypes
  - shutdown
```
public static void shutdown()
```
    Stops the OpenMRS System Should be called after all activity has ended and application is closing
  - getService
```
public static <T> T getService(Class<? extends T> cls)
```
    Used for getting services not in the previous get*Service() calls
    
    Parameters:
    
    cls - The Class of the service to get
    
    Returns:
    
    The requested Service
    
    Should:
    
    return the same object when called multiple times for the same class
  - addAdvisor
```
public static void addAdvisor(Class cls,
                              org.springframework.aop.Advisor advisor)
```
    Adds an AOP advisor around the given Class cls
    Advisors can wrap around a method and effect the method before or after
    
    Parameters:
    
    cls -
    
    advisor -
  - addAdvice
```
public static void addAdvice(Class cls,
                             org.aopalliance.aop.Advice advice)
```
    Adds an AOP advice object around the given Class cls
    Advice comes in the form of before or afterReturning methods
    
    Parameters:
    
    cls -
    
    advice -
  - removeAdvisor
```
public static void removeAdvisor(Class cls,
                                 org.springframework.aop.Advisor advisor)
```
    Removes the given AOP advisor from Class cls
    
    Parameters:
    
    cls -
    
    advisor -
  - removeAdvice
```
public static void removeAdvice(Class cls,
                                org.aopalliance.aop.Advice advice)
```
    Removes the given AOP advice object from Class cls
    
    Parameters:
    
    cls -
    
    advice -
  - checkCoreDataset
```
public static void checkCoreDataset()
```
    Runs through the core data (e.g. privileges, roles, and global properties) and adds them if necessary.
  - updateDatabase
```
public static void updateDatabase(Map<String,Object> userInput)
                           throws DatabaseUpdateException,
                                  InputRequiredException
```
    Updates the openmrs database to the latest. This is only needed if using the API alone.
    
    The typical use-case would be: Try to startup(String, String, String, Properties), if that fails, call this method to get the database up to speed.
    
    Parameters:
    
    userInput - (can be null) responses from the user about needed input
    
    Throws:
    
    DatabaseUpdateException - if an error occurred while updating
    
    InputRequiredException - if user input is required
    
    Since:
    
    1.5
  - getVolatileUserData
```
public static Object getVolatileUserData(String key)
```
    Get a piece of information for the currently authenticated user. This information is stored only temporarily. When a new module is loaded or the server is restarted, this information will disappear. If there is not information by this key, null is returned TODO: This needs to be refactored/removed
    
    Parameters:
    
    key - identifying string for the information
    
    Returns:
    
    the information stored
  - setVolatileUserData
```
public static void setVolatileUserData(String key,
                                       Object value)
```
    Set a piece of information for the currently authenticated user. This information is stored only temporarily. When a new module is loaded or the server is restarted, this information will disappear TODO: This needs to be refactored/removed
    
    Parameters:
    
    key - identifying string for this information
    
    value - information to be stored
  - getDateFormat
```
public static SimpleDateFormat getDateFormat()
```
    Gets the simple date format for the current user's locale. The format will be similar in size to mm/dd/yyyy
    
    Returns:
    
    SimpleDateFormat for the user's current locale
    
    See Also:
    
    OpenmrsUtil.getDateFormat(Locale)
    
    Should:
    
    return a pattern with four y characters in it
  - isRefreshingContext
```
public static boolean isRefreshingContext()
```
    Returns:
    
    true/false whether the service context is currently being refreshed
    
    See Also:
    
    ServiceContext.isRefreshingContext()
  - getRegisteredComponents
```
public static <T> List<T> getRegisteredComponents(Class<T> type)
```
    Since:
    
    1.5
    
    See Also:
    
    ServiceContext.getRegisteredComponents(Class)
  - setUseSystemClassLoader
```
public static void setUseSystemClassLoader(boolean useSystemClassLoader)
```
    Since:
    
    1.10
    
    See Also:
    
    ServiceContext.setUseSystemClassLoader(boolean)
  - isUseSystemClassLoader
```
public static boolean isUseSystemClassLoader()
```
    Since:
    
    1.10
    
    See Also:
    
    ServiceContext.isUseSystemClassLoader()

Class Context

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

Context

Method Detail

setContextDAO

loadClass

setUserContext

clearUserContext

getUserContext

setServiceContext

authenticate

refreshAuthenticatedUser

becomeUser

getRuntimeProperties

setRuntimeProperties

getConceptService

getEncounterService

getLocationService

getObsService

getPatientService

getCohortService

getPersonService

getHL7Service

getPatientSetService

getUserService

getOrderService

getFormService

getSerializationService

getReportService

getReportObjectService

getDataSetService

getLogicService

getAdministrationService

getMessageSourceService

getSchedulerService

getAlertService

getArdenService

getProgramWorkflowService

getMessageService

getActiveListService

getAuthenticatedUser

isAuthenticated

logout

getAllRoles

hasPrivilege

requirePrivilege

addProxyPrivilege

removeProxyPrivilege

setLocale

getLocale

openSession

closeSession

clearSession

flushSession

isSessionOpen

evictFromSession

startup

startup

shutdown

getService

addAdvisor

addAdvice

removeAdvisor

removeAdvice

checkCoreDataset

updateDatabase

getVolatileUserData

setVolatileUserData

getDateFormat

isRefreshingContext

getRegisteredComponents

setUseSystemClassLoader

isUseSystemClassLoader