...
The DSpace Application Lifecycle
- Kernel Initialization
- Service Manager Startup
- Service Registration
- Service Manager Shutdown
- Service Manager Startup
The life cycle of a servlet the container and the services therein is controlled by the container the Web-application context or the DSpace CLI ScriptLauncher main executable in which the servlet has been deployed. When a request is mapped to a servlet, the container performs the following steps.
- If an instance of the servlet does not exist, the Web container
- Loads the servlet class.
- Creates an instance of the servlet class.
- Initializes the servlet instance by calling the init method. Initialization is covered in Initializing a Servlet.
- Invokes the service method, passing a request and response object. Service methods are discussed in the section Writing Service Methods.
If the container needs to remove the servlet, it finalizes the servlet by calling the servlet's destroy method. Finalization is discussed in Finalizing a Servlet.
The Lifecycle assures that when the Service managers (and specifically Spring in this case) are initialized, the required core and addon services are wired and made available to your application.
The ServiceManager Request Cycle
The ServiceManager Request Cycle is similar to the Webapplication Request Cycle. In the case of the Service Request, There is an incoming "Request" object with the state of the a call from the client, this Request is then enterpreted by the Container and mapped to a specific Servlet, which executes to completion, On Completion, the Serlvet Generates a
When a request is made by either the Webapplication or the CLI initialization, then the Request Lifecycle is engaged:
The Service Manager Interface is defined as follows:
...
| Code Block |
|---|
public void pushConfig(Map<String, String> settings); |
Core Services
Behind APIs
can be reimplemented without affecting developers who are using the services.
Most of the services have plugin/provider points so that customizations can be added into the system without touching the core services code.
Example, specialized authentication system and wants to manage the authentication calls which come into the system. The implementor can simply implement an AuthenticationProvider and then register it with the DS2 kernel's ServiceManager. This can be done at any time and does not have to be done during Kernel startup. This allows providers to be swapped out at runtime without disrupting the DS2 service if desired. It can also speed up development by allowing quick hot redeploys of code during development.
Configuration Service
| Code Block |
|---|
/* Instantiate the Utility Class */
DSpace dspace = new DSpace();
/* Access get the Service Manager by convenience method */
ConfigurationService service = dspace.getSingletonService(ConfigurationService.class); |
Request Service
A request is an atomic transaction in the system. It is likely to be an HTTP request in many cases but it does not have to be. This service provides DSpace with a way to manage atomic transactions so that when a request comes in which requires multiple things to happen they can either all succeed or all fail without each service attempting to manage this independently.
In a nutshell this simply allows identification of the current request and the ability to discover if it succeeded or failed when it ends. Nothing in the system will enforce usage of the service, but we encourage developers who are interacting with the system to make use of this service so they know if the request they are participating in with has succeeded or failed and can take appropriate actions.
| Code Block |
|---|
public interface Request {
public String getRequestId();
public Session getSession();
public Object getAttribute(String name);
public void setAttribute(String name, Object o);
public ServletRequest getServletRequest();
public HttpServletRequest getHttpServletRequest();
public ServletResponse getServletResponse();
public HttpServletResponse getHttpServletResponse();
} |
The DSpace Session
The Session represents a user's session (login session) in the system. Can hold some additional attributes as needed, but the underlying implementation may limit the number and size of attributes to ensure session replication is not impacted negatively. A DSpace session is like an HttpSession (and generally is actually one) so this service is here to allow developers to find information about the current session and to access information in it. The session identifies the current user (if authenticated) so it also serves as a way to track user sessions. Since we use HttpSession directly it is easy to mirror sessions across multiple servers in order to allow for no-interruption failover for users when servers go offline.
| Code Block |
|---|
public interface Session extends HttpSession {
/**
* @return the session identifier. This is not the {@link #getId()}
* from HttpSession unless no session id was specified when the
* session was bound.
*/
public String getSessionId();
/**
* Return the internal user ID for this session.
*
* @return internal user ID for the user using this session.
* This is null if the session is anonymous.
*/
public String getUserId();
/**
* Get the external/enterprise user ID for this session.
*
* @return the external/enterprise user id of the user associated with this session
*/
public String getUserEID();
/**
* @return true if this session is active OR false if the session has timed out or been invalidated
*/
public boolean isActive();
/**
* @return id of the server with which this session is associated.
*/
public String getServerId();
/**
* @return the IP Address from which this session originated
*/
public String getOriginatingHostIP();
/**
* @return the hostname from which this session originated
*/
public String getOriginatingHostName();
/**
* Get an attribute from the session if one exists.
* @param key the key for the attribute
* @return the value if one exists OR null if none
*/
public String getAttribute(String key);
/**
* Set an attribute on a session.
*
* @param key for the attribute
* @param value (if this is null then the attribute is removed)
*/
public void setAttribute(String key, String value);
/**
* Get all attributes of this session.
* @return a copy of the attributes in this session.
* Modifying it has no effect on the session attributes.
*/
public Map<String, String> getAttributes();
/**
* Purges all data from this session and effectively resets it to an
* anonymous session. Does not invalidate the session, though.
*/
public void clear(); |
Behind APIs
can be reimplemented without affecting developers who are using the services.
Most of the services have plugin/provider points so that customizations can be added into the system without touching the core services code.
Example, specialized authentication system and wants to manage the authentication calls which come into the system. The implementor can simply implement an AuthenticationProvider and then register it with the DS2 kernel's ServiceManager. This can be done at any time and does not have to be done during Kernel startup. This allows providers to be swapped out at runtime without disrupting the DS2 service if desired. It can also speed up development by allowing quick hot redeploys of code during development.
Configuration Service
| Code Block |
|---|
/* Instantiate the Utility Class */
DSpace dspace = new DSpace();
/* Access get the Service Manager by convenience method */
ConfigurationService service = dspace.getSingletonService(ConfigurationService.class); |
Legacy Configuration
Wiki Markup _\[dspace\]/config/dspace.cfg{_}
...
| Code Block |
|---|
/* Instantiate the Utility Class */ DSpace dspace = new DSpace(); /* Access get the Service Manager by convenience method */ ServiceManager manager = dspace.getServiceManager DSpace(); /* Or access Access get the Service Manager by convenience method for core services */ EventService service = dspace.getEventService(); |
The DSpace launcher (
| Code Block |
|---|
bin/dspace |
) initializes a kernel before dispatching to the selected command.
Application Frameworks (Spring, Guice, etc.)
Similar to Standalone Applications, but you can use your framework to instantiate an org.dspace.utils.DSpace object.
...
<bean id="dspace" class="org.dspace.utils.DSpace"/>
*/
ServiceManager manager = dspace.getServiceManager();
/* Or access by convenience method for core services */
EventService service = dspace.getEventService();
|
The DSpace launcher (
| Code Block |
|---|
bin/dspace |
) initializes a kernel before dispatching to the selected command.
Application Frameworks (Spring, Guice, etc.)
Similar to Standalone Applications, but you can use your framework to instantiate an org.dspace.utils.DSpace object.
| Code Block | ||||
|---|---|---|---|---|
| ||||
<bean id="dspace" class="org.dspace.utils.DSpace"/>
|
Web Applications
In web applications, the kernel can be started and accessed through the use of Servlet Filter/ContextListeners which are provided as part of the DSpace 2 utilities. Developers don't need to understand what is going on behind the scenes and can simply write their applications and package them as webapps and take advantage of the services which are offered by DSpace 2.
Providers and Plugins
For developers (how we are trying to make your lives easier): The DS2 ServiceManager supports a plugin/provider system which is runtime hot-swappable. The implementor can register any service/provider bean or class with the DS2 kernel ServiceManager. The ServiceManager will manage the lifecycle of beans (if desired) and will instantiate and manage the lifecycle of any classes it is given. This can be done at any time and does not have to be done during Kernel startup. This allows providers to be swapped out at runtime without disrupting the service if desired. The goal of this system is to allow DS2 to be extended without requiring any changes to the core codebase or a rebuild of the code code.
Activators
Developers can provide an activator to allow the system to startup their service or provider. It is a simple interface with 2 methods which are called by the ServiceManager to startup the provider(s) and later to shut them down. These simply allow a developer to run some arbitrary code in order to create and register services if desired. It is the method provided to add plugins directly to the system via configuration as the activators are just listed in the configuration file and the system starts them up in the order it finds them.
Provider Stacks
Utilities are provided to assist with stacking and ordering providers. Ordering is handled via a priority number such that 1 is the highest priority and something like 10 would be lower. 0 indicates that priority is not important for this service and can be used to ensure the provider is placed at or near the end without having to set some arbitrarily high number.
Core Services
The core services are all behind APIs so that they can be reimplemented without affecting developers who are using the services. Most of the services have plugin/provider points so that customizations can be added into the system without touching the core services code. For example, let's say a deployer has a specialized authentication system and wants to manage the authentication calls which come into the system. The implementor can simply implement an AuthenticationProvider and then register it with the DS2 kernel's ServiceManager. This can be done at any time and does not have to be done during Kernel startup. This allows providers to be swapped out at runtime without disrupting the DS2 service if desired. It can also speed up development by allowing quick hot redeploys of code during development.
Caching Service
Provides for a centralized way to handle caching in the system and thus a single point for configuration and control over all caches in the system. Provider and plugin developers are strongly encouraged to use this rather than implementing their own caching. The caching service has the concept of scopes so even storing data in maps or lists is discouraged unless there are good reasons to do so.
Configuration Service
The ConfigurationService controls the external and internal configuration of DSpace 2. It reads Properties files when the kernel starts up and merges them with any dynamic configuration data which is available from the services. This service allows settings to be updated as the system is running, and also defines listeners which allow services to know when their configuration settings have changed and take action if desired. It is the central point to access and manage all the configuration settings in DSpace 2.
Manages the configuration of the DSpace 2 system. Can be used to manage configuration for providers and plugins also.
Benefits over the DSpace ConfigurationManager:
1.) Type Casting and Array Parsing: Configuration Service will slip your comma separated values for you.
Recommendation: Why parse values if you do not have to, avoid Parsing Values where-ever possible.
Use commas for lists of values, use lookups
If you end up thinking you want to create maps in your properties, your doing it in the wrong place look instead at Spring Configuration and objectifying your configuration
Objectifying Configuration
wiring your default configuuration
overriding defaults
EventService
Handles events and provides access to listeners for consumption of events.
SessionService
Web Applications
In web applications, the kernel can be started and accessed through the use of Servlet Filter/ContextListeners which are provided as part of the DSpace 2 utilities. Developers don't need to understand what is going on behind the scenes and can simply write their applications and package them as webapps and take advantage of the services which are offered by DSpace 2.
Providers and Plugins
For developers (how we are trying to make your lives easier): The DS2 ServiceManager supports a plugin/provider system which is runtime hot-swappable. The implementor can register any service/provider bean or class with the DS2 kernel ServiceManager. The ServiceManager will manage the lifecycle of beans (if desired) and will instantiate and manage the lifecycle of any classes it is given. This can be done at any time and does not have to be done during Kernel startup. This allows providers to be swapped out at runtime without disrupting the service if desired. The goal of this system is to allow DS2 to be extended without requiring any changes to the core codebase or a rebuild of the code code.
Activators
Developers can provide an activator to allow the system to startup their service or provider. It is a simple interface with 2 methods which are called by the ServiceManager to startup the provider(s) and later to shut them down. These simply allow a developer to run some arbitrary code in order to create and register services if desired. It is the method provided to add plugins directly to the system via configuration as the activators are just listed in the configuration file and the system starts them up in the order it finds them.
Provider Stacks
Utilities are provided to assist with stacking and ordering providers. Ordering is handled via a priority number such that 1 is the highest priority and something like 10 would be lower. 0 indicates that priority is not important for this service and can be used to ensure the provider is placed at or near the end without having to set some arbitrarily high number.
Core Services
The core services are all behind APIs so that they can be reimplemented without affecting developers who are using the services. Most of the services have plugin/provider points so that customizations can be added into the system without touching the core services code. For example, let's say a deployer has a specialized authentication system and wants to manage the authentication calls which come into the system. The implementor can simply implement an AuthenticationProvider and then register it with the DS2 kernel's ServiceManager. This can be done at any time and does not have to be done during Kernel startup. This allows providers to be swapped out at runtime without disrupting the DS2 service if desired. It can also speed up development by allowing quick hot redeploys of code during development.
Caching Service
Provides for a centralized way to handle caching in the system and thus a single point for configuration and control over all caches in the system. Provider and plugin developers are strongly encouraged to use this rather than implementing their own caching. The caching service has the concept of scopes so even storing data in maps or lists is discouraged unless there are good reasons to do so.
Configuration Service
The ConfigurationService controls the external and internal configuration of DSpace 2. It reads Properties files when the kernel starts up and merges them with any dynamic configuration data which is available from the services. This service allows settings to be updated as the system is running, and also defines listeners which allow services to know when their configuration settings have changed and take action if desired. It is the central point to access and manage all the configuration settings in DSpace 2.
Manages the configuration of the DSpace 2 system. Can be used to manage configuration for providers and plugins also.
Benefits over the DSpace ConfigurationManager:
1.) Type Casting and Array Parsing: Configuration Service will slip your comma separated values for you.
Recommendation: Why parse values if you do not have to, avoid Parsing Values where-ever possible.
Use commas for lists of values, use lookups
If you end up thinking you want to create maps in your properties, your doing it in the wrong place look instead at Spring Configuration and objectifying your configuration
Objectifying Configuration
wiring your default configuuration
overriding defaults
EventService
Handles events and provides access to listeners for consumption of events.
RequestService
In DS2 a request is an atomic transaction in the system. It is likely to be an HTTP request in many cases but it does not have to be. This service provides the core services with a way to manage atomic transactions so that when a request comes in which requires multiple things to happen they can either all succeed or all fail without each service attempting to manage this independently. In a nutshell this simply allows identification of the current request and the ability to discover if it succeeded or failed when it ends. Nothing in the system will enforce usage of the service, but we encourage developers who are interacting with the system to make use of this service so they know if the request they are participating in with has succeeded or failed and can take appropriate actions.
SessionService
...
Examples
Configuring Event Listeners
...