net.sf.farrago.runtime
Class FarragoUdrRuntime

java.lang.Object
  net.sf.farrago.runtime.FarragoUdrRuntime

public abstract class FarragoUdrRuntime
extends Object

FarragoUdrRuntime exposes a runtime support interface which can be used by implementations of Farrago user-defined routines. For an example of how to use this interface, see FarragoTestUDR.generateRandomNumber(long).

NOTE: By relying on this interface, your UDR becomes dependent on Farrago.

Version:

$Id: //open/dev/farrago/src/net/sf/farrago/runtime/FarragoUdrRuntime.java#15 $

Author:

John V. Sichi

Constructor Summary

FarragoUdrRuntime()

Method Summary

static void	checkCancel() Tests to see whether the statement invoking this UDR has been cancelled; if so, an exception is thrown.
static Object	getContext() Accesses the context object for the calling UDR.
static Object	getDataServerRuntimeSupport(Object param) If this UDR invocation was generated by a FarragoMedDataServer, invokes that server's FarragoMedDataServer.getRuntimeSupport(java.lang.Object) method.
static FarragoRepos	getRepos() Gets the FarragoRepos for this context.
static FarragoSession	getSession() Gets the session which called the UDR.
static Object	handleRowError(String[] columnNames, Object[] columnValues, RuntimeException ex, int columnIndex, String tag, boolean isWarning) Forwards a row error to the runtime context.
static Object	handleRowError(String[] columnNames, Object[] columnValues, RuntimeException ex, int columnIndex, String tag, boolean isWarning, String errorCode, String columnName) Forwards error to runtime context, if error code is non-null, exceptions will be defered until all errors have been processed/logged for a row
static void	handleRowErrorCompletion(RuntimeException ex, String tag)
static boolean	inUdr()
static void	setContext(Object context) Stores the context object for the calling UDR.
static void	setExecutionHandle(FennelExecutionHandle execHandle) Associates an execution handle with the context associated with the executing UDR.

Methods inherited from class java.lang.Object

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

Constructor Detail

FarragoUdrRuntime

public FarragoUdrRuntime()

Method Detail

getContext

public static Object getContext()

Accesses the context object for the calling UDR.

Returns:

context object, or null if none has been set yet

setContext

public static void setContext(Object context)

Stores the context object for the calling UDR. If the given context object implements the ClosableAllocation interface, its closeAllocation method will be called automatically when statement execution ends.

Parameters:

context - new context object to set

getDataServerRuntimeSupport

public static Object getDataServerRuntimeSupport(Object param)

If this UDR invocation was generated by a FarragoMedDataServer, invokes that server's FarragoMedDataServer.getRuntimeSupport(java.lang.Object) method. Otherwise, throws IllegalStateException.

Parameters:

param - server-specific runtime parameter

Returns:

server-specific runtime support object

checkCancel

public static void checkCancel()

Tests to see whether the statement invoking this UDR has been cancelled; if so, an exception is thrown. UDR's which take a lot of CPU time can call this periodically in order to be responsive to cancel within calls.

setExecutionHandle

public static void setExecutionHandle(FennelExecutionHandle execHandle)

Associates an execution handle with the context associated with the executing UDR.

Parameters:

execHandle - the execution handle

getSession

public static FarragoSession getSession()

Gets the session which called the UDR. Only system UDR's are allowed to call this.

Returns:

a FarragoSession

getRepos

public static FarragoRepos getRepos()

Gets the FarragoRepos for this context. Only system UDR's are allowed to call this.

Returns:

a FarragoRepos

handleRowError

public static Object handleRowError(String[] columnNames,
                                    Object[] columnValues,
                                    RuntimeException ex,
                                    int columnIndex,
                                    String tag,
                                    boolean isWarning)

Forwards a row error to the runtime context. The runtime context then decides how to process the error. For example, it might log the error, send the error to a table, or cancel the statement.

Parameters:

columnNames - array of column names from the input stream

columnValues - array of column values for the bad input row. Primitive values such as long or int should be wrapped in Objects such as Long or Int. Values should be printable via toString(). For example, 2006-10-08 would be preferrable to Date@1ee80a.

ex - the runtime exception to be handled

columnIndex - the 1-based index of the column with the error. Since the value 0 is reserved for filter conditions, the value -1 may be used when a column index is not applicable.

tag - a unique identifier for the source of the exception. It is helpful for the tag to include information about the source. For example, CleanseAddress[Id] may be more useful than [Id]. A timestamp suffix can be informative and helps to satisfy the uniqueness requirement.

isWarning - whether the exception is to be treated as a warning

Returns:

a server specific status value. A server may choose to return null or to return a more detailed status such as TupleIter.NoDataReason to indicate that the error could not be processed.

handleRowError

public static Object handleRowError(String[] columnNames,
                                    Object[] columnValues,
                                    RuntimeException ex,
                                    int columnIndex,
                                    String tag,
                                    boolean isWarning,
                                    String errorCode,
                                    String columnName)

Forwards error to runtime context, if error code is non-null, exceptions will be defered until all errors have been processed/logged for a row

handleRowErrorCompletion

public static void handleRowErrorCompletion(RuntimeException ex,
                                            String tag)

inUdr

public static boolean inUdr()