agi.foundation.access

(agi.foundation.core-2023r1.jar)

Class AccessQuery

java.lang.Object

agi.foundation.infrastructure.DefinitionalObject

agi.foundation.access.AccessQuery

All Implemented Interfaces:

ICloneWithContext, IEnumerateDependencies, IEquatableDefinition, IFreezable

Direct Known Subclasses:

AccessConstraint, AccessQueryAnd, AccessQueryAtLeastN, AccessQueryAtMostN, AccessQueryExactlyN, AccessQueryNot, AccessQueryOr, AccessQueryStartAndMaintain, AccessQueryTrackedSatellite

public abstract class AccessQuery
extends DefinitionalObject

A query that determines whether or not Access exists for a given time or for intervals of time.

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method and Description
static AccessQueryAnd	and(AccessQuery... queries) Creates a query that is satisfied whenever all of its sub-queries are satisfied.
static AccessQueryAnd	and(AccessQuery first, AccessQuery second) Combines two queries using a logical AND operation.
static AccessQuery	anyPath(IServiceProvider transmitter, IServiceProvider receiver, int maximumLength, IServiceProvider... links) Creates a query which is satisfied whenever any path exists between a given transmitter and receiver.
static <T extends IServiceProvider> AccessQuery	anyPath(IServiceProvider transmitter, IServiceProvider receiver, int maximumLength, Iterable<T> links) Creates a query which is satisfied whenever any path exists between a given transmitter and receiver.
static AccessQuery	anyPath(IServiceProvider transmitter, IServiceProvider receiver, int maximumLength, LinkGraph linkGraph) Creates a query which is satisfied whenever any path exists between a given transmitter and receiver.
static AccessQuery	anyPath(IServiceProvider transmitter, IServiceProvider receiver, IServiceProvider... links) Creates a query which is satisfied whenever any path exists between a given transmitter and receiver.
static <T extends IServiceProvider> AccessQuery	anyPath(IServiceProvider transmitter, IServiceProvider receiver, Iterable<T> links) Creates a query which is satisfied whenever any path exists between a given transmitter and receiver.
static AccessQuery	anyPath(IServiceProvider transmitter, IServiceProvider receiver, LinkGraph linkGraph) Creates a query which is satisfied whenever any path exists between a given transmitter and receiver.
static AccessQueryAtLeastN	atLeastN(int n, AccessQuery... queries) Creates a query that is satisfied whenever at least N of the specified sub-queries are satisfied.
static AccessQueryAtMostN	atMostN(int n, AccessQuery... queries) Creates a query that is satisfied whenever no more than N of the specified sub-queries are satisfied.
protected abstract boolean	checkForSameDefinition(AccessQuery other) Checks to determine if another instance has the same definition as this instance and returns true if it does.
protected boolean	checkForSameDefinition(DefinitionalObject 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.
static AccessQueryExactlyN	exactlyN(int n, AccessQuery... queries) Creates a query that is satisfied whenever exactly N of the specified sub-queries are satisfied.
static AccessQuery	fromObject(IServiceProvider constrainedObject) Constructs an access query from the constraints applied to a given object.
static AccessQuery	fromObjectAllowNoConstraints(IServiceProvider constrainedObject) Constructs an access query from the constraints applied to a given object or link.
HierarchicalLogger	getDebuggingLogger() Gets a logger to which debugging information will be written.
abstract int	getEvaluationOrder() Gets the suggested evaluation order of this query.
AccessEvaluator	getEvaluator() Gets an evaluator that can be used to evaluate this query for a given time or for intervals of time.
AccessEvaluator	getEvaluator(IServiceProvider timeObserver) Gets an evaluator that can be used to evaluate this query for a given time or for intervals of time.
abstract 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.
static AccessQueryNot	not(AccessQuery query) Inverts a query using a logical NOT operation.
static AccessQueryOr	or(AccessQuery... queries) Creates a query that is satisfied whenever any of its sub-queries are satisfied.
static AccessQueryOr	or(AccessQuery first, AccessQuery second) Combines two queries using a logical OR operation.
void	setDebuggingLogger(HierarchicalLogger value) Sets a logger to which debugging information will be written.
abstract AccessQuery	toDisjunctiveNormalForm() Transforms this query to disjunctive normal form (DNF).

Methods inherited from class agi.foundation.infrastructure.DefinitionalObject

areSameDefinition, areSameDefinition, areSameDefinition, areSameDefinition, areSameDefinition, clone, collectionItemsAreSameDefinition, collectionItemsAreSameDefinition, collectionItemsAreSameDefinition, dictionaryItemsAreSameDefinition, enumerateDependencies, freeze, freezeAggregatedObjects, 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

AccessQuery

protected AccessQuery()

Initializes a new instance.

AccessQuery

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

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

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 AccessQuery.checkForSameDefinition(agi.foundation.infrastructure.DefinitionalObject) method.

Overrides:

computeCurrentDefinitionHashCode in class DefinitionalObject

Returns:

The computed hash code.

getEvaluationOrder

public abstract int getEvaluationOrder()

Gets the suggested evaluation order of this query. Queries that hold sub-queries (such as an AccessQueryAnd) generally evaluate their sub-queries in ascending order of this value, so queries with a lower evaluation order are evaluated earlier than queries with a higher evaluation order.

Returns:

The suggested evaluation order.

getEvaluator

@Nonnull
public final AccessEvaluator getEvaluator()

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

This attempts to create an evaluator without a specified time observer, an exception will be thrown if the AccessQuery has time delays or other features that require a specified observer.

Returns:

The evaluator.

getEvaluator

@Nonnull
public final AccessEvaluator getEvaluator(IServiceProvider timeObserver)

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

Parameters:

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

Returns:

The evaluator.

getEvaluator

@Nonnull
public abstract AccessEvaluator getEvaluator(IServiceProvider timeObserver,
                                                       @Nonnull
                                                       EvaluatorGroup group)

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

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

@Nonnull
public abstract AccessQuery toDisjunctiveNormalForm()

Transforms this query to disjunctive normal form (DNF).

Returns:

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

getDebuggingLogger

public final HierarchicalLogger getDebuggingLogger()

Gets a logger to which debugging information will be written.

setDebuggingLogger

public final void setDebuggingLogger(HierarchicalLogger value)

Sets a logger to which debugging information will be written.

and

public static AccessQueryAnd and(AccessQuery first,
                                 AccessQuery second)

Combines two queries using a logical AND operation. The resulting query will only be satisfied when both of the input queries are satisfied.

Parameters:

first - The first query.

second - The second query.

Returns:

A new query which is a logical AND of the first and second queries.

or

public static AccessQueryOr or(AccessQuery first,
                               AccessQuery second)

Combines two queries using a logical OR operation. The resulting query will only be satisfied when either of the input queries are satisfied.

Parameters:

first - The first query.

second - The second query.

Returns:

A new query which is a logical OR of the first and second queries.

not

public static AccessQueryNot not(AccessQuery query)

Inverts a query using a logical NOT operation. The new query is satisfied whenever the original is not.

Parameters:

query - The query to invert.

Returns:

The inverted query.

fromObject

public static AccessQuery fromObject(IServiceProvider constrainedObject)

Constructs an access query from the constraints applied to a given object. The given object can be a link, such as LinkInstantaneous or LinkSpeedOfLight, or it can be a single object, such as Platform.

This method assembles a query from the constraints attached to the specified object using IAccessConstraintsService. This service can be added to a Platform, a LinkInstantaneous, or a LinkSpeedOfLight by adding the AccessConstraintsExtension to the object's Extensions (get) collection. If the specified constrainedObject is a link, the returned query will also include constraints attached to the Transmitter (get) and Receiver (get), if any.

In all cases, this method attempts to infer the objects to which the constraints apply from their context. For example, if the Transmitter end of a link specified as the constrainedObject parameter has an ElevationAngleConstraint attached to it, the constraint's ConstrainedLink (get / set) property will be set to the constrainedObject link and the ConstrainedLinkEnd (get / set) property will be set to LinkRole.TRANSMITTER. Instead of modifying the constraints directly, this method will copy them and include the copies in the returned query.

Parameters:

constrainedObject - The link or single object from which to construct a query.

Returns:

The query.

Throws:

IllegalStateException - The constrainedObject does not have any constraints associated with it.

fromObjectAllowNoConstraints

public static AccessQuery fromObjectAllowNoConstraints(@Nonnull
                                                       IServiceProvider constrainedObject)

Constructs an access query from the constraints applied to a given object or link. The specified object is allowed to not have any constraints, in which case null will be returned. This method is identical to AccessQuery.fromObject(agi.foundation.IServiceProvider) except that it will not throw when the object does not provide the IAccessConstraintsService.

Parameters:

constrainedObject - The link or single object from which to construct a query.

Returns:

The query, or null if the object does not have any constraints.

anyPath

public static AccessQuery anyPath(IServiceProvider transmitter,
                                  IServiceProvider receiver,
                                  IServiceProvider... links)

Creates a query which is satisfied whenever any path exists between a given transmitter and receiver. The possible paths are deduced from a list of links.

Parameters:

transmitter - The transmitter.

receiver - The receiver.

links - The list of links from which the possible paths are deduced.

Returns:

A query that is satisfied whenever a path exists.

anyPath

public static AccessQuery anyPath(IServiceProvider transmitter,
                                  IServiceProvider receiver,
                                  int maximumLength,
                                  IServiceProvider... links)

Creates a query which is satisfied whenever any path exists between a given transmitter and receiver. The possible paths are deduced from a list of links.

Parameters:

transmitter - The transmitter.

receiver - The receiver.

maximumLength - The maximum length of a path between the transmitter and receiver, expressed as the number of links traversed. To allow paths of any length, pass Integer.MAX_VALUE for this argument.

links - The list of links from which the possible paths are deduced.

Returns:

A query that is satisfied whenever a path exists.

anyPath

public static <T extends IServiceProvider> AccessQuery anyPath(IServiceProvider transmitter,
                                                               IServiceProvider receiver,
                                                               Iterable<T> links)

Creates a query which is satisfied whenever any path exists between a given transmitter and receiver. The possible paths are deduced from a list of links.

Type Parameters:

T - The type used to represent a link.

Parameters:

transmitter - The transmitter.

receiver - The receiver.

links - The list of links from which the possible paths are deduced.

Returns:

A query that is satisfied whenever a path exists.

anyPath

public static <T extends IServiceProvider> AccessQuery anyPath(IServiceProvider transmitter,
                                                               IServiceProvider receiver,
                                                               int maximumLength,
                                                               @Nonnull
                                                               Iterable<T> links)

Creates a query which is satisfied whenever any path exists between a given transmitter and receiver. The possible paths are deduced from a list of links.

Type Parameters:

T - The type used to represent a link.

Parameters:

transmitter - The transmitter.

receiver - The receiver.

maximumLength - The maximum length of a path between the transmitter and receiver, expressed as the number of links traversed. To allow paths of any length, pass Integer.MAX_VALUE for this argument.

links - The list of links from which the possible paths are deduced.

Returns:

A query that is satisfied whenever a path exists.

anyPath

public static AccessQuery anyPath(IServiceProvider transmitter,
                                  IServiceProvider receiver,
                                  @Nonnull
                                  LinkGraph linkGraph)

Creates a query which is satisfied whenever any path exists between a given transmitter and receiver. The possible paths are defined by a LinkGraph.

Parameters:

transmitter - The transmitter.

receiver - The receiver.

linkGraph - The graph of links from which the possible paths between the transmitter and receiver are computed.

Returns:

A query that is satisfied whenever a path exists.

anyPath

public static AccessQuery anyPath(IServiceProvider transmitter,
                                  IServiceProvider receiver,
                                  int maximumLength,
                                  @Nonnull
                                  LinkGraph linkGraph)

Creates a query which is satisfied whenever any path exists between a given transmitter and receiver. The possible paths are defined by a LinkGraph.

Parameters:

transmitter - The transmitter.

receiver - The receiver.

maximumLength - The maximum length of a path between the transmitter and receiver, expressed as the number of links traversed. To allow paths of any length, pass Integer.MAX_VALUE for this argument.

linkGraph - The graph of links from which the possible paths between the transmitter and receiver are computed.

Returns:

A query that is satisfied whenever a path exists.

atLeastN

@Nonnull
public static AccessQueryAtLeastN atLeastN(int n,
                                                     @Nonnull
                                                     AccessQuery... queries)

Creates a query that is satisfied whenever at least N of the specified sub-queries are satisfied.

Parameters:

n - The number of the given queries that must be satisfied for the returned query to be satisfied.

queries - The queries, at least n of which must be satisfied.

Returns:

The new query.

atMostN

@Nonnull
public static AccessQueryAtMostN atMostN(int n,
                                                   @Nonnull
                                                   AccessQuery... queries)

Creates a query that is satisfied whenever no more than N of the specified sub-queries are satisfied.

Parameters:

n - The maximum number of the given queries that can be satisfied for the returned query to be satisfied.

queries - The queries, at most n of which can be satisfied.

Returns:

The new query.

exactlyN

@Nonnull
public static AccessQueryExactlyN exactlyN(int n,
                                                     @Nonnull
                                                     AccessQuery... queries)

Creates a query that is satisfied whenever exactly N of the specified sub-queries are satisfied.

Parameters:

n - The number of the given queries that can be satisfied for the returned query to be satisfied.

queries - The queries, exactly n of which must be satisfied.

Returns:

The new query.

and

@Nonnull
public static AccessQueryAnd and(@Nonnull
                                           AccessQuery... queries)

Creates a query that is satisfied whenever all of its sub-queries are satisfied.

Parameters:

queries - The queries, all of which must be satisfied.

Returns:

The new query.

or

@Nonnull
public static AccessQueryOr or(@Nonnull
                                         AccessQuery... queries)

Creates a query that is satisfied whenever any of its sub-queries are satisfied.

Parameters:

queries - The queries, any of which can be satisfied.

Returns:

The new query.