jcommon.graph
Interface ITopologicalSortAsyncResult<TValue,TProcessedValue>

Type Parameters:

TValue - The expected result type for ending graph vertices who have no out neighbors.

public interface ITopologicalSortAsyncResult<TValue,TProcessedValue>

Returned by an asynchronous sort call. Used to know or await for notification of asynchronous processing completion.

Method Summary

boolean	await() Provided for conveniency.
boolean	await(long timeout, TimeUnit unit) Provided for conveniency.
boolean	awaitUninterruptibly() Provided for conveniency.
boolean	awaitUninterruptibly(long timeout, TimeUnit unit) Provided for conveniency.
boolean	contains(TValue value) Returns a boolean indicating if the results contain a key for the provided value.
boolean	discontinueScheduling() Discontinues further scheduling of additional vertices for processing.
Iterable<TValue>	endingValues() Returns the list of ending values (values for vertices that have no out neighbors) that generated the result.
TProcessedValue	first() Retrieves the result for the first ending value.
TProcessedValue	get(TValue value) Gets the result for an ending value.
ExecutorService	getExecutorService() Provides a reference to the ExecutorService that asynchronous processing was called with.
boolean	isDone() Determines if all processing of vertices has completed.
boolean	isEmpty() Determines if the results are empty.
boolean	isProcessingDiscontinued() Determines if discontinueScheduling() has been called previously.
boolean	isSuccessful() Determines if all vertices have been processed without incident.
TProcessedValue	resultFor(TValue value) Retrieves the result for an ending value.
Iterable<TProcessedValue>	results() Generates an instance of Iterable that allows traversing the contents of the results.
int	size() The number of returned results.
boolean	waitForCompletion() Waits indefinitely and uninterruptibly for the asynchronous sort to signal that it's done processing.
boolean	waitForCompletion(long timeout, TimeUnit unit) Waits indefinitely and uninterruptibly for the asynchronous sort to signal that it's done processing.

Method Detail

isDone

boolean isDone()

Determines if all processing of vertices has completed.

Returns:

True if all processing of vertices has completed, otherwise false.

isSuccessful

boolean isSuccessful()

Determines if all vertices have been processed without incident. Should be called only after waitForCompletion(), await(), or awaitUninterruptibly() have returned. Calling waitForCompletion() will return this same value after all vertices have been processed. It's suggested you use waitForCompletion().

Returns:

True if all vertices were processed without incident, otherwise false.

isProcessingDiscontinued

boolean isProcessingDiscontinued()

Determines if discontinueScheduling() has been called previously.

Returns:

True if discontinueScheduling() has been called previously, otherwise false.

getExecutorService

ExecutorService getExecutorService()

Provides a reference to the ExecutorService that asynchronous processing was called with.

Returns:

A reference to an ExecutorService instance.

discontinueScheduling

boolean discontinueScheduling()

Discontinues further scheduling of additional vertices for processing. It's highly suggested that you do not shutdown or abort the getExecutorService() instance. Instead, call this method and then waitForCompletion() which will allow all previously submitted vertices to drain.

Returns:

True if the operation was successful, otherwise false.

waitForCompletion

boolean waitForCompletion()

Waits indefinitely and uninterruptibly for the asynchronous sort to signal that it's done processing.

Returns:

True if the sorting completed successfully. False if a callback threw an exception or a cycle was detected.

waitForCompletion

boolean waitForCompletion(long timeout,
                          TimeUnit unit)

Waits indefinitely and uninterruptibly for the asynchronous sort to signal that it's done processing.

Parameters:

timeout - Length of time in TimeUnit units to wait for completion.

unit - TimeUnit unit of time represented by the timeout.

Returns:

True if the sorting completed successfully. False if a callback threw an exception or a cycle was detected.

awaitUninterruptibly

boolean awaitUninterruptibly()

Provided for conveniency. Waits indefinitely and uninterruptibly for the asynchronous sort to signal that it's done processing. It's suggested you use waitForCompletion().

Returns:

True if processing completed. This is not an indicator of successful completion. Please use isSuccessful() or simply call waitForCompletion() instead.

awaitUninterruptibly

boolean awaitUninterruptibly(long timeout,
                             TimeUnit unit)

Provided for conveniency. Waits indefinitely and uninterruptibly for the asynchronous sort to signal that it's done processing. It's suggested you use waitForCompletion().

Parameters:

timeout - Length of time in TimeUnit units to wait for completion.

unit - TimeUnit unit of time represented by the timeout.

Returns:

True if processing completed. This is not an indicator of successful completion. Please use isSuccessful() or simply call waitForCompletion() instead.

await

boolean await()
              throws InterruptedException

Provided for conveniency. Waits indefinitely (but can be interrupted) for the asynchronous sort to signal that it's done processing. It's suggested you use waitForCompletion().

Returns:

True if processing completed. This is not an indicator of successful completion. Please use isSuccessful() or simply call waitForCompletion() instead.

Throws:

InterruptedException

await

boolean await(long timeout,
              TimeUnit unit)
              throws InterruptedException

Provided for conveniency. Waits indefinitely (but can be interrupted) for the asynchronous sort to signal that it's done processing. It's suggested you use waitForCompletion().

Parameters:

timeout - Length of time in TimeUnit units to wait for completion.

unit - TimeUnit unit of time represented by the timeout.

Returns:

True if processing completed. This is not an indicator of successful completion. Please use isSuccessful() or simply call waitForCompletion() instead.

Throws:

InterruptedException

isEmpty

boolean isEmpty()

Determines if the results are empty. The results should be considered unreliable until after isSuccessful() or waitForCompletion() returns true.

Returns:

true if the results are empty or processing has not completed; false otherwise.

get

TProcessedValue get(TValue value)

Gets the result for an ending value. Alias for resultFor(Object). The results should be considered unreliable until after isDone() or waitForCompletion() returns.

Parameters:

value - The value whose result you want.

See Also:

resultFor(Object)

resultFor

TProcessedValue resultFor(TValue value)

Retrieves the result for an ending value. The results should be considered unreliable until after isDone() or waitForCompletion() returns.

Parameters:

value - The value whose result you want.

Returns:

The value whose result you want. null if the value is not in the result list.

first

TProcessedValue first()

Retrieves the result for the first ending value. If there is more than one result, this method is not guaranteed to provide the same answer with every invocation. If there is more than one result, you should use the get(Object) or resultFor(Object) methods. The results should be considered unreliable until after isDone() or waitForCompletion() returns.

Returns:

The value of the first given result. null if there are no values in the result list.

size

int size()

The number of returned results. It's possible that this does not agree with the number of vertices with no out neighbors (ending vertices) if processing was interrupted. The results should be considered unreliable until after isDone() or waitForCompletion() returns.

Returns:

An int representing the size of the results.

See Also:

results()

contains

boolean contains(TValue value)

Returns a boolean indicating if the results contain a key for the provided value. The results should be considered unreliable until after isDone() or waitForCompletion() returns.

Parameters:

value - The value for whom membership in the results will be tested.

Returns:

true if the provided value is a member of the results; false otherwise.

results

Iterable<TProcessedValue> results()

Generates an instance of Iterable that allows traversing the contents of the results. The results should be considered unreliable until after isDone() or waitForCompletion() returns.

Returns:

An instance of Iterable for traversing the contents of the results.

endingValues

Iterable<TValue> endingValues()

Returns the list of ending values (values for vertices that have no out neighbors) that generated the result. The results should be considered unreliable until after isDone() or waitForCompletion() returns.

Returns:

An instance of Iterable representing the ending values (values for vertices that have no out neighbors) that generated the result.