agi.foundation.tracking

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

Class EntityFilter<TEntity extends IEntityIdentifier>

java.lang.Object

agi.foundation.infrastructure.DefinitionalObject

agi.foundation.tracking.EntityFilter<TEntity>

Type Parameters:

TEntity - The type of entity.

All Implemented Interfaces:

ICloneWithContext, IEnumerateDependencies, IEquatableDefinition, IFreezable, IThreadAware

Direct Known Subclasses:

AccessEntityFilter, DelegateEntityFilter

public abstract class EntityFilter<TEntity extends IEntityIdentifier>
extends DefinitionalObject
implements IThreadAware

The base class for classes that are used with EntityFilterChain to filter entities into different EntitySets based on their properties.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	EntityFilter(EntityFilter<TEntity> existingInstance, CopyContext context) Initializes a new instance as a copy of an existing instance.
protected	EntityFilter(TransactionContext context) Initializes a new instance with the specified context.

Method Summary

Modifier and Type	Method and Description
void	beginEntityMatching(Transaction transaction) Indicates to the filter that the EntityFilterChain has begun matching entities to filters as part of a EntityFilterChain.redistributeEntities() operation.
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 abstract boolean	checkForSameDefinition(EntityFilter<TEntity> 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	endEntityMatching(Transaction transaction) Indicates to the filter that the EntityFilterChain has finished matching entities to filters as part of a EntityFilterChain.redistributeEntities() operation.
protected void	entityMatchingCleanup(Transaction transaction) Allows the filter to perform any filter-specific cleanup at the end of entity matching.
protected void	entityMatchingSetup(Transaction transaction) Allows the filter to perform any filter-specific setup at the start of entity matching.
boolean	getIsThreadSafe() Gets a value indicating whether the methods on this instance are safe to call from multiple threads simultaneously.
EntitySet<TEntity>	getMatchingEntities() Gets the set of entities that match this filter.
abstract boolean	isMatch(Transaction transaction, TEntity entity) Returns true if the provided entity fits the filter criteria.
boolean	match(Transaction transaction, TEntity entity) Checks an entity against this filter and adds it to the MatchingEntities (get) collection if it matches.

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

Methods inherited from interface agi.foundation.infrastructure.ICloneWithContext

clone

Constructor Detail

EntityFilter

protected EntityFilter(@Nonnull
                       TransactionContext context)

Initializes a new instance with the specified context.

Parameters:

context - The transaction context to be used by this filter.

See Also:

Filtering topic

EntityFilter

protected EntityFilter(@Nonnull
                       EntityFilter<TEntity> 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(EntityFilter<TEntity> 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 EntityFilter.checkForSameDefinition(agi.foundation.infrastructure.DefinitionalObject) method.

Overrides:

computeCurrentDefinitionHashCode in class DefinitionalObject

Returns:

The computed hash code.

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

beginEntityMatching

public final void beginEntityMatching(@Nonnull
                                      Transaction transaction)

Indicates to the filter that the EntityFilterChain has begun matching entities to filters as part of a EntityFilterChain.redistributeEntities() operation.

Parameters:

transaction - The transaction to be used to match entities.

endEntityMatching

public final void endEntityMatching(Transaction transaction)

Indicates to the filter that the EntityFilterChain has finished matching entities to filters as part of a EntityFilterChain.redistributeEntities() operation.

Parameters:

transaction - The transaction to be used to match entities.

match

public final boolean match(@Nonnull
                           Transaction transaction,
                           @Nonnull
                           TEntity entity)

Checks an entity against this filter and adds it to the MatchingEntities (get) collection if it matches.

Parameters:

transaction - The transaction used for getting values from the entity.

entity - The entity to be filtered.

Returns:

true if the entity matched this filter and was added to the MatchingEntities (get) collection; otherwise false.

getMatchingEntities

public final EntitySet<TEntity> getMatchingEntities()

Gets the set of entities that match this filter.

isMatch

public abstract boolean isMatch(@Nonnull
                                Transaction transaction,
                                @Nonnull
                                TEntity entity)

Returns true if the provided entity fits the filter criteria.

Parameters:

transaction - The transaction used for getting values from the entity.

entity - The entity to be filtered.

Returns:

true if the entity meets the filter criteria; otherwise false.

entityMatchingSetup

protected void entityMatchingSetup(Transaction transaction)

Allows the filter to perform any filter-specific setup at the start of entity matching. This method is called by EntityFilter.beginEntityMatching(agi.foundation.Transaction).

Parameters:

transaction - The transaction to be used to match entities.

entityMatchingCleanup

protected void entityMatchingCleanup(Transaction transaction)

Allows the filter to perform any filter-specific cleanup at the end of entity matching. This method is called by EntityFilter.endEntityMatching(agi.foundation.Transaction).

Parameters:

transaction - The transaction to be used to match entities.