uk.ac.ed.epcc.webapp

Class AppContext

java.lang.Object

uk.ac.ed.epcc.webapp.AppContext

public final class AppContext
extends java.lang.Object

The AppContext is used to encapsulate the runtime environment. To a first approximation the AppContext is passed down to all levels of the code and most significant classes contain a reference to an AppContext. Because Web applications are typically multi threaded we wish to avoid static variables. The AppContext is used to hold any information that we would otherwise be tempted to have as static and any static methods usually need to take an AppContext as a parameter.

Though there is a high degree of dependence between AppContext and most of the code base we concentrate global dependencies within this Object which reduces coupling to the classes contained within the AppContext such as the database connection.

Each page request will have an independent AppContext and short term state can be cached within in using the setAttribute method. This data can be retrieved using the getAttribute method.

The AppContext also acts as a composite policy object allowing different behaviours to be selected depending on the environment. This allows a policy object specific to a particular type of functionality (e.g. logging) to be retrieved using the getService(Class) method (the class object for the required interface/superclass is used as the key). e.g.

 LoggerService lfac = conn.getService(LoggerService.class);
 Logger log = lfac.getLogger(getClass())
 log.debug("Debug message");
 

Services all implement AppContextService and can be pre-set using the setService(AppContextService) method or they can be constructed dynamically by a call to makeObject(Class, String) The FQCN of the class used to request the service is used as the identifying tag when lookup up the implementation class. If the located class is annotated with the PreRequisiteService annotation then the AppContext will attempt to ensure the referenced services are in place before calling the constructor of the requested service. All services are cached as attributes so the same instance will be returned by subsequent calls to getService(Class). Frequently AppContextServices will be chained together with the currently installed implementation of a service holding a reference to the implementation it replaced and possibly forwarding some requests to that nested version.

Key AppContextServices include:

• LoggerService - application logging policy
• ConfigService - configuration property policy
• SessionService - user session and persistence
• DatabaseService - database connection service

Note that there may be legacy methods in AppContext for functionality that was once part of the class proper but has been moved into a separate service.

The AppContext class is final so all specialisations need to be implemented via AppContextServices.

The AppContext encodes the conventions for constructing objects by reflection. A typical use might be:

TargetType t = conn.makeObject(TargetType.class,"tag-name");

This uses the getPropertyClass(Class, String) method that looks for a class name in a configuration property of the form class.tag-name This may either be a full class-name or the name of a classdef parameter e.g.

  class.fred=myclass
  class.bill=myclass
  classdef.myclass=com.example.thing

The target type can be an interface or a superclass of desired object. If the target type is a non abstract class it will be used as the default if no class is configured using parameters. The AppContext will attempt various constructor signatures when creating an object in this way attempting to pass the tag-name and the AppContext. Some of these include the tag-name so its possible to refer to several instances of the same type by different tag-names. Factory classes that correspond to different database tables often follow this pattern, using the table name as the tag. If a class implements the Tagged interface the value returned by the Tagged.getTag() method should be the same as the tag used to construct the object.

Configuration parameters

The AppContext provides mechanisms for retrieving configuration parameters. e.g.

   AppContext c;
   String param1 = c.getInitParameter("param1");
   String param2 = c.getInitParameter("param2","Default value");
   int int_param = c.getIntegerParameter("param3",13); // default to 13
 

These methods use an underlying ConfigService.

Error reporting

The AppContext provides error reporting methods

  try{
    ....
  }catch(Exception e){
    c.error(e,"An error occurred");
  }
 

These are forwarded onto an underlying LoggerService if one is available but converts the error to a fatal error otherwise. Normally it is better to use a Logger specific to the class where the exception is caught unless reporting error from within a AppContextService. We will probably remove or reduce the visibility of the AppContext methods in the near future.

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	CLASS_PREFIX
static java.lang.String	CLASSDEF_PROP_PREFIX
static Feature	CONTEXT_CACHE_FEATURE
static Feature	DATABASE_FEATURE
static Feature	TAG_CHECK_FEATURE

Constructor Summary

Constructors

Constructor and Description
AppContext()
AppContext(java.util.Properties props)

Method Summary

Modifier and Type	Method and Description
<T extends Contexed> boolean	canMakeContexedObject(java.lang.Class<T> clazz) Method to check a class implements one of the supported constructors for canMakeContexedObject(Class)
<T> boolean	canMakeObject(java.lang.Class<T> clazz) Method to check if a class implements one of the permitted constructors for makeObject(Class)
void	clearAttributes()
<S extends AppContextService<S>> void	clearService(java.lang.Class<S> clazz)
void	close() Cleans up resources held by the AppContext The AppContextCleanup.cleanup() method is called on each service in the reverse order that services were created.
void	error(java.lang.String errors) Report an application error.
void	error(java.lang.Throwable e, java.lang.String text) Report an application error.
java.lang.String	expandText(java.lang.String text_to_expand) perform config parameter expansion on a text fragment.
<T> java.lang.reflect.Constructor<T>	findConstructor(java.lang.Class<T> clazz, java.lang.Object... param) Search for a matching constructor considering supertypes
<T> java.lang.reflect.Constructor<T>	findConstructorFromParamSignature(java.lang.Class<T> clazz, java.lang.Class... param) Search for Constructor considering super-types
java.lang.Object	getAttribute(java.lang.Object key) method for returning Objects cached in the AppContext using setAttribute.
java.util.Map<java.lang.Object,java.lang.Object>	getAttributes()
boolean	getBooleanParameter(java.lang.String name, boolean def) Check for a boolean parameter yes/on/true or no/off/false
<T> java.lang.Class<? extends T>	getClassDef(java.lang.Class<T> template, java.lang.String name)
<T> java.lang.Class<? extends T>	getClassFromName(java.lang.Class<T> template, java.lang.Class<? extends T> default_class, java.lang.String tag) resolve a class-name into a class.
java.util.List<java.lang.Class>	getClassList(java.lang.Class template, java.lang.String name)
<T> java.util.Map<java.lang.String,java.lang.Class>	getClassMap(java.lang.Class<T> template) Generate a map of tags to classes assignable to (or containing an assignable Composable Composite of) a target type This will only find classes registered with the config service.
double	getDoubleParam(java.lang.String name, double def)
<E extends java.lang.Enum> E	getEnumParameter(java.lang.Class<E> clazz, java.lang.String name, E fallback)
java.lang.String	getExpandedProperty(java.lang.String name) Query an environmental parameter with nested parameter expansion
java.lang.String	getExpandedProperty(java.lang.String name, java.lang.String def)
java.lang.String	getInitParameter(java.lang.String name) Query environmental parameter.
java.lang.String	getInitParameter(java.lang.String name, java.lang.String fallback) Query an environmental parameter returning a default value if not found
java.util.Hashtable<java.lang.String,java.lang.String>	getInitParameters(java.lang.String prefix) Get all environmental parameters starting with a given prefix.
int	getIntegerParameter(java.lang.String name, int def)
long	getLongParameter(java.lang.String name, long def)
java.util.Properties	getProperties() return a copy of the Service properties associated with the AppContext
<T> java.lang.Class<? extends T>	getPropertyClass(java.lang.Class<T> template, java.lang.Class<? extends T> default_class, java.lang.String tag) lookup a desired implementation class using the Config service.
<T> java.lang.Class<? extends T>	getPropertyClass(java.lang.Class<T> template, java.lang.String tag) lookup a desired implementation class using the Config service.
<S extends AppContextService> S	getService(java.lang.Class<S> clazz)
java.util.Collection<AppContextService>	getServices() Return a collection of the current AppContextServices This is used for generating debugging info.
java.lang.String	getTaggedProperty(java.lang.String name, java.lang.String tag) Query a property with generic and specialised forms.
boolean	hasAttribute(java.lang.Object key) Do we have the specified attribute set
<T extends Contexed> T	makeContexedObject(java.lang.Class<T> clazz) Construct an object that implements Contexed using the non-tagged constructor (if it exists).
<T> T	makeObject(java.lang.Class<T> clazz) Create an instance from a class.
<T> T	makeObject(java.lang.Class<T> clazz, java.lang.String tag) Construct an object identified by a string tag.
<T> T	makeObjectWithDefault(java.lang.Class<T> clazz, java.lang.Class<? extends T> default_class, java.lang.String tag) Construct an object identified by a string tag.
<T> T	makeObjectWithDefault(java.lang.Class<T> clazz, java.lang.Class<? extends T> default_class, java.lang.String path, java.lang.String name) Construct an object identified by a string tag and an optional qualifier string.
<T> T	makeParamObject(java.lang.Class<T> clazz, java.lang.Object... param) Construct an object based on a supplied parameter list.
static boolean	parseBooleanParam(java.lang.String parm, boolean def)
void	removeAttribute(java.lang.Object key) remove an object cached in the AppContext
void	removeCached(java.lang.String path, java.lang.String tag)
void	setAttribute(java.lang.Object key, java.lang.Object value) method for caching an object in the AppContext Code should never assume the existance of an attribute this should only be used for short term caching to avoid unecessary database queries.
<S extends AppContextService> S	setService(S service)

Methods inherited from class java.lang.Object

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

Field Detail

CLASSDEF_PROP_PREFIX

public static final java.lang.String CLASSDEF_PROP_PREFIX

See Also:

Constant Field Values

CONTEXT_CACHE_FEATURE

public static final Feature CONTEXT_CACHE_FEATURE

DATABASE_FEATURE

public static final Feature DATABASE_FEATURE

TAG_CHECK_FEATURE

public static final Feature TAG_CHECK_FEATURE

CLASS_PREFIX

public static final java.lang.String CLASS_PREFIX

See Also:

Constant Field Values

Constructor Detail

AppContext

public AppContext()

AppContext

public AppContext(java.util.Properties props)

Method Detail

close

public void close()

Cleans up resources held by the AppContext The AppContextCleanup.cleanup() method is called on each service in the reverse order that services were created.

error

public void error(java.lang.Throwable e,
                  java.lang.String text)

Report an application error.

Parameters:

e - Exception generating error.

text - Text of error.

error

public final void error(java.lang.String errors)

Report an application error.

Parameters:

errors - Text of error.

getAttribute

public final java.lang.Object getAttribute(java.lang.Object key)

method for returning Objects cached in the AppContext using setAttribute. Code should never assume the existence of an attribute this should only be used for short term caching to avoid unnecessary database queries

We use Object as the key instead of String so that classes can create private key objects (e.g. an Enum) to ensure cached objects are not accessible outside the class.

Parameters:

key -

Returns:

cached object or null if it does not exist

hasAttribute

public boolean hasAttribute(java.lang.Object key)

Do we have the specified attribute set

Parameters:

key -

Returns:

boolean

getAttributes

public java.util.Map<java.lang.Object,java.lang.Object> getAttributes()

getService

public final <S extends AppContextService> S getService(java.lang.Class<S> clazz)

getServices

public final java.util.Collection<AppContextService> getServices()

Return a collection of the current AppContextServices This is used for generating debugging info.

Returns:

Collection

clearService

public <S extends AppContextService<S>> void clearService(java.lang.Class<S> clazz)

setService

public <S extends AppContextService> S setService(S service)

getBooleanParameter

public boolean getBooleanParameter(java.lang.String name,
                                   boolean def)

Check for a boolean parameter yes/on/true or no/off/false

Parameters:

name - String name of paameter

def - boolean default if it does not exist.

Returns:

boolean

parseBooleanParam

public static boolean parseBooleanParam(java.lang.String parm,
                                        boolean def)

getDoubleParam

public double getDoubleParam(java.lang.String name,
                             double def)

getInitParameter

public final java.lang.String getInitParameter(java.lang.String name)

Query environmental parameter.

Parameters:

name - Name of parameter

Returns:

value or null.

getExpandedProperty

public final java.lang.String getExpandedProperty(java.lang.String name)

Query an environmental parameter with nested parameter expansion

getExpandedProperty

public final java.lang.String getExpandedProperty(java.lang.String name,
                                                  java.lang.String def)

expandText

public java.lang.String expandText(java.lang.String text_to_expand)

perform config parameter expansion on a text fragment. Text of the form ${name} is replaced with the corresponding config parameter A fall-back value can be specified by using ${name:fallback}

Parameters:

text_to_expand -

Returns:

expanded text

getTaggedProperty

public final java.lang.String getTaggedProperty(java.lang.String name,
                                                java.lang.String tag)

Query a property with generic and specialised forms. First look for a property called name.tag If this does not exist look for a property called name

Parameters:

name - base property name

tag - specialisation

Returns:

String

getInitParameter

public final java.lang.String getInitParameter(java.lang.String name,
                                               java.lang.String fallback)

Query an environmental parameter returning a default value if not found

Parameters:

name - Name of parameter

fallback - Default value

Returns:

String

getEnumParameter

public final <E extends java.lang.Enum> E getEnumParameter(java.lang.Class<E> clazz,
                                                           java.lang.String name,
                                                           E fallback)

getInitParameters

public final java.util.Hashtable<java.lang.String,java.lang.String> getInitParameters(java.lang.String prefix)

Get all environmental parameters starting with a given prefix.

Parameters:

prefix - String

Returns:

Hashtable

getIntegerParameter

public int getIntegerParameter(java.lang.String name,
                               int def)

getLongParameter

public long getLongParameter(java.lang.String name,
                             long def)

getProperties

public java.util.Properties getProperties()

return a copy of the Service properties associated with the AppContext

Returns:

Properties

makeContexedObject

public <T extends Contexed> T makeContexedObject(java.lang.Class<T> clazz)
                                          throws java.lang.Exception

Construct an object that implements Contexed using the non-tagged constructor (if it exists).

Type Parameters:

T -

Parameters:

clazz -

Returns:

instance of T

Throws:

java.lang.Exception

canMakeContexedObject

public <T extends Contexed> boolean canMakeContexedObject(java.lang.Class<T> clazz)

Method to check a class implements one of the supported constructors for canMakeContexedObject(Class)

Parameters:

clazz -

Returns:

makeObject

public <T> T makeObject(java.lang.Class<T> clazz)
                 throws java.lang.Exception

Create an instance from a class. The target object is assumed to either have a public no argument constructor or to implement Contexed and take an AppContext as a constructor parameter.

Type Parameters:

T - type to produce

Parameters:

clazz - Class of type to create

Returns:

instance of T

Throws:

java.lang.Exception

See Also:

Contexed

canMakeObject

public <T> boolean canMakeObject(java.lang.Class<T> clazz)

Method to check if a class implements one of the permitted constructors for makeObject(Class)

Parameters:

clazz -

Returns:

makeParamObject

public <T> T makeParamObject(java.lang.Class<T> clazz,
                             java.lang.Object... param)
                      throws java.lang.Exception

Construct an object based on a supplied parameter list. This is a convenience routine that searched for a compatible constructor. It used the first constructor where the supplied parameters may be assigned to the parameter types of the constructor.

Type Parameters:

T -

Parameters:

clazz - Class of object to make

param - parameter list

Returns:

new instance

Throws:

java.lang.Exception

findConstructor

public <T> java.lang.reflect.Constructor<T> findConstructor(java.lang.Class<T> clazz,
                                                            java.lang.Object... param)

Search for a matching constructor considering supertypes

Type Parameters:

T -

Parameters:

clazz -

param -

Returns:

Constructor or null

findConstructorFromParamSignature

public <T> java.lang.reflect.Constructor<T> findConstructorFromParamSignature(java.lang.Class<T> clazz,
                                                                              java.lang.Class... param)

Search for Constructor considering super-types

Type Parameters:

T -

Parameters:

clazz -

param - array of class types from parameter

Returns:

makeObject

public final <T> T makeObject(java.lang.Class<T> clazz,
                              java.lang.String tag)

Construct an object identified by a string tag. The exact class to construct can be set using the property class.tag If the property is not set then the default_class is constructed. If the default class cannot be instantiated null is returned. It is quite common to need to parameterise the constructed class using the tag. We therefore look for a string parameterised constructor in preference. If such a constructor is found:

Type Parameters:

T - return type

Parameters:

clazz - default super class

tag -

Returns:

instance

makeObjectWithDefault

public final <T> T makeObjectWithDefault(java.lang.Class<T> clazz,
                                         java.lang.Class<? extends T> default_class,
                                         java.lang.String tag)

Construct an object identified by a string tag. The exact class to construct can be set using the property class.tag If the property is not set then the default_class is constructed. If the default class cannot be instantiated null is returned. It is quite common to need to parameterise the constructed class using the tag. We therefore look for a string parameterised constructor in preference. If such a constructor is found:

Type Parameters:

T - return type

Parameters:

clazz - return type class

default_class -

tag -

Returns:

instance

makeObjectWithDefault

public final <T> T makeObjectWithDefault(java.lang.Class<T> clazz,
                                         java.lang.Class<? extends T> default_class,
                                         java.lang.String path,
                                         java.lang.String name)

Construct an object identified by a string tag and an optional qualifier string.

The qualifier string if for cases where it is convenient to use the same tag string for various related classes.

The exact class to construct can be set using the property class.path.tag Or (if path is null or the property is not set) class.tag If neither property is not set then the default_class is constructed. If the default class cannot be instantiated null is returned. It is quite common to need to parameterise the constructed class using the tag. We therefore look for a string parameterised constructor in preference. If such a constructor is found.

Type Parameters:

T - return type

Parameters:

clazz - return type class

default_class -

path -

name -

Returns:

instance

getPropertyClass

public <T> java.lang.Class<? extends T> getPropertyClass(java.lang.Class<T> template,
                                                         java.lang.String tag)

lookup a desired implementation class using the Config service. When tag is not null this method looks up the property class.tag interpreting the result as a class name. If this class name exists, can be instantiated and extends or implements the template class then this class is returned. Otherwise this method will return either the template class (if it can be instantiated) or null. It it a common convention to use the database table name of the target as the tag.

Type Parameters:

T - type that the target class must extend or implement

Parameters:

template - Class object for T

tag -

Returns:

Class of target or null.

getPropertyClass

public final <T> java.lang.Class<? extends T> getPropertyClass(java.lang.Class<T> template,
                                                               java.lang.Class<? extends T> default_class,
                                                               java.lang.String tag)

lookup a desired implementation class using the Config service. When tag is not null this method looks up the property class.tag to determine the target class. This can either be a fully qualified java class name or (if not qualified) then it can also be the name of a class definition parameter. classdef.name defining the fully qualified name. If the target class name exists, can be instantiated and extends or implements the template class then this class is returned. Otherwise this method will return either the default_class (if it can be instantiated) or null.

The use of classdef parameters is preferred as it makes it easier to provide backwards compatibility when classes are renamed. It also allows

Type Parameters:

T - type that the target class must extend or implement

Parameters:

template - Class object for T

default_class - Class to use if no property set

tag -

Returns:

Class of target or null.

getClassList

public java.util.List<java.lang.Class> getClassList(java.lang.Class template,
                                                    java.lang.String name)

getClassMap

public <T> java.util.Map<java.lang.String,java.lang.Class> getClassMap(java.lang.Class<T> template)

Generate a map of tags to classes assignable to (or containing an assignable Composable Composite of) a target type This will only find classes registered with the config service.

Type Parameters:

T - type being looked for.

Parameters:

template - Class of target.

Returns:

Map of tag to class

getClassFromName

public <T> java.lang.Class<? extends T> getClassFromName(java.lang.Class<T> template,
                                                         java.lang.Class<? extends T> default_class,
                                                         java.lang.String tag)

resolve a class-name into a class. This will attempt expand classdef definitions if the name is in the default package. If a default_class is specified this will be returned if no definition is found in the configuration service. And a ClassCastException will be thrown if a definition incompatible with the template is found. Without a default_class null is returned in both cases. Note this can take fully qualified class names so it is safer not to allow the class_name to be set from untrusted content. Instead use getPropertyClass(java.lang.Class<T>, java.lang.String) which ensures only classes registered with the ConfigService can be generated.

Type Parameters:

T -

Parameters:

template -

default_class - result to use if no definition

tag - Either a fully qualified class name or a classdef tag.

Returns:

target class or null

getClassDef

public <T> java.lang.Class<? extends T> getClassDef(java.lang.Class<T> template,
                                                    java.lang.String name)

removeAttribute

public final void removeAttribute(java.lang.Object key)

remove an object cached in the AppContext

Parameters:

key -

setAttribute

public final void setAttribute(java.lang.Object key,
                               java.lang.Object value)

method for caching an object in the AppContext Code should never assume the existance of an attribute this should only be used for short term caching to avoid unecessary database queries.

We use Object as the key instead of String so that classes can create private key objects (e.g. an Enum) to ensure cached objects are not accessible outside the class.

Parameters:

key - used to identify attribute

value - Object to be stored.

clearAttributes

public final void clearAttributes()

removeCached

public final void removeCached(java.lang.String path,
                               java.lang.String tag)