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
`static java.lang.String` `LOG_THROWABLE_STACK_TRACE`
`protected boolean` `logThrowableStackTrace`
`static java.lang.String` `RECORD_ELEMENT_TRACE`
`static java.lang.String` `RECORD_THROWABLE_MESSAGE`
`static java.lang.String` `RECORD_THROWABLE_STACK_TRACE`
`protected boolean` `recordElementTrace`
`protected boolean` `recordThrowableMessage`
`protected boolean` `recordThrowableStackTrace`
`static java.lang.String` `STACK_TRACE_LINE_DELIMITER`
`static java.lang.String` `STACK_TRACE_LINE_TRIM`
`protected java.lang.String` `stackTraceLineDelimiter`
`protected boolean` `stackTraceTrimLine`

### Constructor Summary

Constructors
Constructor and Description
`TrapProps()`

### Method Summary

Methods
`protected void` `addPropertiesTo(java.util.Properties properties)`
`java.lang.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(java.lang.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 java.lang.String RECORD_ELEMENT_TRACE

See Also:
  Constant Field Values

#### RECORD_THROWABLE_MESSAGE

    public static final java.lang.String RECORD_THROWABLE_MESSAGE

See Also:
  Constant Field Values

#### RECORD_THROWABLE_STACK_TRACE

    public static final java.lang.String RECORD_THROWABLE_STACK_TRACE

See Also:
  Constant Field Values

#### LOG_THROWABLE_STACK_TRACE

    public static final java.lang.String LOG_THROWABLE_STACK_TRACE

See Also:
  Constant Field Values

#### STACK_TRACE_LINE_TRIM

    public static final java.lang.String STACK_TRACE_LINE_TRIM

See Also:
  Constant Field Values

#### STACK_TRACE_LINE_DELIMITER

    public static final java.lang.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 java.lang.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 java.lang.String getStackTraceLineDelimiter()

#### setStackTraceLineDelimiter

    public TrapProps setStackTraceLineDelimiter(java.lang.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(java.util.Properties properties)

Specified by:
  `addPropertiesTo` in class `Props`