public interface IEclipseContext
While a context appears superficially to be a Map, it may in fact compute values for requested keys dynamically rather than simply retrieving a stored value.
Contexts may have a parent context, and may delegate lookup of a value to their parent. Whether a value is computed or stored in this context or a parent context is an implementation detail that clients need not be concerned with. The content of parent contexts cannot be modified by a child context.
Contexts may have child contexts. Children inherit context values from their parent as described earlier. At any time, one of the children may be considered the active child. The interpretation of what active means depends on the domain in which the context is used.
Like maps, values are stored in the context based on keys. Two types of keys can be used: strings
and classes. When classes are used to access objects in the context, keys are calculated based on
the class name, so the value stored for the class String
can be retrieved
using the key value of "java.lang.String".
Modifier and Type | Method and Description |
---|---|
void |
activate()
Marks this context as active.
|
void |
activateBranch()
Marks this context and its parent contexts as active.
|
boolean |
containsKey(Class<?> clazz)
Returns whether this context or a parent has a value stored for the given class.
|
boolean |
containsKey(String name)
Returns whether this context or a parent has a value stored for the given name.
|
IEclipseContext |
createChild()
Creates a new context using this context as a parent.
|
IEclipseContext |
createChild(String name)
Creates a new named context using this context as a parent.
|
void |
deactivate()
Marks this context as inactive.
|
void |
declareModifiable(Class<?> clazz)
Declares the value for the class as modifiable by descendants of this context.
|
void |
declareModifiable(String name)
Declares the named value as modifiable by descendants of this context.
|
void |
dispose()
Disposes of this object.
|
<T> T |
get(Class<T> clazz)
Returns the context value associated with the given class.
|
Object |
get(String name)
Returns the context value associated with the given name.
|
<T> T |
getActive(Class<T> clazz)
Returns the value stored on the active leaf node of the context's tree.
|
Object |
getActive(String name)
Returns the named value stored on the active leaf node of the context's tree.
|
IEclipseContext |
getActiveChild()
Returns active child for this context.
|
IEclipseContext |
getActiveLeaf()
Follows active child chain to return the active leaf for this context.
|
<T> T |
getLocal(Class<T> clazz)
Returns the context value associated with the given class in this context, or
null if
no such value is defined in this context. |
Object |
getLocal(String name)
Returns the context value associated with the given name in this context, or
null if
no such value is defined in this context. |
IEclipseContext |
getParent()
Returns parent context, or
null if there is no parent context. |
<T> void |
modify(Class<T> clazz,
T value)
Modifies the value to be associated with the given class.
|
void |
modify(String name,
Object value)
Modifies the value to be associated with the given name.
|
void |
processWaiting()
Process waiting updates for listeners that support batch notifications.
|
void |
remove(Class<?> clazz)
Removes the value for the given class from this context.
|
void |
remove(String name)
Removes the given name and any corresponding value from this context.
|
void |
runAndTrack(RunAndTrack runnable)
Executes a runnable within this context.
|
<T> void |
set(Class<T> clazz,
T value)
Sets a value to be associated with a given class in this context.
|
void |
set(String name,
Object value)
Sets a value to be associated with a given name in this context.
|
void |
setParent(IEclipseContext parentContext)
Sets parent context.
|
boolean containsKey(String name)
name
- the name being queriedtrue
if this context has a value for the given name, and
false
otherwise.boolean containsKey(Class<?> clazz)
clazz
- the class being queriedtrue
if this context has a value for the given class, and
false
otherwise.containsKey(String)
Object get(String name)
null
if no
such value is defined or computable by this context, or if the assigned value is
null
.
If the value associated with this name is an ContextFunction
, this method will
evaluate ContextFunction.compute(IEclipseContext, String)
.
name
- the name of the value to returnnull
<T> T get(Class<T> clazz)
clazz
- the class that needs to be found in the contextnull
get(String)
Object getLocal(String name)
null
if
no such value is defined in this context.
This method does not search for the value on other elements on the context tree.
If the value associated with this name is an ContextFunction
, this method will
evaluate ContextFunction.compute(IEclipseContext, String)
.
name
- the name of the value to returnnull
<T> T getLocal(Class<T> clazz)
null
if
no such value is defined in this context.
This method does not search for the value on other elements on the context tree.
clazz
- The class of the value to returnnull
getLocal(String)
void remove(String name)
Removal can never affect a parent context, so it is possible that a subsequent call to
get(String)
with the same name will return a non-null result, due to a value being
stored in a parent context.
name
- the name to removevoid remove(Class<?> clazz)
clazz
- The class to removeremove(String)
void runAndTrack(RunAndTrack runnable)
This method allows a client to keep some external state synchronized with one or more values in this context. For this synchronization to work correctly, the runnable should perform its synchronization purely as a function of values in the context. If the runnable relies on mutable values that are external to the context, it will not be updated correctly when that external state changes.
The runnable is not guaranteed to be executed synchronously with the context change that triggers its execution. Thus the context state at the time of the runnable's execution may not match the context state at the time of the relevant context change.
The runnable does not need to be explicitly unregistered from this context when it is no longer interested in tracking changes. If a subsequent invocation of this runnable does not access any values in this context, it is automatically unregistered from change tracking on this context. Thus a provided runnable should be implemented to return immediately when change tracking is no longer needed.
runnable
- The runnable to execute and register for change trackingRunAndTrack
void set(String name, Object value)
ContextFunction
. In the case of a function,
subsequent invocations of get(String)
with the same name will invoke
ContextFunction.compute(IEclipseContext, String)
to obtain the value. The value
may be null
.
Removal can never affect a parent context, so it is possible that a subsequent call to
get(String)
with the same name will return a non-null result, due to a value being
stored in a parent context.
name
- the name to store a value forvalue
- the value to be stored, or a ContextFunction
that can return
the stored value.<T> void set(Class<T> clazz, T value)
clazz
- The class to store a value forvalue
- The value to be storedset(String, Object)
void modify(String name, Object value)
The value has to be declared as modifiable by the original context before this method can be
used. If the variable with this name has not been declared as modifiable, an
IllegalArgumentException
will be thrown.
The value is modified in the context in which it has been previously set. If none of the contexts on the parent chain have a value set for the name, the value will be set in this context.
name
- the name to store a value forvalue
- the value to be stored, or a ContextFunction
that can return the stored value.IllegalArgumentException
- if the variable has not been declared as modifiable<T> void modify(Class<T> clazz, T value)
clazz
- The class to store a value forvalue
- The value to be storedIllegalArgumentException
- if the variable has not been declared as modifiablemodify(String, Object)
void declareModifiable(String name)
null
value added for the name.name
- the name to be declared as modifiable by descendantsvoid declareModifiable(Class<?> clazz)
null
value added for the class.clazz
- the class to be declared as modifiable by descendantsdeclareModifiable(String)
void processWaiting()
IEclipseContext createChild()
IEclipseContext createChild(String name)
name
- the name to identify this contextIEclipseContext getParent()
null
if there is no parent context.null
void setParent(IEclipseContext parentContext)
null
to indicate that this context has
no parent.parentContext
- the new parent context, or null
to indicate
that this context has no parentvoid activate()
void deactivate()
void activateBranch()
IEclipseContext getActiveChild()
null
if there are no active children.null
IEclipseContext getActiveLeaf()
void dispose()
<T> T getActive(Class<T> clazz)
This method is similar to getActiveLeaf().get(clazz)
but optimized
for a large number of repeat invocations.
Use this method in code paths that are going to receive a large number
of repeat calls, such as inside RunAndTrack.changed(IEclipseContext)
.
In the code paths that won't be cycled through large number of times,
consider using getActiveLeaf().get(clazz)
.
clazz
- the class that needs to be found in the active contextnull
getActiveLeaf()
Object getActive(String name)
This method is similar to getActiveLeaf().get(name)
but optimized
for a large number of repeat invocations.
Use this method in code paths that are going to receive a large number
of repeat calls, such as inside RunAndTrack.changed(IEclipseContext)
.
In the code paths that won't be cycled through large number of times,
consider using getActiveLeaf().get(name)
.
name
- the name of the value to returnnull
getActiveLeaf()
Copyright (c) 2000, 2015 Eclipse Contributors and others. All rights reserved.Guidelines for using Eclipse APIs.