Package org.eclipse.e4.core.contexts

Interface IEclipseContext

public interface IEclipseContext
A context is used to isolate application code from its dependencies on an application framework or container. This helps avoid building in dependencies on a specific framework that inhibit reuse of the application code. Fundamentally a context supplies values (either data objects or services), and allows values to be set. Typically a client will be provided values from a context through injection, removing the need for clients to even depend on this interface.

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".

A context should be disposed with dispose() when no longer needed.

Since:
1.3
Restriction:
This interface is not intended to be implemented by clients.
Restriction:
This interface is not intended to be extended by clients.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final String
    PROPERTY_CONTEXT
    Property that is used for the event on TOPIC_DISPOSE and contains the IEclipseContext that is about to be disposed.
    static final String
    TOPIC_DISPOSE
    Topic for sending an event via EventAdmin to inform about the disposal of an IEclipseContext.

  • Method Summary

    Modifier and Type
    Method
    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.

  • Field Details

  • Method Details

    • containsKey

      boolean containsKey(String name)
      Returns whether this context or a parent has a value stored for the given name.
      Parameters:
      name - the name being queried
      Returns:
      true if this context has a value for the given name, and false otherwise.

    • containsKey

      boolean containsKey(Class<?> clazz)
      Returns whether this context or a parent has a value stored for the given class.
      Parameters:
      clazz - the class being queried
      Returns:
      true if this context has a value for the given class, and false otherwise.
      See Also:

    • get

      Object get(String name)
      Returns the context value associated with the given name. Returns 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).

      Parameters:
      name - the name of the value to return
      Returns:
      an object corresponding to the given name, or null

    • get

      <T> T get(Class<T> clazz)
      Returns the context value associated with the given class.
      Parameters:
      clazz - the class that needs to be found in the context
      Returns:
      an object corresponding to the given class, or null
      See Also:

    • getLocal

      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.

      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).

      Parameters:
      name - the name of the value to return
      Returns:
      an object corresponding to the given name, or null

    • getLocal

      <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.

      This method does not search for the value on other elements on the context tree.

      Parameters:
      clazz - The class of the value to return
      Returns:
      An object corresponding to the given class, or null
      See Also:

    • remove

      void remove(String name)
      Removes the given name and any corresponding value from this context.

      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.

      Parameters:
      name - the name to remove

    • remove

      void remove(Class<?> clazz)
      Removes the value for the given class from this context.
      Parameters:
      clazz - The class to remove
      See Also:

    • runAndTrack

      void runAndTrack(RunAndTrack runnable)
      Executes a runnable within this context. If the runnable accesses any values in this context during its execution, the runnable will be executed again after any of those values change. Only the context values accessed during the most recent invocation of the runnable are tracked.

      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.

      Parameters:
      runnable - The runnable to execute and register for change tracking
      See Also:

    • set

      void set(String name, Object value)
      Sets a value to be associated with a given name in this context. The value may be an arbitrary object, or it may be an 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.

      Parameters:
      name - the name to store a value for
      value - the value to be stored, or a ContextFunction that can return the stored value.

    • set

      <T> void set(Class<T> clazz, T value)
      Sets a value to be associated with a given class in this context.
      Parameters:
      clazz - The class to store a value for
      value - The value to be stored
      See Also:

    • modify

      void modify(String name, Object value)
      Modifies the value to be associated with the given name.

      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.

      Parameters:
      name - the name to store a value for
      value - the value to be stored, or a ContextFunction that can return the stored value.
      Throws:
      IllegalArgumentException - if the variable has not been declared as modifiable

    • modify

      <T> void modify(Class<T> clazz, T value)
      Modifies the value to be associated with the given class.
      Parameters:
      clazz - The class to store a value for
      value - The value to be stored
      Throws:
      IllegalArgumentException - if the variable has not been declared as modifiable
      See Also:

    • declareModifiable

      void declareModifiable(String name)
      Declares the named value as modifiable by descendants of this context. If the value does not exist in this context, a null value added for the name.
      Parameters:
      name - the name to be declared as modifiable by descendants

    • declareModifiable

      void declareModifiable(Class<?> clazz)
      Declares the value for the class as modifiable by descendants of this context. If the value does not exist in this context, a null value added for the class.
      Parameters:
      clazz - the class to be declared as modifiable by descendants
      See Also:

    • processWaiting

      void processWaiting()
      Process waiting updates for listeners that support batch notifications.

    • createChild

      IEclipseContext createChild()
      Creates a new context using this context as a parent. A child should be disposed with dispose() when no longer needed.
      Returns:
      a new child context

    • createChild

      IEclipseContext createChild(String name)
      Creates a new named context using this context as a parent. A child should be disposed with dispose() when no longer needed.
      Parameters:
      name - the name to identify this context
      Returns:
      a new child context

    • getParent

      IEclipseContext getParent()
      Returns parent context, or null if there is no parent context.
      Returns:
      the parent context, or null

    • setParent

      void setParent(IEclipseContext parentContext)
      Sets parent context. Pass in null to indicate that this context has no parent.
      Parameters:
      parentContext - the new parent context, or null to indicate that this context has no parent

    • activate

      void activate()
      Marks this context as active.

    • deactivate

      void deactivate()
      Marks this context as inactive.

    • activateBranch

      void activateBranch()
      Marks this context and its parent contexts as active.

    • getActiveChild

      IEclipseContext getActiveChild()
      Returns active child for this context. May return null if there are no active children.
      Returns:
      active child context or null

    • getActiveLeaf

      IEclipseContext getActiveLeaf()
      Follows active child chain to return the active leaf for this context. May return the context itself if it has no active children.
      Returns:
      leaf active context

    • dispose

      void dispose()
      Disposes of this object. If this object is already disposed this method will have no effect.

    • getActive

      <T> T getActive(Class<T> clazz)
      Returns the value stored on the active leaf node of the context's tree.

      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).

      Parameters:
      clazz - the class that needs to be found in the active context
      Returns:
      an object corresponding to the given class, or null
      See Also:

    • getActive

      Object getActive(String name)
      Returns the named value stored on the active leaf node of the context's tree.

      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).

      Parameters:
      name - the name of the value to return
      Returns:
      an object corresponding to the given name, or null
      See Also: