Module datarush.library
Package 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
    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 Details

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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

      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:

    • 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