agi.foundation.access

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

Class AccessConstraint

java.lang.Object

agi.foundation.infrastructure.DefinitionalObject

agi.foundation.access.AccessQuery

agi.foundation.access.AccessConstraint

All Implemented Interfaces:

ICloneWithContext, IEnumerateDependencies, IEquatableDefinition, IFreezable

Direct Known Subclasses:

AlwaysSatisfiedLinkConstraint, CartographicZoneConstraint, CentralBodyEllipticCylindricalAccessConstraint, CentralBodyLayeredProjectedVolumeAccessConstraint, CentralBodyObstructionConstraint, CentralBodySurfaceRegionConstraint, CentralBodySurfaceRegionSensorVolumeConstraint, CircularAccessConstraint, MinimumMaximumAccessConstraint, SensorVolumeConstraint, TerrainLineOfSightConstraint

public abstract class AccessConstraint
extends AccessQuery

A constraint between two objects. Constraints have a function (preferably continuous near f(x)=0) which is their degree of satisfaction. This allows the exact start or end of the interval during which the constraint is satisfied to be computed.

There are two types of AccessConstraints, those that implement ILinkConstraint and those that implement ISingleObjectConstraint.

ISingleObjectConstraints like AltitudeConstraint have a ConstrainedObject (get / set) property that must be set before the AccessEvaluator is created.

ILinkConstraints like ElevationAngleConstraint have two properties that must be set. The first is ConstrainedLink (get / set), that must be set to an instance of LinkInstantaneous or LinkSpeedOfLight. The second is ConstrainedLinkEnd (get / set) which must be set to an enumeration of LinkRole.

Some AccessConstraints that implement ILinkConstraint, such as CentralBodyObstructionConstraint do not use ConstrainedLinkEnd, as the Constraint applies to the Link as a whole instead of being dependent on a single Platform.

AccessConstraints that are attached to AccessComputations do not need to have their ConstrainedLink, ConstrainedLinkEnd, or ConstrainedObject properties set. Instead set the Transmitter (get / set), and Receiver (get / set) properties and add the desired constraints to the ReceiverConstraints (get) or TransmitterConstraints (get) collections. The appropriate links will be created and assigned behind the scenes.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	AccessConstraint() Initializes a new instance.
protected	AccessConstraint(AccessConstraint existingInstance, CopyContext context) Initializes a new instance as a copy of an existing instance.

Method Summary

Modifier and Type	Method and Description
abstract void	buildQueryEvaluator(ConstraintQueryBuilder builder, EvaluatorGroup group) Builds a query evaluator from this constraint.
protected abstract boolean	checkForSameDefinition(AccessConstraint other) Checks to determine if another instance has the same definition as this instance and returns true if it does.
protected boolean	checkForSameDefinition(AccessQuery other) Checks to determine if another instance has the same definition as this instance and returns true if it does.
protected int	computeCurrentDefinitionHashCode() Computes a hash code based on the current properties of this object.
void	enumerateDependencies(DependencyEnumerator enumerator) Enumerates the dependencies of this object by calling DependencyEnumerator#enumerate(T) for each object that this object directly depends upon.
protected void	freezeAggregatedObjects() Called by DefinitionalObject.freeze() to also freeze any objects that are considered to be a part of this object.
AccessConstraintApplicability	getApplicability() Gets the Access situation in which this constraint applies.
int	getEvaluationOrder() Gets a number indicating the evaluation order of this constraint relative to other constraints.
AccessEvaluator	getEvaluator(IServiceProvider timeObserver, EvaluatorGroup group) Gets an evaluator that can be used to evaluate this query for a given time or for intervals of time.
JulianDateFunctionSampling	getSampling() Gets an instance describing how this constraint is to be sampled.
void	setApplicability(AccessConstraintApplicability value) Sets the Access situation in which this constraint applies.
void	setEvaluationOrder(int value) Sets a number indicating the evaluation order of this constraint relative to other constraints.
AccessQuery	toDisjunctiveNormalForm() Transforms this query to disjunctive normal form (DNF).

Methods inherited from class agi.foundation.access.AccessQuery

and, and, anyPath, anyPath, anyPath, anyPath, anyPath, anyPath, atLeastN, atMostN, checkForSameDefinition, exactlyN, fromObject, fromObjectAllowNoConstraints, getDebuggingLogger, getEvaluator, getEvaluator, not, or, or, setDebuggingLogger

Methods inherited from class agi.foundation.infrastructure.DefinitionalObject

areSameDefinition, areSameDefinition, areSameDefinition, areSameDefinition, areSameDefinition, clone, collectionItemsAreSameDefinition, collectionItemsAreSameDefinition, collectionItemsAreSameDefinition, dictionaryItemsAreSameDefinition, freeze, getCollectionHashCode, getCollectionHashCode, getCollectionHashCode, getDefinitionHashCode, getDefinitionHashCode, getDefinitionHashCode, getDefinitionHashCode, getDefinitionHashCode, getDefinitionHashCode, getDictionaryHashCode, getIsFrozen, isSameDefinition, throwIfFrozen

Methods inherited from class java.lang.Object

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

Constructor Detail

AccessConstraint

protected AccessConstraint()

Initializes a new instance.

AccessConstraint

protected AccessConstraint(@Nonnull
                           AccessConstraint 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

checkForSameDefinition

protected final boolean checkForSameDefinition(AccessQuery other)

Checks to determine if another instance has the same definition as this instance and returns true if it does. Derived classes MUST override this method and check all new fields introduced by the derived class for definitional equivalence. It is NOT necessary to check base class fields because the base class will already have done that. When overriding this method, you should NOT call the base implementation because it will return false for all derived-class instances. Derived classes should check the type of other to preserve the symmetric nature of IEquatableDefinition.isSameDefinition(java.lang.Object).

Specified by:

checkForSameDefinition in class AccessQuery

Parameters:

other - The other instance to compare to this one.

Returns:

true if the two objects are defined equivalently; otherwise false.

checkForSameDefinition

protected abstract boolean checkForSameDefinition(AccessConstraint other)

Checks to determine if another instance has the same definition as this instance and returns true if it does. Derived classes MUST override this method and check all new fields introduced by the derived class for definitional equivalence. It is NOT necessary to check base class fields because the base class will already have done that. When overriding this method, you should NOT call the base implementation because it will return false for all derived-class instances. Derived classes should check the type of other to preserve the symmetric nature of IEquatableDefinition.isSameDefinition(java.lang.Object).

Parameters:

other - The other instance to compare to this one.

Returns:

true if the two objects are defined equivalently; otherwise false.

computeCurrentDefinitionHashCode

protected int computeCurrentDefinitionHashCode()

Computes a hash code based on the current properties of this object. Derived classes MUST override this method and compute a hash code that combines: a unique hash code seed, the base implementation result, and the hash codes of all new fields introduced by the derived class which are used in the AccessConstraint.checkForSameDefinition(agi.foundation.access.AccessQuery) method.

Overrides:

computeCurrentDefinitionHashCode in class AccessQuery

Returns:

The computed hash code.

enumerateDependencies

public void enumerateDependencies(DependencyEnumerator enumerator)

Enumerates the dependencies of this object by calling DependencyEnumerator#enumerate(T) for each object that this object directly depends upon. Derived classes which contain additional dependencies MUST override this method, call the base implementation, and enumerate dependencies introduced by the derived class.

Specified by:

enumerateDependencies in interface IEnumerateDependencies

Overrides:

enumerateDependencies in class DefinitionalObject

Parameters:

enumerator - The enumerator that is informed of the dependencies of this object.

freezeAggregatedObjects

protected void freezeAggregatedObjects()

Called by DefinitionalObject.freeze() to also freeze any objects that are considered to be a part of this object. Derived classes which contain additional aggregated objects MUST override this method, call the base implementation, and freeze aggregated objects introduced by the derived class. The objects that need to be frozen in this method are frequently created in this object's constructor and are not settable via properties.

Overrides:

freezeAggregatedObjects in class DefinitionalObject

getApplicability

@Nonnull
public final AccessConstraintApplicability getApplicability()

Gets the Access situation in which this constraint applies.

setApplicability

public final void setApplicability(@Nonnull
                                   AccessConstraintApplicability value)

Sets the Access situation in which this constraint applies.

getEvaluationOrder

public int getEvaluationOrder()

Gets a number indicating the evaluation order of this constraint relative to other constraints. All constraints involved in an AccessComputation or that share a common parent (e.g. AccessQueryAnd or AccessQueryOr) in an AccessQuery are sorted by this value before being evaluated in ascending order, so constraints with a lower evaluation order are evaluated earlier than constraints with a higher evaluation order.

Specified by:

getEvaluationOrder in class AccessQuery

Returns:

The suggested evaluation order.

setEvaluationOrder

public final void setEvaluationOrder(int value)

Sets a number indicating the evaluation order of this constraint relative to other constraints. All constraints involved in an AccessComputation or that share a common parent (e.g. AccessQueryAnd or AccessQueryOr) in an AccessQuery are sorted by this value before being evaluated in ascending order, so constraints with a lower evaluation order are evaluated earlier than constraints with a higher evaluation order.

getSampling

@Nonnull
public final JulianDateFunctionSampling getSampling()

Gets an instance describing how this constraint is to be sampled.

buildQueryEvaluator

public abstract void buildQueryEvaluator(@Nonnull
                                         ConstraintQueryBuilder builder,
                                         @Nonnull
                                         EvaluatorGroup group)

Builds a query evaluator from this constraint.

Parameters:

builder - The builder instance to use to build the evaluator.

group - The evaluator group in which to create individual constraint function evaluators.

getEvaluator

public final AccessEvaluator getEvaluator(IServiceProvider timeObserver,
                                          EvaluatorGroup group)

Gets an evaluator that can be used to evaluate this query for a given time or for intervals of time.

Specified by:

getEvaluator in class AccessQuery

Parameters:

timeObserver - The IServiceProvider time observer to use when evaluating this query.

group - The group with which to associate the new evaluator. By grouping evaluators that are often evaluated at the same Julian dates, common computations can be performed only once for the entire group instead of multiple times for each evaluator.

Returns:

The evaluator.

toDisjunctiveNormalForm

public AccessQuery toDisjunctiveNormalForm()

Transforms this query to disjunctive normal form (DNF).

Specified by:

toDisjunctiveNormalForm in class AccessQuery

Returns:

An equivalent query expressed in disjunctive normal form (DNF).