agi.foundation.infrastructure

(agi.foundation.core-2024r3.jar)

Class CalculationContext

java.lang.Object

agi.foundation.infrastructure.CalculationContext

All Implemented Interfaces:

ICloneWithContext, IThreadAware

public class CalculationContext
extends Object
implements IThreadAware

The context in which calculations are performed. This holds a number of facets which describe the problem. Facets can include things like central bodies and leap seconds. To use a facet, call the facet's static method that returns the context. Avoid calling CalculationContext.getFacet(int) directly.

CalculationContexts start off empty. It is up to each facet to decide what to do when the facet does not yet exist in the context. See the documentation for each facet for more information about that specific facet's behavior.

Constructor Summary

Constructors

Modifier	Constructor and Description
	CalculationContext() Initializes a new calculation context with default facets.
protected	CalculationContext(CalculationContext existingInstance, CopyContext context) Initializes a new instance as a copy of an existing instance.

Method Summary

Modifier and Type	Method and Description
void	addFacet(int facetId, CalculationContextFacet facet) Adds a facet to the context.
Object	clone(CopyContext context) Clones this object using the specified context.
static ICalculationContextStorageStrategy	getCalculationContextStorageStrategy() Gets the strategy that is used to store calculation contexts.
static CalculationContext	getDefaultForNewContexts() Gets the calculation context to use for contexts that do not yet have a calculation context.
CalculationContextFacet	getFacet(int facetId) Gets the facet with the given ID.
static CalculationContext	getInstance() Gets the current calculation context.
boolean	getIsThreadSafe() Gets a value indicating whether the methods on this instance are safe to call from multiple threads simultaneously.
static int	getNextFacetId(CreateCalculationContextFacetCallback creationCallback) Gets the next available facet ID.
static void	setCalculationContextStorageStrategy(ICalculationContextStorageStrategy value) Sets the strategy that is used to store calculation contexts.
static void	setDefaultForNewContexts(CalculationContext value) Sets the calculation context to use for contexts that do not yet have a calculation context.
static void	setInstance(CalculationContext value) Sets the current calculation context.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

CalculationContext

public CalculationContext()

Initializes a new calculation context with default facets.

CalculationContext

protected CalculationContext(@Nonnull
                             CalculationContext existingInstance,
                             @Nonnull
                             CopyContext context)

Initializes a new instance as a copy of an existing instance.

See ICloneWithContext.clone(CopyContext) for more information about how to implement this constructor in a derived class.

Parameters:

existingInstance - The existing instance to copy.

context - A CopyContext that controls the depth of the copy.

Throws:

ArgumentNullException - Thrown when existingInstance or context is null.

Method Detail

clone

public final Object clone(CopyContext context)

Clones this object using the specified context.

This method should be implemented to call a copy constructor on the class of the object being cloned. The copy constructor should take the CopyContext as a parameter in addition to the existing instance to copy. The copy constructor should first call CopyContext.addObjectMapping(T, T) to identify the newly constructed instance as a copy of the existing instance. It should then copy all fields, using CopyContext.updateReference(T) to copy any reference fields.

A typical implementation of ICloneWithContext:

public static class MyClass implements ICloneWithContext {
    public MyClass(MyClass existingInstance, CopyContext context) {
        context.addObjectMapping(existingInstance, this);
        someReference = context.updateReference(existingInstance.someReference);
    }

    @Override
    public final Object clone(CopyContext context) {
        return new MyClass(this, context);
    }

    private Object someReference;
}

In general, all fields that are reference types should be copied with a call to CopyContext.updateReference(T). There are a couple of exceptions:

1. Fields that are aggregate parts of the object should always be copied. A referenced object is an aggregate if properties or methods on the object being copied can modify the externally-visible value of the referenced object.
2. If the semantics of the referenced object require that it have a single parent, owner, context, etc., and the object being copied is that parent, owner, or context, then the referenced object should always be copied.

If one of these exceptions applies, the CopyContext should be given an opportunity to update the reference before the reference is copied explicitly. Use CopyContext.updateReference(T) to update the reference. If CopyContext.updateReference(T) returns the original object, indicating that the context does not have a replacement registered, then copy the object manually by invoking a Clone method, a copy constructor, or by manually constructing a new instance and copying the values.

alwaysCopy = context.updateReference(existingInstance.alwaysCopy);
if (existingInstance.alwaysCopy != null && alwaysCopy == existingInstance.alwaysCopy) {
    alwaysCopy = (AlwaysCopy) existingInstance.alwaysCopy.clone(context);
}

If you are implementing an evaluator (a class that implements IEvaluator), the IEvaluator.updateEvaluatorReferences(agi.foundation.infrastructure.CopyContext) method shares some responsibilities with the copy context constructor. Code duplication can be avoided by doing the following:

1. For references to other evaluators ONLY, simply assign the reference in the constructor instead of calling CopyContext.updateReference(T). You should still call CopyContext.updateReference(T) on any references to non-evaluators.
2. Call IEvaluator.updateEvaluatorReferences(agi.foundation.infrastructure.CopyContext) as the last line in the constructor and pass it the same CopyContext passed to the constructor.
3. Implement IEvaluator.updateEvaluatorReferences(agi.foundation.infrastructure.CopyContext) as normal. See the reference documentation for IEvaluator.updateEvaluatorReferences(agi.foundation.infrastructure.CopyContext) for more information on implementing that method.

public MyClass(MyClass existingInstance, CopyContext context) {
    super(existingInstance, context);
    someReference = context.updateReference(existingInstance.someReference);
    evaluatorReference = existingInstance.evaluatorReference;
    updateEvaluatorReferences(context);
}

@Override
public void updateEvaluatorReferences(CopyContext context) {
    evaluatorReference = context.updateReference(evaluatorReference);
}

@Override
public Object clone(CopyContext context) {
    return new MyClass(this, context);
}

private Object someReference;
private IEvaluator evaluatorReference;

Specified by:

clone in interface ICloneWithContext

Parameters:

context - The context to use to perform the copy.

Returns:

A new instance which is a copy of this object.

getIsThreadSafe

public final boolean getIsThreadSafe()

Gets a value indicating whether the methods on this instance are safe to call from multiple threads simultaneously.

If this property is true, all methods and properties are guaranteed to be thread safe. Conceptually, an object that returns true for this method acts as if there is a lock protecting each method and property such that only one thread at a time can be inside any method or property in the class. In reality, such locks are generally not used and are in fact discouraged. However, the user must not experience any exceptions or inconsistent behavior that would not be experienced if such locks were used.

If this property is false, the behavior when using this class from multiple threads simultaneously is undefined and may include inconsistent results and exceptions. Clients wishing to use multiple threads should call CopyForAnotherThread.copy(T) to get a separate instance of the object for each thread.

Specified by:

getIsThreadSafe in interface IThreadAware

getInstance

public static CalculationContext getInstance()

Gets the current calculation context. By default, each thread has its own context.

setInstance

public static void setInstance(CalculationContext value)

Sets the current calculation context. By default, each thread has its own context.

getCalculationContextStorageStrategy

@Nonnull
public static ICalculationContextStorageStrategy getCalculationContextStorageStrategy()

Gets the strategy that is used to store calculation contexts. The default strategy ensures that each thread has its own context.

setCalculationContextStorageStrategy

public static void setCalculationContextStorageStrategy(@Nonnull
                                                        ICalculationContextStorageStrategy value)

Sets the strategy that is used to store calculation contexts. The default strategy ensures that each thread has its own context.

getDefaultForNewContexts

public static CalculationContext getDefaultForNewContexts()

Gets the calculation context to use for contexts that do not yet have a calculation context. When using the default CalculationContextStorageStrategy (get / set), a context is a thread so this property specifies the calculation context that will be used for new threads that do not yet have a CalculationContext.

setDefaultForNewContexts

public static void setDefaultForNewContexts(CalculationContext value)

Sets the calculation context to use for contexts that do not yet have a calculation context. When using the default CalculationContextStorageStrategy (get / set), a context is a thread so this property specifies the calculation context that will be used for new threads that do not yet have a CalculationContext.

getFacet

@Nullable
public final CalculationContextFacet getFacet(int facetId)

Gets the facet with the given ID.

Parameters:

facetId - The ID of the facet to get.

Returns:

The requested facet, or null if that facet does not currently exist in the context.

addFacet

public final void addFacet(int facetId,
                           CalculationContextFacet facet)

Adds a facet to the context.

Parameters:

facetId - The ID of the facet to add.

facet - The facet to add.

Throws:

ArgumentOutOfRangeException - Thrown when the facetId has not been allocated to any facet type.

getNextFacetId

public static int getNextFacetId(@Nonnull
                                 CreateCalculationContextFacetCallback creationCallback)

Gets the next available facet ID. Each time this method is called a unique ID is returned. It is safe to call this method from multiple threads simultaneously.

Parameters:

creationCallback - A callback to use to create a default instance of this facet.

Returns:

The next facet ID.