org.jtrim2.concurrent.query

Class MultiAsyncDataState

java.lang.Object

org.jtrim2.concurrent.query.MultiAsyncDataState

All Implemented Interfaces:

AsyncDataState

public final class MultiAsyncDataState
extends Object
implements AsyncDataState

Defines an aggregate state of progress of multiple data retrieval processes.

AsyncDataLink instances relying on multiple other AsyncDataLink instances may choose to return an instance of MultiAsyncDataState containing all the data states. The order of states are important: each state's data retrieval process is considered to be the subprocess of the data retrieval process of the previous state.

Note that the AsyncDataLink instance created by the AsyncLinks.convertResultAsync(AsyncDataLink, AsyncDataQuery) method returns MultiAsyncDataState instances as its state of progress.

Thread safety

The methods of this class are safe to be accessed by multiple threads concurrently. The wrapped list of AsyncDataState instances cannot be modified after construction time.

Synchronization transparency

The methods of this class are synchronization transparent.

See Also:

AsyncLinks.convertResultAsync(AsyncDataLink, AsyncDataQuery), AsyncQueries.convertResultsAsync(AsyncDataQuery, AsyncDataQuery)

Constructor Summary

Constructors

Constructor and Description
MultiAsyncDataState(AsyncDataState... states) Initializes the MultiAsyncDataState with the specified underlying states.
MultiAsyncDataState(List<? extends AsyncDataState> states) Initializes the MultiAsyncDataState with the specified underlying states.

Method Summary

Modifier and Type	Method and Description
double	getProgress() Returns an aggregated progress value of the underlying states.
double	getSubProgress(int index) Returns the progress value of the underlying state at the given index.
AsyncDataState	getSubState(int index) Returns the underlying state at the given index.
int	getSubStateCount() Returns the number of underlying AsyncDataState instances.
List<AsyncDataState>	getSubStateList() Returns a read-only list of the underlying AsyncDataState instances in the order they were specified at construction time.
String	toString() Returns the string representation of this MultiAsyncDataState in no particular format.

Methods inherited from class java.lang.Object

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

Constructor Detail

MultiAsyncDataState

public MultiAsyncDataState(AsyncDataState... states)

Initializes the MultiAsyncDataState with the specified underlying states.

Parameters:

states - the underlying AsyncDataState instances in the order of significance. The content of the passed array will be copied, so modifying the passed array after this constructor returns will have no effect on the newly created instance. This argument cannot be null but its elements are allowed to be null.

Throws:

NullPointerException - thrown if the specified AsyncDataState array is null

MultiAsyncDataState

public MultiAsyncDataState(List<? extends AsyncDataState> states)

Initializes the MultiAsyncDataState with the specified underlying states.

Parameters:

states - the underlying AsyncDataState instances in the order of significance. The content of the passed list will be copied, so modifying the passed list after this constructor returns will have no effect on the newly created instance. This argument cannot be null but its elements are allowed to be null.

Throws:

NullPointerException - thrown if the specified AsyncDataState list is null

Method Detail

getSubStateList

public List<AsyncDataState> getSubStateList()

Returns a read-only list of the underlying AsyncDataState instances in the order they were specified at construction time.

This method returns a list with the same element as if they were returned by the getSubState(int) method and will have the same number of elements as returned by the getSubStateCount() method.

Returns:

a read-only list of the underlying AsyncDataState instances in the order they were specified at construction time. This method never returns null but the returned list may contain null elements at positions where null was specified at construction time.

See Also:

getSubStateCount(), getSubState(int)

getSubStateCount

public int getSubStateCount()

Returns the number of underlying AsyncDataState instances. That is, the number of AsyncDataState instances specified at construction time.

The returned integer is the exclusive upper bound for the argument of the getSubState(int) method. The return value of this method is constant throughout the life time of this MultiAsyncDataState.

Returns:

the number of underlying AsyncDataState instances. This method always returns an integer greater than or equal to zero.

See Also:

getSubState(int)

getSubState

public AsyncDataState getSubState(int index)

Returns the underlying state at the given index. That is, the AsyncDataState instance specified at the given index at construction time. The inclusive lower bound for the index is zero and the exclusive upper bound is the value returned by the getSubStateCount() method.

Note that this method is effectively the same as invoking: getSubStateList().get(index) but more efficient.

Parameters:

index - the index of the underlying state to be returned. This argument must be greater than or equal to zero and lower than the value returned by the getSubStateCount() method.

Returns:

the underlying state at the given index. This method may return null if such state was specified at the given index at construction time.

Throws:

IndexOutOfBoundsException - thrown if the specified index is not within its valid range

See Also:

getSubStateCount()

getSubProgress

public double getSubProgress(int index)

Returns the progress value of the underlying state at the given index. The progress value for null states is defined to be zero.

This method is effectively the same as the getSubState(index) != null ? getSubState(index).getProgress() : 0.0 expression.

Parameters:

index - the index of the underlying state whose progress value is to be returned. This argument must be greater than or equal to zero and lower than the value returned by the getSubStateCount() method.

Returns:

the progress value of the state at the given index

Throws:

IndexOutOfBoundsException - thrown if the specified index is not within its valid range

See Also:

getSubStateCount()

getProgress

public double getProgress()

Returns an aggregated progress value of the underlying states.

How this aggregated progress value is calculated is not defined but the following condition holds for the resulting progress: If for two different invocation, the first N state has the same progress value but the progress value at N + 1 position is different, then this method will return greater or equal value for the invocation where the progress value at the N + 1 position is greater. When the underlying progress values are all the same, this method will return the same value for both invocation.

In case all the underlying AsyncDataState instances return a value within the range [0.0, 1.0], this method will also return a value within this range.

Specified by:

getProgress in interface AsyncDataState

Returns:

the aggregated progress value of the underlying states

toString

public String toString()

Returns the string representation of this MultiAsyncDataState in no particular format. The string representation contains the string representation of all the underlying states.

This method is intended to be used for debugging only.

Overrides:

toString in class Object

Returns:

the string representation of this object in no particular format. This method never returns null.