net.sf.mmm.util.context.api

Interface GenericContext

All Known Subinterfaces:

MutableGenericContext

All Known Implementing Classes:

AbstractGenericContextProxy, AbstractMutableGenericContext, ImmutableGenericContext, MutableGenericContextImpl

public interface GenericContext

This is the interface for a context of variables. It allows to read all variables as well as to create a child-context this is mutable.
Note: Initially the name of this interface should be just Context. However there are tons of common java projects shipped with a type of this name so to avoid confusion a longer name was chosen.

Since:

1.1.0

Author:

Joerg Hohwiller (hohwille at users.sourceforge.net)

Method Summary

Modifier and Type	Method and Description
MutableGenericContext	createChildContext() This method creates a new context that inherits all variables from this context (and its parent contexts).
<T> T	getVariable(Class<T> type) This method gets the variable associated with the given type.
Object	getVariable(String variableName) This method gets the variable associated with the given variableName.
<T> T	getVariable(String variableName, Class<T> type) This method gets the variable associated with the given variableName as the given type.
Set<String>	getVariableNames() This method returns the names of all defined variables.
boolean	hasVariable(String variableName) This method determines if the variable for the given variableName exists.
<T> T	requireVariable(Class<T> type) This method gets the variable associated with the given type.
Object	requireVariable(String variableName) This method gets the variable associated with the given variableName.
<T> T	requireVariable(String variableName, Class<T> type) This method gets the variable associated with the given variableName.
Map<String,Object>	toMap() This method allows to create a Map representing the variables of this context.

Method Detail

requireVariable

Object requireVariable(String variableName)
                throws ValueNotSetException

This method gets the variable associated with the given variableName.

Parameters:

variableName - is the name of the requested variable.

Returns:

the value of the variable.

Throws:

ValueNotSetException - if the requested variable is NOT set.

requireVariable

<T> T requireVariable(String variableName,
                      Class<T> type)
               throws ValueNotSetException

This method gets the variable associated with the given variableName.

Type Parameters:

T - the generic type of the variable.

Parameters:

variableName - is the name of the requested variable.

type - is the class reflecting the type of the variable.

Returns:

the value of the variable.

Throws:

ValueNotSetException - if the requested variable is NOT set.

requireVariable

<T> T requireVariable(Class<T> type)
               throws ValueNotSetException

This method gets the variable associated with the given type. It will use the classname as variable-name.
ATTENTION:
Only use this method in combination with expressive types. E.g. types like String or Integer are bad candidates while MySpecificSingletonComponentInterface might be a good option.

Type Parameters:

T - the generic type of the variable.

Parameters:

type - is the class reflecting the type of the variable.

Returns:

the value of the variable.

Throws:

ValueNotSetException - if the requested variable is NOT set.

Since:

2.0.0

See Also:

MutableGenericContext.setVariable(String, Object)

getVariable

Object getVariable(String variableName)

This method gets the variable associated with the given variableName.

Parameters:

variableName - is the name of the requested variable.

Returns:

the value of the variable or null if the variable is NOT set.

getVariable

<T> T getVariable(String variableName,
                  Class<T> type)

This method gets the variable associated with the given variableName as the given type. If the type does NOT match the actual type of the variable it may automatically be converted as possible.

Type Parameters:

T - the generic type of the variable.

Parameters:

variableName - is the name of the requested variable.

type - is the class reflecting the type of the variable.

Returns:

the value of the variable or null if the variable is NOT set.

getVariable

<T> T getVariable(Class<T> type)

This method gets the variable associated with the given type. It will use the classname as variable-name.
ATTENTION:
Only use this method in combination with expressive types. E.g. types like String or Integer are bad candidates while MySpecificSingletonComponentInterface might be a good option.

Type Parameters:

T - the generic type of the variable.

Parameters:

type - is the class reflecting the type of the variable.

Returns:

the value of the variable or null if the variable is NOT set.

Since:

2.0.0

See Also:

MutableGenericContext.setVariable(String, Object)

hasVariable

boolean hasVariable(String variableName)

This method determines if the variable for the given variableName exists.

Parameters:

variableName - is the name of the requested variable.

Returns:

true if a value exists for the given variableName, false otherwise.

getVariableNames

Set<String> getVariableNames()

This method returns the names of all defined variables.
ATTENTION:
Please note that this is an expensive operation so prefer hasVariable(String) where possible.

Returns:

a set of all variable names.

createChildContext

MutableGenericContext createChildContext()

This method creates a new context that inherits all variables from this context (and its parent contexts). Variables that are set in the child-context override inherited variables. However changes to the child-context do NOT modify this context.
ATTENTION:
Typically the child-context will be a cheap-copy connected to this context. So you should be aware of this when creating many child-contexts recursively as their parent-contexts can NOT be collected by the garbage-collector.

Returns:

the new created sub-context.

toMap

Map<String,Object> toMap()

This method allows to create a Map representing the variables of this context. This can be useful to pass this context to an external component (e.g. a template-engine) that typically accepts a Map.
ATTENTION:
This method will create a fresh map with all variables filled in. Therefore it is NOT a cheap operation. Further the Map will NOT reflect changes of this context and vice versa.

Returns:

this context as map.