Package net.algart.contexts

Interface Context

All Known Subinterfaces:
ArrayMemoryContext, ArrayThreadPoolContext, CurrentFolderContext, InterruptionContext, ProgressUpdater, RectangleUpdater, StatusUpdater
All Known Implementing Classes:
AbstractContext, DefaultContext, SubContext, SubtaskContext
public interface Context

Execution context for any modules.

This interface is an universal concept allowing modules to request almost any information, that, as supposed, describes an execution context of some module. The concrete kinds of such information depend on the module nature. For example, long-working mathematical algorithm may need access to some GUI component that will allow it to show executiong percents. Another example: a module, that creates temporary files for storing large data, may need to know the directory for such files.

There are two related concepts, traditionally used in algorithms and other modules.

  • Algorithm parameters. They can be passed to the algorithm as method arguments or as settings of the class instance. Usually, all parameters are absolutely necessary for performing the task.
  • Global application settings or even global OS settings. They may be passed to the algorithm via system properties (System.getProperty) or environment variables (System.getenv). The global directory for temporary files is a good example. Another example: behavior of net.algart.arrays package can be customized via several special system properties.

The context is an intermediate layer between these two concepts.

Unlike algorithm parameters, the context information is not directly passed to the module. Usually the programmer, who calls some complex method, supporting the contexts, should not think over and may even not know about all contextual information passed via the context. The programmer just need to pass (as an argument of the method) some instance of this Context interface, usually provided by the application. Unlike algorithm parameters, the context should not determine the final results of execution. But it may clarify the behavior of methods: for example, may allow them to show execution progress or specify the directory for temporary files. Some modules may work correctly without any context (when null is passed as the Context argument). Other modules may require some context providing the necessary information. The requirements to the context, passed to some method, are the part of the module contract and must be specified in Javadoc.

Unlike global settings, a large application may use several different contexts. For example, if there are several application windows, and some long-working algorithm may be executed "inside" a window, the application may pass to the algorithm a context, specific for a window and allowing to show the executing progress bar in the corresponding window.

This interface defines a maximally abstract context, that doesn't allow to retrieve useful information. But its basic as(Class) method allows to get inheritors of this interface — so-called specific contexts, that have additional methods accessing to different context information. This package offers the following "standard" specific contexts: InterruptionContext, ArrayMemoryContext, ArrayThreadPoolContext, StatusUpdater, ProgressUpdater, RectangleUpdater. There is also the DefaultContext class, simplifying implementation of concrete contexts, and SubContext class, allowing to create a new context on the base of existing one.

A usage example:

 void someComplexAlgorithm(Context context, some other arguments...) {
     ProgressUpdater pu = context.as(ProgressUpdater.class);
     . . .
     for (int k = 0; k < n; k++) { // the main long-working loop
         . . .
         pu.updateProgress((k + 1.0) / n, k == n - 1);
     }
  
     . . .
 }
Author:
Daniel Alievsky

  • Method Summary

    Modifier and Type
    Method
    Description
    <T extends Context>
    T
    as(Class<T> contextClass)
    Retrieves a specific context according to the passed context class or throws UnsupportedContextException if this context cannot serve this request.
    boolean
    is(Class<? extends Context> contextClass)
    Returns true if this context class can be processed by as(Class) method.

  • Method Details

    • as

      <T extends Context> T as(Class<T> contextClass)
      Retrieves a specific context according to the passed context class or throws UnsupportedContextException if this context cannot serve this request. The contextClass argument is an interface, that will be implemented by the returned context, or (rarely) a class or superclass of the returned context.

      If this instance already implements the required contextClass (more precisely, if contextClass.isAssignableFrom(thisInstance.getClass())), this method usually returns a reference to this instance. In particular, it's true for all context implementations provided by this package.

      If contextClass is null or is not an inheritor of Context interface, this method throws an exception.

      Parameters:
      contextClass - the class of returned object (or superclass, or implemented interface).
      Returns:
      the required context.
      Throws:
      NullPointerException - if contextClass is null.
      IllegalArgumentException - if contextClass does not extends or implements Context interface.
      UnsupportedContextException - if this context cannot serve the request.
      See Also:

    • is

      boolean is(Class<? extends Context> contextClass)
      Returns true if this context class can be processed by as(Class) method. Returns false if and only if contextClass==null, contextClass is not an inheritor of Context interface or the corresponding call as(contextClass) throws UnsupportedContextException.
      Parameters:
      contextClass - the class or interface of a context.
      Returns:
      true if this context class can be processed by as(Class) method.
      See Also: