com.pervasive.datarush.ports.physical

Interface RecordInput

All Superinterfaces:

Named, PhysicalInputPort, PhysicalPort, RecordTyped, RecordValued, SteppableRecordValued, TokenTyped, TokenValued

public interface RecordInput
extends PhysicalInputPort, SteppableRecordValued

An input port on a record data flow. A record output is a collection of output ScalarInputField fields, one for each field of the record, indexed both by name and position, as determined by the schema of the input's RecordTokenType.

As with other ports, the input maintains a position in the flow. However, the position in the flow is only advanced by calling methods on the RecordInput itself; the component input fields cannot advance the position. When the port is positioned on a token, the input fields contain the field values of the current record.

Method Summary

Modifier and Type	Method and Description
void	detach() Detaches the input port from its data flow.
ScalarInputField	getField(int index) Gets the input field at the given position.
ScalarInputField	getField(String fieldName) Gets the input field with the given name.
ScalarInputField[]	getFields() Gets all input fields of this record port.
long	getPosition() Retrieves the position of the port.
InputStatistics	getStats() Retrieves the run-time statistics gathered for this input.
RecordTokenType	getType() Gets the type of tokens in the underlying flow.
boolean	isAttached() Tests if the port is attached to a data flow.
boolean	isOnToken() Tests if the port is positioned on a token.
boolean	stepNext() Advances the cursor position of this input by one token.
boolean	stepNext(long n) Advances the cursor position of this input by the specified number of tokens.
long	stepUntil(long n, Timeout timeout) Advances the cursor position as many tokens as possible up to the specified number of tokens, within a given amount of time.
long	stepUntil(Timeout timeout) Advances the cursor position of this input by one token, if it can be be done in a given amount of time.
boolean	transfer(TokenAppendable out) Transfers the current token value of the input port to the target.
boolean	transfer(TokenAppendable out, boolean startWithNextToken) Transfers a token value from the input port to the given target, transferring either the current token (that is, push, then step) or the next token (that is, step, then push).
boolean	transfer(TokenAppendable out, long n) Transfers multiple tokens of the input port starting at the current token to the given target.
boolean	transfer(TokenAppendable out, long n, boolean startWithNextToken) Transfers multiple tokens from the input port, beginning either with the current token or the next token.
void	transferAll(TokenAppendable out) Transfers all remaining tokens from the input port starting at the current token to the given target.
void	transferAll(TokenAppendable out, boolean startWithNextToken) Transfers all remaining tokens from the input port, beginning either with the current token or the next token.

Methods inherited from interface com.pervasive.datarush.namespace.Named

getName

Methods inherited from interface com.pervasive.datarush.tokens.record.RecordValued

containsNull, newFieldIterator, newFieldIterator, newFieldIterator, size

Methods inherited from interface com.pervasive.datarush.tokens.TokenValued

isNull

Method Detail

getType

RecordTokenType getType()

Description copied from interface: PhysicalPort

Gets the type of tokens in the underlying flow.

Specified by:

getType in interface PhysicalPort

Specified by:

getType in interface RecordTyped

Specified by:

getType in interface RecordValued

Specified by:

getType in interface TokenTyped

Specified by:

getType in interface TokenValued

Returns:

the token type for this port.

getFields

ScalarInputField[] getFields()

Gets all input fields of this record port.

Specified by:

getFields in interface RecordValued

Returns:

the input fields of this port

getField

ScalarInputField getField(String fieldName)

Gets the input field with the given name.

Specified by:

getField in interface RecordValued

Parameters:

fieldName - name of the field

Returns:

the field with the given name

getField

ScalarInputField getField(int index)

Gets the input field at the given position.

Specified by:

getField in interface RecordValued

Specified by:

getField in interface SteppableRecordValued

Parameters:

index - zero-based index into the field list

Returns:

the field at the given position

stepNext

boolean stepNext()

Advances the cursor position of this input by one token. This method may block until more data is available or end of data on the port is encountered.

Specified by:

stepNext in interface SteppableRecordValued

Returns:

true if the cursor was advanced and resides on a valid token, false if end of data was encountered.

stepNext

boolean stepNext(long n)

Advances the cursor position of this input by the specified number of tokens. This method may block until more data is available or end of data on the port is encountered.

Parameters:

n - the number of tokens to advance

Returns:

true if the cursor was advanced the specified number of tokens and resides on a valid token, false if end of data was encountered.

stepUntil

long stepUntil(Timeout timeout)

Advances the cursor position of this input by one token, if it can be be done in a given amount of time. The time bound is honored on a best effort basis; it may be violated as necessary to ensure data consistency.

Parameters:

timeout - the maximum amount of time to block for data. Using a value of 0 will block indefinitely, as stepNext() does.

Returns:

the number of tokens advanced. If end of data was encountered, -1 is be returned.

stepUntil

long stepUntil(long n,
               Timeout timeout)

Advances the cursor position as many tokens as possible up to the specified number of tokens, within a given amount of time. The time bound is honored on a best effort basis; it may be violated as necessary to ensure data consistency.

Parameters:

n - the number of tokens to advance

timeout - the maximum amount of time to block for data. Using a value of 0 will block indefinitely, as stepNext(long) does.

Returns:

the actual number of tokens advanced. If end of data was encountered, the return value will be negative and is expressed as -(tokensAdvanced + 1), where tokensAdvanced is the number of tokens advanced at the point when end of data was hit.

transfer

boolean transfer(TokenAppendable out)

Transfers the current token value of the input port to the target. On return, the port will be on the next token.

The port and the given target must have compatible types for transfer.

Parameters:

out - target onto which to push the current token. This can be any appendable sequence of tokens, such as an output port.

Returns:

true if the input port is positioned on a valid token upon completion, false if it is at end of data.

See Also:

stepNext()

transfer

boolean transfer(TokenAppendable out,
                 long n)

Transfers multiple tokens of the input port starting at the current token to the given target. The port will be advanced the given number of tokens.

The port and the given output port must have compatible types for transfer. Fewer tokens than the given count may be transferred if this port encounters end of data during the transfer.

Parameters:

out - target onto which to push tokens. This can be any appendable sequence of tokens, such as an output port.

n - number of tokens to transfer

Returns:

true if the input port is positioned on a valid token upon completion, false if it is at end of data.

See Also:

stepNext(long)

transferAll

void transferAll(TokenAppendable out)

Transfers all remaining tokens from the input port starting at the current token to the given target. The port will be advanced until end of data is encountered. The port and the given output port must have compatible types for transfer.

Parameters:

out - target onto which to push all remaining tokens. This can be any appendable sequence of tokens, such as an output port.

transfer

boolean transfer(TokenAppendable out,
                 boolean startWithNextToken)

Transfers a token value from the input port to the given target, transferring either the current token (that is, push, then step) or the next token (that is, step, then push). In either case, on return the port will be advanced to the next token.

This input port and the given output port must have compatible types for transfer. If transferring the current token, the token cursor for this port must be positioned on a token. When transferring the next token, it is possible that no token gets transferred if the next position is end of data.

Parameters:

out - target onto which to push the token value. This can be any appendable sequence of tokens, such as an output port.

startWithNextToken - indicates whether the current token or the next token is pushed onto the target.

Returns:

true if the input port is positioned on a valid token upon completion, false if it is at end of data.

See Also:

stepNext(), transfer(TokenAppendable)

transfer

boolean transfer(TokenAppendable out,
                 long n,
                 boolean startWithNextToken)

Transfers multiple tokens from the input port, beginning either with the current token or the next token. In either case, the port is advanced by the given number of tokens.

This input port and the given target must have compatible types for transfer. If transferring starting with the current token, the token cursor for the port must be positioned on a token. Fewer tokens than requested (possibly none) may be transferred if the port encounters end of data during the transfer.

Specified by:

transfer in interface SteppableRecordValued

Parameters:

out - target onto which to push tokens. This can be any

n - number of tokens to transfer

startWithNextToken - indicates whether to start the transfer with the current token or the next token.

Returns:

true if the input port is positioned on a valid token upon completion, false if it is at end of data.

See Also:

stepNext(long), transfer(TokenAppendable, long)

transferAll

void transferAll(TokenAppendable out,
                 boolean startWithNextToken)

Transfers all remaining tokens from the input port, beginning either with the current token or the next token. The port will be advanced until end of data is encountered.

The port and the given target must have compatible types for transfer.

Parameters:

out - target onto which to push all remaining tokens. This can be any appendable sequence of tokens, such as an output port.

startWithNextToken - indicates whether to start the transfer with the current token or the next token.

See Also:

transferAll(TokenAppendable)

detach

void detach()

Detaches the input port from its data flow. Once detached, the port behaves as if end of data were encountered.

Detaching a port frees resources. If an input port is no longer needed and end of data has not been reached, it is a good idea to detach it.

Specified by:

detach in interface PhysicalPort

See Also:

isAttached()

getPosition

long getPosition()

Retrieves the position of the port. That is, how many tokens have been stepped by calling stepNext() and stepNext(long). Once end of data has been encountered, this value will be exactly the number of tokens which were on the flow.

The position is zero based. The position acts as a cursor in that the position lies between the current element and the next element. Thus a position of zero indicates that no element has been addressed from the port. This is similar to the cursor semantics in the ListIterator interface.

Specified by:

getPosition in interface SteppableRecordValued

Returns:

the position of the port.

isAttached

boolean isAttached()

Tests if the port is attached to a data flow. A port starts initially attached and becomes detached if one of the following occurs:

• end of data (EOD)is encountered on the port
• the port is explicitly detached using detach()

If a port is attached, the port can be safely advanced (using stepNext(), etc.). However, this does not indicate the port is positioned on a token, so attempting to access the current token value may fail with an exception.

If a port is not attached, any attempt to advance the port or access the current value will throw an exception.

Specified by:

isAttached in interface PhysicalPort

Returns:

the attached state of the port

See Also:

isOnToken()

isOnToken

boolean isOnToken()

Tests if the port is positioned on a token. Initially, a port is not positioned on a token. Advancing the position will either encounter end of data or leave the port on a token.

While positioned on a token, the current value can be safely accessed without error. But if not positioned on a token, all attempts to access the current value will throw an exception.

Returns:

the positional state of the port

See Also:

isAttached()

getStats

InputStatistics getStats()

Retrieves the run-time statistics gathered for this input.

Specified by:

getStats in interface PhysicalPort

Returns:

PortStats gathered during execution or null if the configuration did not specify collecting statistics