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

    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 String TOPIC_DISPOSE
      Topic for sending an event via EventAdmin to inform about the disposal of an IEclipseContext.
    • Method Summary

      All Methods Instance Methods Abstract Methods 
      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 Detail

      • TOPIC_DISPOSE

        static final String TOPIC_DISPOSE
        Topic for sending an event via EventAdmin to inform about the disposal of an IEclipseContext.
        Since:
        1.6
        See Also:
        Constant Field Values
    • Method Detail

      • 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:
        containsKey(String)
      • 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:
        get(String)
      • 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:
        getLocal(String)
      • 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:
        remove(String)
      • 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:
        RunAndTrack
      • 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:
        set(String, Object)
      • 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:
        modify(String, Object)
      • 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:
        declareModifiable(String)
      • 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.
        Returns:
        a new child context
      • createChild

        IEclipseContext createChild​(String name)
        Creates a new named context using this context as a parent.
        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:
        getActiveLeaf()
      • 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:
        getActiveLeaf()