cascading.tap

## Class TrapProps

- java.lang.Object
- - cascading.property.Props
  - - cascading.tap.TrapProps

-     public class TrapProps
      extends Props

  Class TrapProps is a fluent helper class to set properties which control the behaviour of `Tap` instances used as traps on a given `Flow`.

  A Tap trap is used to capture bad data that has triggered an unhandled `Throwable` within a Cascading `Operation` or `Tap` (either as a source or sink).

  When a trap captures a failure, the `Tuple` arguments to the Operation or Tap will be captured and the Flow will continue executing with the next Tuple in the stream. Otherwise a Flow would typically fail.

  Due to the variability of data in the stream at any given point, a Tap trap should be configured with a `Scheme` that sinks `Fields.ALL`, or is guaranteed to sink known fields common to all Operations within the branch the trap has been bound too.

  Optionally diagnostic information, with the given field names, may be captured along with the argument Tuple.

  - `element-trace` - the file and line number the failed operation was instantiated
  - `throwable-message` - the `Throwable.getMessage()` value
  - `throwable-stacktrace` - the `Throwable.printStackTrace()` value, cleansed

  By default, if the Throwable stacktrace is captured, each line of the trace will be trimmed (to remove the TAB character (`\t`) and each new line (`\n`) will be replaced with a pipe character (`|`).

  Each value is prepended to the argument Tuple in the order given above. Since the argument Tuple may vary in size, prepending the diagnostic value deterministically allows for simple grep and sed like commands to be applied to the files.

  Trap properties can be applied to a given Flow by calling `Props.buildProperties()` on the properties instance handed to the target `FlowConnector` or directly to any given Tap via the `Tap.getConfigDef()` using `Props.setProperties(cascading.property.ConfigDef)`.

  It should be noted that traps are not intended for 'flow control' of a data stream. They are for exceptional cases that when reached should not cause a Flow to fail. Flow control (sending known bad data down a different branch) should be part of the application. Traps capture the values that are unaccounted for and cause errors, if missing them doesn't compromise the integrity of the application.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static String` | `LOG_THROWABLE_STACK_TRACE`
    `protected boolean` | `logThrowableStackTrace`
    `static String` | `RECORD_ELEMENT_TRACE`
    `static String` | `RECORD_THROWABLE_MESSAGE`
    `static String` | `RECORD_THROWABLE_STACK_TRACE`
    `protected boolean` | `recordElementTrace`
    `protected boolean` | `recordThrowableMessage`
    `protected boolean` | `recordThrowableStackTrace`
    `static String` | `STACK_TRACE_LINE_DELIMITER`
    `static String` | `STACK_TRACE_LINE_TRIM`
    `protected String` | `stackTraceLineDelimiter`
    `protected boolean` | `stackTraceTrimLine`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `TrapProps()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected void` | `addPropertiesTo(Properties properties)`
    `String` | `getStackTraceLineDelimiter()`
    `boolean` | `isLogThrowableStackTrace()`
    `boolean` | `isRecordElementTrace()`
    `boolean` | `isRecordThrowableMessage()`
    `boolean` | `isRecordThrowableStackTrace()`
    `boolean` | `isStackTraceTrimLine()`
    `TrapProps` | `recordAllDiagnostics()` Method recordAllDiagnostics enables recording of all configurable diagnostic values.
    `TrapProps` | `setLogThrowableStackTrace(boolean logThrowableStackTrace)` Method setLogThrowableStackTrace will disable logging of the Throwable stacktrace value if set to `false`.
    `TrapProps` | `setRecordElementTrace(boolean recordElementTrace)` Method setRecordElementTrace will enable recording the element trace value if set to `true`.
    `TrapProps` | `setRecordThrowableMessage(boolean recordThrowableMessage)` Method setRecordThrowableMessage will enable recording the Throwable message value if set to `true`.
    `TrapProps` | `setRecordThrowableStackTrace(boolean recordThrowableStackTrace)` Method setRecordThrowableStackTrace will enable recording the Throwable stacktrace value if set to `true`.
    `TrapProps` | `setStackTraceLineDelimiter(String stackTraceLineDelimiter)` Method setStackTraceLineDelimiter will set the text delimiter used to denote stacktrace lines.
    `TrapProps` | `setStackTraceTrimLine(boolean stackTraceTrimLine)` Method setStackTraceTrimLine will disable trimming of whitespace on every recorded stacktrace line if set to `false`.
    `static TrapProps` | `trapProps()`

    - ### Methods inherited from class cascading.property.Props

      `buildProperties, buildProperties, buildProperties, buildProperties, setProperties, setProperties`

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### RECORD_ELEMENT_TRACE

          public static final String RECORD_ELEMENT_TRACE

      See Also:
        Constant Field Values

    - #### RECORD_THROWABLE_MESSAGE

          public static final String RECORD_THROWABLE_MESSAGE

      See Also:
        Constant Field Values

    - #### RECORD_THROWABLE_STACK_TRACE

          public static final String RECORD_THROWABLE_STACK_TRACE

      See Also:
        Constant Field Values

    - #### LOG_THROWABLE_STACK_TRACE

          public static final String LOG_THROWABLE_STACK_TRACE

      See Also:
        Constant Field Values

    - #### STACK_TRACE_LINE_TRIM

          public static final String STACK_TRACE_LINE_TRIM

      See Also:
        Constant Field Values

    - #### STACK_TRACE_LINE_DELIMITER

          public static final String STACK_TRACE_LINE_DELIMITER

      See Also:
        Constant Field Values

    - #### recordElementTrace

          protected boolean recordElementTrace

    - #### recordThrowableMessage

          protected boolean recordThrowableMessage

    - #### recordThrowableStackTrace

          protected boolean recordThrowableStackTrace

    - #### logThrowableStackTrace

          protected boolean logThrowableStackTrace

    - #### stackTraceTrimLine

          protected boolean stackTraceTrimLine

    - #### stackTraceLineDelimiter

          protected String stackTraceLineDelimiter

  - ### Constructor Detail

    - #### TrapProps

          public TrapProps()

  - ### Method Detail

    - #### trapProps

          public static TrapProps trapProps()

    - #### recordAllDiagnostics

          public TrapProps recordAllDiagnostics()

      Method recordAllDiagnostics enables recording of all configurable diagnostic values.
      Returns:
        this

    - #### isRecordElementTrace

          public boolean isRecordElementTrace()

    - #### setRecordElementTrace

          public TrapProps setRecordElementTrace(boolean recordElementTrace)

      Method setRecordElementTrace will enable recording the element trace value if set to `true`.

      The default is `false`.
      Parameters:
        `recordElementTrace` - of type boolean
      Returns:
        this

    - #### isRecordThrowableMessage

          public boolean isRecordThrowableMessage()

    - #### setRecordThrowableMessage

          public TrapProps setRecordThrowableMessage(boolean recordThrowableMessage)

      Method setRecordThrowableMessage will enable recording the Throwable message value if set to `true`.

      The default is `false`.
      Parameters:
        `recordThrowableMessage` - of type boolean
      Returns:
        this

    - #### isRecordThrowableStackTrace

          public boolean isRecordThrowableStackTrace()

    - #### setRecordThrowableStackTrace

          public TrapProps setRecordThrowableStackTrace(boolean recordThrowableStackTrace)

      Method setRecordThrowableStackTrace will enable recording the Throwable stacktrace value if set to `true`.

      The default is `false`.
      Parameters:
        `recordThrowableStackTrace` - of type boolean
      Returns:
        this

    - #### isLogThrowableStackTrace

          public boolean isLogThrowableStackTrace()

    - #### setLogThrowableStackTrace

          public TrapProps setLogThrowableStackTrace(boolean logThrowableStackTrace)

      Method setLogThrowableStackTrace will disable logging of the Throwable stacktrace value if set to `false`.

      The default is `true`.
      Parameters:
        `logThrowableStackTrace` - of type boolean
      Returns:
        this

    - #### isStackTraceTrimLine

          public boolean isStackTraceTrimLine()

    - #### setStackTraceTrimLine

          public TrapProps setStackTraceTrimLine(boolean stackTraceTrimLine)

      Method setStackTraceTrimLine will disable trimming of whitespace on every recorded stacktrace line if set to `false`.

      The default is `true`.
      Parameters:
        `stackTraceTrimLine` - of type boolean
      Returns:
        this

    - #### getStackTraceLineDelimiter

          public String getStackTraceLineDelimiter()

    - #### setStackTraceLineDelimiter

          public TrapProps setStackTraceLineDelimiter(String stackTraceLineDelimiter)

      Method setStackTraceLineDelimiter will set the text delimiter used to denote stacktrace lines.

      The default is `|` (the pipe character).
      Parameters:
        `stackTraceLineDelimiter` - of type boolean
      Returns:
        this

    - #### addPropertiesTo

          protected void addPropertiesTo(Properties properties)

      Specified by:
        `addPropertiesTo` in class `Props`

Copyright © 2007-2015 Concurrent, Inc. All Rights Reserved.