com.neurosys.q.service

Interface TokenContainerService<T extends Token<T>,C extends TokenContainer<T>>

Type Parameters:

T - as Token

C - as Container Type

All Known Subinterfaces:

BatchService<B,T>, ShiftService<S,V,P,T>, TokenManager<T,S,E>

All Known Implementing Classes:

DefaultAbstractTokenContainerService

public interface TokenContainerService<T extends Token<T>,C extends TokenContainer<T>>

Methods that services for Token-Containers like Batch and Shift should have common

Author:

Arjun Dhar

Method Summary

Modifier and Type	Method and Description
List<T>	add(C tokenContainer, List<T> tokens, Consumer<T> consumer, TokenEvent<T> tokenEvent)
C	getAssignedContainer(T token) For a Token get the container
default Integer	getMaxResultSize() To ensure no overload of systems, the maximum # of tokens that can be fetched for any type of request for container.
List<TokenPosition<T>>	getPositions(List<T> tokens, Collection states) Get the TokenPosition of a Token within its container .
QStatesStrategy	getQStatesStrategy() A lot of the Service API internally depend on Token states/status
Number	getSequence(C tokenContainer, T token) Get the index of a Token ready To be served within its container .
Class<C>	getType() Type of TokenContainer this service represents
default boolean	hasNext(C tokenContainer) If there are any tokens pending that are in #getReadyToBeProcessed(TokenContainer, Token).
void	init() Load/Refresh any state for the token management service
void	linkTokens(C tokenContainer, List<T> tokens) Re-Q / Move the tokens
Collection<T>	lookup(C tokenContainer, Query<T> query) Lookup using custom query defined in a proxy Object in tokens that are #getReadyToBeProcessed(TokenContainer, Token).
List<T>	lookupById(C tokenContainer, Object identifier) Lookup token(s) in a token container, using any of the following identifiers.
void	lookupBySequence(C tokenContainer, Map<Number,T> indexMap) UPDATE a Map with multiple tokens by lookup-sequence number in tokens that are #getReadyToBeProcessed(TokenContainer, Token).
T	lookupBySequence(C tokenContainer, Number sequence) Lookup a token in a Container by sequence number in tokens that are #getReadyToBeProcessed(TokenContainer, Token).
int	move(C tokenContainer, List<T> tokens, T tokenAfter) Deprecated. There can be many ways to move / prioritize tokens this implementation will not be supported in the future. Each service will define its own moving strategy, and from that we may infer a common Move strategy in the future. For now rely on update(TokenContainer, List, TokenEvent) and the Token itself will contain details of where its being moved.
T	poll(C tokenContainer) Poll then next token READY to be served.
List<T>	poll(C tokenContainer, Integer size) An optimized Poll with N number of Tokens in one go.
List<T>	poll(C tokenContainer, Integer size, T lastToken) Based on Last Token return next set of Tokens (of size), in Shift. This is for fail safe to ensure if a Token is lost in network errors, then the server knows last point of rollback.
T	poll(C tokenContainer, T lastToken) Based on Last Token return next Token in TokenContainer. This is for fail safe to ensure if a Token is lost in network errors, then the server knows last point of rollback.
List<T>	remove(C tokenContainer, List<T> tokens, Consumer<T> consumer, TokenEvent<T> tokenEvent) Remove the association of the tokenContainer from the Token
T	save(T token) An innocent save method
Number	size(C tokenContainer) # of tokens Tokens that are in the TokenContainer.
List<T>	update(C tokenContainer, List<T> tokens, TokenEvent<T> tokenEvent) Update Tokens passed from an API which is untrusted.
<S extends FlowStatus> List<T>	updateStatus(C tokenContainer, List tokens, S status, TokenEvent<T> tokenEvent) Update collection of tokens with status
<S extends FlowStatus> List<T>	updateStatus(List tokens, S status, TokenEvent<T> tokenEvent) Update collection of tokens with status

Method Detail

lookupById

List<T> lookupById(C tokenContainer,
                   Object identifier)

Lookup token(s) in a token container, using any of the following identifiers. The types of identifiers supported is implementation dependent.

A lookup operation is idempotent. Also, since the identifier can be anything full or partial a return type as List is supported. For all practical purposes this will be a single result.

Parameters:

tokenContainer - as TokenContainer type

identifier - as name String, Id Long

Returns:

List of

lookupBySequence

void lookupBySequence(C tokenContainer,
                      Map<Number,T> indexMap)

UPDATE a Map with multiple tokens by lookup-sequence number in tokens that are #getReadyToBeProcessed(TokenContainer, Token).

Parameters:

tokenContainer - as container type

indexMap - the Map to update where key is sequence number (or or above), and value is Token to be inserted.

lookupBySequence

T lookupBySequence(C tokenContainer,
                   Number sequence)

Lookup a token in a Container by sequence number in tokens that are #getReadyToBeProcessed(TokenContainer, Token).

Parameters:

tokenContainer - as container type

sequence - as Number

Returns:

getSequence

Number getSequence(C tokenContainer,
                   T token)

Get the index of a Token ready To be served within its container . Number index starts from 0

Parameters:

tokenContainer - as container type

token - as Token

Returns:

Number. null if in a ready state

See Also:

Batch.getSequence(Token), getPositions(List, Collection)

getPositions

List<TokenPosition<T>> getPositions(List<T> tokens,
                                    Collection states)

Get the TokenPosition of a Token within its container . Number index starts from 0

Parameters:

tokenContainerType - as TokenContainer Class type

tokens - as List of Token type

states - as Token States

Returns:

Number. null if in a ready state

See Also:

Batch.getSequence(Token), getSequence(TokenContainer, Token)

lookup

Collection<T> lookup(C tokenContainer,
                     Query<T> query)

Lookup using custom query defined in a proxy Object in tokens that are #getReadyToBeProcessed(TokenContainer, Token).

Parameters:

tokenContainer - as container type

query - as Query

Returns:

See Also:

Query

poll

T poll(C tokenContainer)

Poll then next token READY to be served. A State of READY is defined by QStatesStrategy.getReadyToBeProcessed()

Parameters:

tokenContainer - as container type

Returns:

next Token within the container. null if none

See Also:

#getReadyToBeProcessed(TokenContainer), QStatesStrategy

poll

T poll(C tokenContainer,
       T lastToken)

Based on Last Token return next Token in TokenContainer.
This is for fail safe to ensure if a Token is lost in network errors, then the server knows last point of rollback.

Parameters:

tokenContainer - as TokenContainer type

lastToken - as Token type

Returns:

Token type . null if none

poll

List<T> poll(C tokenContainer,
             Integer size)

An optimized Poll with N number of Tokens in one go.

Parameters:

tokenContainer - as TokenContainer type

number - as Integer

Returns:

List of Token of type . null if none

poll

List<T> poll(C tokenContainer,
             Integer size,
             T lastToken)

Based on Last Token return next set of Tokens (of size), in Shift.
This is for fail safe to ensure if a Token is lost in network errors, then the server knows last point of rollback.

Parameters:

tokenContainer - as TokenContainer type

lastToken -

Returns:

List of Token of type . null if none

add

List<T> add(C tokenContainer,
            List<T> tokens,
            Consumer<T> consumer,
            TokenEvent<T> tokenEvent)
     throws TokenGenerationException

Parameters:

tokenContainer - as container type

tokens - as List of Tokens

consumer - as Consumer to apply an anonymous function at runtime over the Token elements iterated; after they are added. nullable true

tokenEvent - as TokenEvent

Returns:

List of Tokens that were added

Throws:

TokenGenerationException

remove

List<T> remove(C tokenContainer,
               List<T> tokens,
               Consumer<T> consumer,
               TokenEvent<T> tokenEvent)

Remove the association of the tokenContainer from the Token

Parameters:

tokenContainer - as container type

tokens - as List of Tokens

consumer - as Consumer to apply an anonymous function at runtime over the Token elements iterated; after they are removed.nullable true.

tokenEvent - as TokenEvent

Returns:

List of Tokens that were removed

move

@Deprecated
int move(C tokenContainer,
                     List<T> tokens,
                     T tokenAfter)

Deprecated. There can be many ways to move / prioritize tokens this implementation will not be supported in the future. Each service will define its own moving strategy, and from that we may infer a common Move strategy in the future. For now rely on update(TokenContainer, List, TokenEvent) and the Token itself will contain details of where its being moved.

Re-Q / Move the tokens

Parameters:

tokenContainer - as TokenContainer type

tokens - as List of Tokens

tokenAfter. - @nullable true. If Null the move will occur after the last token within the container

Returns:

int as count of number of moves made (including repairs to positions from where the tokens was moved from)

linkTokens

void linkTokens(C tokenContainer,
                List<T> tokens)

Re-Q / Move the tokens

Parameters:

tokenContainer - as TokenContainer type

tokens - as List of Tokens

updateStatus

<S extends FlowStatus> List<T> updateStatus(List tokens,
                                            S status,
                                            TokenEvent<T> tokenEvent)

Update collection of tokens with status

Parameters:

tokens - as List of tokens of type Token or Ids

status - as Status

tokenEvent - as TokenEvent

Returns:

List of tokens affected

updateStatus

<S extends FlowStatus> List<T> updateStatus(C tokenContainer,
                                            List tokens,
                                            S status,
                                            TokenEvent<T> tokenEvent)

Update collection of tokens with status

Parameters:

tokenContainer - as TokenContainer type , provided to safeguard tokens belong to the specific container.

tokens - as List of tokens of type Token or Ids. If null then will apply Status to all tokens in container

status - as Status

tokenEvent - as TokenEvent

Returns:

List of tokens affected

update

List<T> update(C tokenContainer,
               List<T> tokens,
               TokenEvent<T> tokenEvent)
        throws PartialTransactionException

Update Tokens passed from an API which is untrusted.
Any implementation must cautiously inspect the tokens and only update the fields that are expected from the client, or ones not expected null and ignore the rest.

Parameters:

tokenContainer - type or can be null

tokens - as List of Tokens

tokenEvent - as TokenEvent

Returns:

List of tokens affected. The returned copy will be the same as what is persisted post update (not input; incase input output List are different)

Throws:

PartialTransactionException

size

Number size(C tokenContainer)

# of tokens Tokens that are in the TokenContainer. If the container is a finite state container then it will be the actual size of it, else if a stream then the count of tokens in #getReadyToBeProcessed(TokenContainer, Token). This is an idempotent operation.

Parameters:

tokenContainer - as TokenContainer type

Returns:

Number

getQStatesStrategy

QStatesStrategy getQStatesStrategy()

A lot of the Service API internally depend on Token states/status

Returns:

QStatesStrategy

save

T save(T token)

An innocent save method

getAssignedContainer

C getAssignedContainer(T token)

For a Token get the container

Parameters:

token - as Token

Returns:

getType

Class<C> getType()

Type of TokenContainer this service represents

Returns:

class of TokenContainer type

hasNext

default boolean hasNext(C tokenContainer)

If there are any tokens pending that are in #getReadyToBeProcessed(TokenContainer, Token). This is an idempotent operation.

Parameters:

tokenContainer - as TokenContainer type

Returns:

boolean

getMaxResultSize

default Integer getMaxResultSize()

To ensure no overload of systems, the maximum # of tokens that can be fetched for any type of request for container.

Can be null:

true, means all possible

Default value:

1500

init

void init()

Load/Refresh any state for the token management service