agi.foundation.tracking

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

Class TrackingArchive<TEntity extends IEntityIdentifier & IEntityLastUpdate>

java.lang.Object

agi.foundation.tracking.TrackingArchive<TEntity>

Type Parameters:

TEntity - The type of entity to be archived.

All Implemented Interfaces:

IDisposable, AutoCloseable

Direct Known Subclasses:

MemoryArchive

public abstract class TrackingArchive<TEntity extends IEntityIdentifier & IEntityLastUpdate>
extends Object
implements IDisposable

The base for classes that archive tracking data.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	TrackingArchive(TypeLiteral<TEntity> typeLiteralTEntity, TransactionContext context) Initializes a new instance using the provided TransactionContext.
protected	TrackingArchive(TypeLiteral<TEntity> typeLiteralTEntity, TransactionContext context, TrackingTypeArchiverCollection typeArchivers) Initializes a new instance using the provided TransactionContext and a specified collection of type archivers.

Method Summary

Modifier and Type	Method and Description
protected abstract void	archiveEntities(Transaction transaction, Iterable<? extends TEntity> entities) Archives a set of entities.
abstract void	clear() Clears the contents of the archive.
void	dispose() Releases any resources associated with this instance.
protected void	dispose(boolean disposing) Releases any resources associated with this instance.
RawEntityData<TEntity>	getArchivedData(JulianDate start, JulianDate stop, int maximumRecords, String... propertyNames) Retrieves archived properties for all entities over the provided time period.
RawEntityData<TEntity>	getArchivedData(Object entityIdentifier, JulianDate start, JulianDate stop, int maximumRecords, String... propertyNames) Retrieves archived properties for the provided entity over the provided time period.
abstract TimeInterval	getArchivedInterval() Gets the overall interval that exists in the archive for any entity.
abstract TimeInterval	getArchivedInterval(Object entityIdentifier) Gets the overall interval that exists in the archive for the specified entity identifier.
protected abstract Object[]	getArchivedPrimitivePropertyComponents(Iterable<? extends ArchivedProperty> primitivePropertyComponents, JulianDate start, JulianDate stop, int maximumRecords) Retrieves archived primitive property components for all entities over the provided time period.
protected abstract Object[]	getArchivedPrimitivePropertyComponents(Object entityIdentifier, Iterable<? extends ArchivedProperty> primitivePropertyComponents, JulianDate start, JulianDate stop, int maximumRecords) Retrieves archived primitive property components for the provided entity over the provided time period.
TransactionContext	getContext() Gets the context for which to archive entities.
protected void	getEntityPrimitivePropertyComponents(Transaction transaction, TEntity entity, Object[] values) Fills an array with the archived properties of an entity.
boolean	getIsRunning() Gets a value indicating whether the archiver is currently archiving changes to entities in the Context (get).
int	getMaximumQueueLength() Gets the maximum length of the queue of committed transactions to be archived.
<T> DateMotionCollection1<T>	getMotion1(Object entityIdentifier, JulianDate start, JulianDate stop, int maximumPoints, String... propertyNames) Gets time-varying data, such as position and velocity, from the archive.
<T> DateMotionCollection1<T>	getMotion1(Object entityIdentifier, JulianDate start, JulianDate stop, String... properties) Gets time-varying data, such as position and velocity, from the archive.
<T,TDerivative> DateMotionCollection2<T,TDerivative>	getMotion2(Object entityIdentifier, JulianDate start, JulianDate stop, int maximumPoints, String... propertyNames) Gets time-varying data, such as position and velocity, from the archive.
<T,TDerivative> DateMotionCollection2<T,TDerivative>	getMotion2(Object entityIdentifier, JulianDate start, JulianDate stop, String... properties) Gets time-varying data, such as position and velocity, from the archive.
DateMotionCollection2<UnitQuaternion,Cartesian>	getOrientations(Object entityIdentifier, JulianDate start, int maximumPoints) Gets a DateMotionCollection2 representing the archived orientation, rotational velocity and rotational acceleration of the specified entity beginning at the specified time and lasting for the specified duration.
DateMotionCollection2<UnitQuaternion,Cartesian>	getOrientations(Object entityIdentifier, JulianDate start, JulianDate stop) Gets a DateMotionCollection2 representing the archived orientation, rotational velocity and rotational acceleration of the specified entity beginning at the specified time and lasting for the specified duration.
DateMotionCollection2<UnitQuaternion,Cartesian>	getOrientations(Object entityIdentifier, JulianDate start, JulianDate stop, int maximumPoints) Gets a DateMotionCollection2 representing the archived orientation, rotational velocity and rotational acceleration of the specified entity beginning at the specified time and lasting for the specified duration.
DateMotionCollection1<Cartesian>	getPositions(Object entityIdentifier, JulianDate start, int maximumPoints) Gets a DateMotionCollection1 representing the archived position, velocity and acceleration of the specified entity beginning at the specified time and lasting for the specified duration.
DateMotionCollection1<Cartesian>	getPositions(Object entityIdentifier, JulianDate start, JulianDate stop) Gets a DateMotionCollection1 representing the archived position, velocity and acceleration of the specified entity beginning at the specified time and lasting for the specified duration.
DateMotionCollection1<Cartesian>	getPositions(Object entityIdentifier, JulianDate start, JulianDate stop, int maximumPoints) Gets a DateMotionCollection1 representing the archived position, velocity and acceleration of the specified entity beginning at the specified time and lasting for the specified duration.
List<ArchivedProperty>	getPrimitivePropertyComponents() Gets a list of the primitive components of the properties for this entity type.
List<ArchivedProperty>	getProperties() Gets a list of archived properties for this entity type.
TrackingTypeArchiverCollection	getTypeArchivers() Gets the collection of TrackingTypeArchivers that is used to archive the properties of entities.
void	setMaximumQueueLength(int value) Sets the maximum length of the queue of committed transactions to be archived.
void	startWriting() Starts the archiver.
void	stopWriting() Stops the archiver.
void	waitForArchiveQueue() Waits for the currently queued transactions to be archived before returning.
protected void	writingShutdown() Called during TrackingArchive.stopWriting(), after the last call to TrackingArchive.archiveEntities(agi.foundation.Transaction, java.lang.Iterable<? extends TEntity>).
protected void	writingStartup() Called during TrackingArchive.startWriting(), before the first call to TrackingArchive.archiveEntities(agi.foundation.Transaction, java.lang.Iterable<? extends TEntity>).

Methods inherited from class java.lang.Object

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

Methods inherited from interface agi.foundation.compatibility.IDisposable

close

Constructor Detail

TrackingArchive

protected TrackingArchive(TypeLiteral<TEntity> typeLiteralTEntity,
                          @Nonnull
                          TransactionContext context)

Initializes a new instance using the provided TransactionContext. The default collection of type archivers is used.

Parameters:

typeLiteralTEntity - A TypeLiteral object representing the generic type TEntity.

context - The context for which to archive entities.

Throws:

ArgumentNullException - Thrown when context is null.

TrackingArchive

protected TrackingArchive(TypeLiteral<TEntity> typeLiteralTEntity,
                          @Nonnull
                          TransactionContext context,
                          @Nonnull
                          TrackingTypeArchiverCollection typeArchivers)

Initializes a new instance using the provided TransactionContext and a specified collection of type archivers.

Parameters:

typeLiteralTEntity - A TypeLiteral object representing the generic type TEntity.

context - The context for which to archive entities.

typeArchivers - The type archivers to use to archive entity properties.

Throws:

ArgumentNullException - Thrown when context or typeArchivers is null.

Method Detail

dispose

public final void dispose()

Releases any resources associated with this instance.

Specified by:

dispose in interface IDisposable

dispose

protected void dispose(boolean disposing)

Releases any resources associated with this instance.

Parameters:

disposing - true to release both managed and unmanaged resources; false to release only unmanaged resources.

getContext

@Nonnull
public final TransactionContext getContext()

Gets the context for which to archive entities.

getTypeArchivers

@Nonnull
public final TrackingTypeArchiverCollection getTypeArchivers()

Gets the collection of TrackingTypeArchivers that is used to archive the properties of entities. The returned instance should be considered read-only. Attempts to modify the collection of archivers will result in an ObjectFrozenException.

getMaximumQueueLength

public final int getMaximumQueueLength()

Gets the maximum length of the queue of committed transactions to be archived. If transactions are committed at a higher rate than they can be archived, the length of the queue will grow. When it reaches this maximum length, committing threads will block until the archiver catches up. Setting this value too high will result in excessive memory usage. Changes to this value while the archiver IsRunning (get) will not take effect until it is restarted.

setMaximumQueueLength

public final void setMaximumQueueLength(int value)

Sets the maximum length of the queue of committed transactions to be archived. If transactions are committed at a higher rate than they can be archived, the length of the queue will grow. When it reaches this maximum length, committing threads will block until the archiver catches up. Setting this value too high will result in excessive memory usage. Changes to this value while the archiver IsRunning (get) will not take effect until it is restarted.

startWriting

public final void startWriting()

Starts the archiver. After this method is called, all updates to entities in the Context (get) will be archived.

stopWriting

public final void stopWriting()

Stops the archiver. After this method is called, updates to entities in the Context (get) will no longer be archived. This method does not return until the current queue of updates to archive has been processed.

getIsRunning

public final boolean getIsRunning()

Gets a value indicating whether the archiver is currently archiving changes to entities in the Context (get).

getProperties

@Nonnull
public final List<ArchivedProperty> getProperties()

Gets a list of archived properties for this entity type. There is one property in this collection for each property in the entity's EntitySchema.

getPrimitivePropertyComponents

@Nonnull
public final List<ArchivedProperty> getPrimitivePropertyComponents()

Gets a list of the primitive components of the properties for this entity type. Each property in Properties (get) will correspond to one or more properties in this collection. For example, a property in Properties (get) of type JulianDate might have two properties in this collection: an integer called "Day" and a double called "SecondsOfDay". The exact relationship between Properties (get) and this collection is dictated by the TypeArchivers (get) being used by this archive.

getMotion1

public final <T> DateMotionCollection1<T> getMotion1(Object entityIdentifier,
                                                     @Nonnull
                                                     JulianDate start,
                                                     @Nonnull
                                                     JulianDate stop,
                                                     String... properties)

Gets time-varying data, such as position and velocity, from the archive.

Type Parameters:

T - The type of data to retrieve. For example, this would be Cartesian for position and velocity data.

Parameters:

entityIdentifier - The identifier of the entity for which to retrieve data.

start - The earliest time for which to retrieve data.

stop - The latest time for which to retrieve data.

properties - The names of the properties to include in the returned collection. The first string is the name of the property representing the Values (get) of the motion, the second is the name of the property representing the FirstDerivatives (get) of the motion, and so on. To obtain the positions of the entity over time, pass Position as the first property, and Velocity and Acceleration as the successive properties, if applicable.

Returns:

An instance of DateMotionCollection1 representing the requested interval.

getMotion1

@Nonnull
public final <T> DateMotionCollection1<T> getMotion1(Object entityIdentifier,
                                                               @Nonnull
                                                               JulianDate start,
                                                               @Nonnull
                                                               JulianDate stop,
                                                               int maximumPoints,
                                                               String... propertyNames)

Gets time-varying data, such as position and velocity, from the archive.

Type Parameters:

T - The type of data to retrieve. For example, this would be Cartesian for position and velocity data.

Parameters:

entityIdentifier - The identifier of the entity for which to retrieve data.

start - The earliest time for which to retrieve data.

stop - The latest time for which to retrieve data.

maximumPoints - The maximum number of points to return.

propertyNames - The names of the properties to include in the returned collection. The first string is the name of the property representing the Values (get) of the motion, the second is the name of the property representing the FirstDerivatives (get) of the motion, and so on. To obtain the positions of the entity over time, pass Position as the first property, and Velocity and Acceleration as the successive properties, if applicable.

Returns:

An instance of DateMotionCollection1 representing the requested interval.

getMotion2

public final <T,TDerivative> DateMotionCollection2<T,TDerivative> getMotion2(Object entityIdentifier,
                                                                             @Nonnull
                                                                             JulianDate start,
                                                                             @Nonnull
                                                                             JulianDate stop,
                                                                             String... properties)

Gets time-varying data, such as position and velocity, from the archive.

Type Parameters:

T - The type of value data to retrieve. For example, this would be UnitQuaternion for rotation and rotational velocity data.

TDerivative - The type of derivative data to retrieve. For example, this would be Cartesian for rotation and rotational velocity data.

Parameters:

entityIdentifier - The identifier of the entity for which to retrieve data.

start - The earliest time for which to retrieve data.

stop - The latest time for which to retrieve data.

properties - The names of the properties to include in the returned collection. The first string is the name of the property representing the Values (get) of the motion, the second is the name of the property representing the FirstDerivatives (get) of the motion, and so on. To obtain the orientations of the entity over time, pass Orientation as the first property, and RotationalVelocity and RotationalAcceleration as the successive properties, if applicable.

Returns:

An instance of DateMotionCollection2 representing the requested interval.

getMotion2

public final <T,TDerivative> DateMotionCollection2<T,TDerivative> getMotion2(Object entityIdentifier,
                                                                             @Nonnull
                                                                             JulianDate start,
                                                                             @Nonnull
                                                                             JulianDate stop,
                                                                             int maximumPoints,
                                                                             String... propertyNames)

Gets time-varying data, such as position and velocity, from the archive.

Type Parameters:

T - The type of value data to retrieve. For example, this would be UnitQuaternion for rotation and rotational velocity data.

TDerivative - The type of derivative data to retrieve. For example, this would be Cartesian for rotation and rotational velocity data.

Parameters:

entityIdentifier - The identifier of the entity for which to retrieve data.

start - The earliest time for which to retrieve data.

stop - The latest time for which to retrieve data.

maximumPoints - The maximum number of points to return.

propertyNames - The names of the properties to include in the returned collection. The first string is the name of the property representing the Values (get) of the motion, the second is the name of the property representing the FirstDerivatives (get) of the motion, and so on. To obtain the orientations of the entity over time, pass Orientation as the first property, and RotationalVelocity and RotationalAcceleration as the successive properties, if applicable.

Returns:

An instance of DateMotionCollection2 representing the requested interval.

getPositions

public final DateMotionCollection1<Cartesian> getPositions(Object entityIdentifier,
                                                           @Nonnull
                                                           JulianDate start,
                                                           @Nonnull
                                                           JulianDate stop)

Gets a DateMotionCollection1 representing the archived position, velocity and acceleration of the specified entity beginning at the specified time and lasting for the specified duration.

Parameters:

entityIdentifier - The identifier of the entity whose data is to be retrieved.

start - The date of the earliest data point to retrieve.

stop - The time of the last data point to retrieve.

Returns:

A DateMotionCollection1 representing the archived data.

getPositions

public final DateMotionCollection1<Cartesian> getPositions(Object entityIdentifier,
                                                           @Nonnull
                                                           JulianDate start,
                                                           int maximumPoints)

Gets a DateMotionCollection1 representing the archived position, velocity and acceleration of the specified entity beginning at the specified time and lasting for the specified duration.

Parameters:

entityIdentifier - The identifier of the entity whose data is to be retrieved.

start - The date of the earliest data point to retrieve.

maximumPoints - The maximum number of points to return.

Returns:

A DateMotionCollection1 representing the archived data.

getPositions

public final DateMotionCollection1<Cartesian> getPositions(Object entityIdentifier,
                                                           @Nonnull
                                                           JulianDate start,
                                                           @Nonnull
                                                           JulianDate stop,
                                                           int maximumPoints)

Gets a DateMotionCollection1 representing the archived position, velocity and acceleration of the specified entity beginning at the specified time and lasting for the specified duration.

Parameters:

entityIdentifier - The identifier of the entity whose data is to be retrieved.

start - The date of the earliest data point to retrieve.

stop - The time of the last data point to retrieve.

maximumPoints - The maximum number of points to return.

Returns:

A DateMotionCollection1 representing the archived data.

getOrientations

public final DateMotionCollection2<UnitQuaternion,Cartesian> getOrientations(Object entityIdentifier,
                                                                             @Nonnull
                                                                             JulianDate start,
                                                                             @Nonnull
                                                                             JulianDate stop)

Gets a DateMotionCollection2 representing the archived orientation, rotational velocity and rotational acceleration of the specified entity beginning at the specified time and lasting for the specified duration.

Parameters:

entityIdentifier - The identifier of the entity whose data is to be retrieved.

start - The date of the earliest data point to retrieve.

stop - The time of the last data point to retrieve.

Returns:

A DateMotionCollection2 representing the archived data.

getOrientations

public final DateMotionCollection2<UnitQuaternion,Cartesian> getOrientations(Object entityIdentifier,
                                                                             @Nonnull
                                                                             JulianDate start,
                                                                             int maximumPoints)

Gets a DateMotionCollection2 representing the archived orientation, rotational velocity and rotational acceleration of the specified entity beginning at the specified time and lasting for the specified duration.

Parameters:

entityIdentifier - The identifier of the entity whose data is to be retrieved.

start - The date of the earliest data point to retrieve.

maximumPoints - The maximum number of points to return.

Returns:

A DateMotionCollection2 representing the archived data.

getOrientations

public final DateMotionCollection2<UnitQuaternion,Cartesian> getOrientations(Object entityIdentifier,
                                                                             @Nonnull
                                                                             JulianDate start,
                                                                             @Nonnull
                                                                             JulianDate stop,
                                                                             int maximumPoints)

Gets a DateMotionCollection2 representing the archived orientation, rotational velocity and rotational acceleration of the specified entity beginning at the specified time and lasting for the specified duration.

Parameters:

entityIdentifier - The identifier of the entity whose data is to be retrieved.

start - The date of the earliest data point to retrieve.

stop - The time of the last data point to retrieve.

maximumPoints - The maximum number of points to return.

Returns:

A DateMotionCollection2 representing the archived data.

getArchivedData

public final RawEntityData<TEntity> getArchivedData(@Nonnull
                                                    JulianDate start,
                                                    @Nonnull
                                                    JulianDate stop,
                                                    int maximumRecords,
                                                    String... propertyNames)

Retrieves archived properties for all entities over the provided time period.

Parameters:

start - The time of the first property to retrieve.

stop - The time of the last property to retrieve.

maximumRecords - The maximum number of each property to retrieve.

propertyNames - The archived properties to retrieve.

Returns:

An instance of RawEntityData representing the requested data.

getArchivedData

public final RawEntityData<TEntity> getArchivedData(Object entityIdentifier,
                                                    @Nonnull
                                                    JulianDate start,
                                                    @Nonnull
                                                    JulianDate stop,
                                                    int maximumRecords,
                                                    String... propertyNames)

Retrieves archived properties for the provided entity over the provided time period.

Parameters:

entityIdentifier - The identifier of the entity whose properties to retrieve.

start - The time of the first property to retrieve.

stop - The time of the last property to retrieve.

maximumRecords - The maximum number of each property to retrieve.

propertyNames - The archived properties to retrieve.

Returns:

An instance of RawEntityData representing the requested data.

waitForArchiveQueue

public final void waitForArchiveQueue()

Waits for the currently queued transactions to be archived before returning. Additional committed transactions may be queued while waiting and these will NOT be waited upon.

archiveEntities

protected abstract void archiveEntities(@Nonnull
                                        Transaction transaction,
                                        @Nonnull
                                        Iterable<? extends TEntity> entities)

Archives a set of entities.

Parameters:

transaction - A transaction that should be used to retrieve properties of the entities. It is possible for later transactions to commit additional updates before this method is called for older updates. However, this transaction will see the state of the system as of the time that the updates being archived were committed. Using this transaction rather than creating a separate one will guarantee that updates are not missed.

entities - The entities to archive.

getArchivedPrimitivePropertyComponents

protected abstract Object[] getArchivedPrimitivePropertyComponents(Iterable<? extends ArchivedProperty> primitivePropertyComponents,
                                                                   @Nonnull
                                                                   JulianDate start,
                                                                   @Nonnull
                                                                   JulianDate stop,
                                                                   int maximumRecords)

Retrieves archived primitive property components for all entities over the provided time period.

Parameters:

primitivePropertyComponents - The archived properties to retrieve.

start - The time of the first property to retrieve.

stop - The time of the last property to retrieve.

maximumRecords - The maximum number of each property to retrieve.

Returns:

The array of primitive components.

getArchivedPrimitivePropertyComponents

protected abstract Object[] getArchivedPrimitivePropertyComponents(Object entityIdentifier,
                                                                   Iterable<? extends ArchivedProperty> primitivePropertyComponents,
                                                                   @Nonnull
                                                                   JulianDate start,
                                                                   @Nonnull
                                                                   JulianDate stop,
                                                                   int maximumRecords)

Retrieves archived primitive property components for the provided entity over the provided time period.

Parameters:

entityIdentifier - The identifier of the entity whose properties to retrieve.

primitivePropertyComponents - The archived properties to retrieve.

start - The time of the first property to retrieve.

stop - The time of the last property to retrieve.

maximumRecords - The maximum number of each property to retrieve.

Returns:

The array of primitive components.

getArchivedInterval

@Nonnull
public abstract TimeInterval getArchivedInterval(@Nonnull
                                                           Object entityIdentifier)

Gets the overall interval that exists in the archive for the specified entity identifier.

Parameters:

entityIdentifier - The identifier of the entity for which to obtain the interval of availability.

Returns:

The interval of archived data.

getArchivedInterval

@Nonnull
public abstract TimeInterval getArchivedInterval()

Gets the overall interval that exists in the archive for any entity.

Returns:

The interval of archived data.

clear

public abstract void clear()

Clears the contents of the archive.

writingStartup

protected void writingStartup()

Called during TrackingArchive.startWriting(), before the first call to TrackingArchive.archiveEntities(agi.foundation.Transaction, java.lang.Iterable<? extends TEntity>).

writingShutdown

protected void writingShutdown()

Called during TrackingArchive.stopWriting(), after the last call to TrackingArchive.archiveEntities(agi.foundation.Transaction, java.lang.Iterable<? extends TEntity>).

getEntityPrimitivePropertyComponents

protected final void getEntityPrimitivePropertyComponents(@Nonnull
                                                          Transaction transaction,
                                                          @Nonnull
                                                          TEntity entity,
                                                          @Nonnull
                                                          Object[] values)

Fills an array with the archived properties of an entity.

Parameters:

transaction - The transaction in which to obtain the property values of the entity.

entity - The entity from which to obtain the property values.

values - The array in which to store the values. The array must have an element for each property in PrimitivePropertyComponents (get).