com.ibm.di.fc
Class AssemblyLineFC

java.lang.Object
  com.ibm.di.fc.Function
      com.ibm.di.fc.AssemblyLineFC

All Implemented Interfaces:

FunctionInterface, VersionInfoInterface

public class AssemblyLineFC
extends Function

This is a function component that calls an AssemblyLine(AL) on a local or remote server. The call can be made in three different modes.

1. Run and wait for result. Each call to perform() starts the target AL and returns the result object for the execution, typically the last work Entry. initialize() does not start the target AL.
2. Run in background. The target AL runs on its own, in the background. initialize() does not start the target AL.
3. Manual (cycle mode). The target AL is controlled by the FC by executing a cycle for each call to perform(). initialize() starts the target AL.

When the FC runs an AssemblyLine in background mode, the FC keeps a reference to the target AL and the FC can return the status of the running/terminated assemblyline. You obtain this status simply by calling the FC with a null or empty Entry parameter. The returned Entry object contains the reference to the target AL in its "value" attribute. If you pass a null value to the FC, the return value is the actual reference to the target AL. This complies with the calling conventions of Function components in general (e.g. return an Entry object if called with Entry object).

When the FC runs an AssemblyLine in background mode, you can also call the FC with specific string values to obtain various info about the target AL:

 fc.perform("target"); // returns the object reference of the target al
 fc.perform("active"); // returns either ""active", "aborted" or "terminated" depending on the target al status
 fc.perform("error"); // returns the java.lang.Exception object when the status is "aborted"
 fc.perform("result"); // returns the current result Entry object
 fc.perform("stop"); // tries to terminate an active target al - may throw an error if call does not succeed
 

When the FC is called in this mode with an Entry object, the Entry object can contain one or more of the above keywords in the command Attribute. The returned Entry object is then populated with the same values as described above. So, rather than calling perform() with all keywords, you can create an Entry with all keywords as attributes in the Entry object and get away with one call to perform(): var e = system.newEntry(); e.setAttribute("command", "target, status"); var result = fc.perform(e); task.logmsg("The status is: " + result.getString("status")); When the FC runs an AL in manual mode, each call with an Entry object causes one cycle to be executed in the target AL. The returned Entry object is the work entry result of the cycle. When the target AL has completed, a null entry is returned. If the cycle execution causes an error, that error is re-thrown by the FC (you should use a try/catch block in your script).

To provide a TaskCallBlock (TCB) you can use the fc.getTCB() and set parameters in the returned TCB object. This object will be used the next time an AssemblyLine is started by this FC. You should only set connector parameters in the returned TCB as this FC will potentially overwrite the runmode and initial work entry.

Another way to set TCB parameters are by using the output attribute map where you define variables with the specific prefix "$tcb.". When these attributes are found in the entry they will be moved to the TCB and removed from the entry. This will only work when the FC runs an assemblyline each time the FC is called (e.g. run and await completion).

Field Summary

static String	ASSEMBLYLINE Parameter name.
static String	CONFIG Parameter name.
static String	CUSTOM_SEC Parameter name.
static String	CYCLE_MODE Parameter name.
static String	OPERATION Parameter name.
static String	OPERATION_INIT_PREFIX Prefix for operation initialization.
static String	SERVER Parameter name.
static String	SHARE_LOG Parameter name.
static String	SIMULATE_MODE Parameter name.
static String	TCB Parameter name.
static String	USE_TCB_ATTRS Parameter name.

Fields inherited from class com.ibm.di.fc.Function

logger

Constructor Summary

AssemblyLineFC()
Default constructor.

Method Summary

Session	connectServer(String server) Establish a server connection.
ConfigInstance	getConfigInstance(String ci) Retrieves the ConfigInstance object using the provided ID from the current session.
Session	getSession() Retrieves session object.
TaskCallBlock	getTCB() Returns the TaskCallBlock to use before starting an instance.
String	getVersion() Version information.
void	initialize(Object obj) Called once to initialize the function
Object	perform(Object obj) Executes the AL in the specified mode.
Object	performOperation(Object work, String operation) This method invokes an operation in the target AssemblyLine.
Object	performOperation(Object work, String operation, Entry opentry) Performs the specified operation.
List<Entry>	querySchema(Object source) This method translates to whatever means a function component has to discover schema for a connection.
void	terminate() This method frees any resources allocated.
boolean	updateSchema(FunctionConfig config) This method modifies the schema in the provided configuration.
boolean	updateSchemaConnector(ConnectorConfig config) This method modifies the schema in the provided configuration.

Methods inherited from class com.ibm.di.fc.Function

debug, getConfiguration, getContext, getDebug, getLog, getParam, getRSInterface, getUI, initialize, logmsg, setConfiguration, setContext, setDebug, setLog, setParam, setRSInterface, verifyInitialized

Methods inherited from class java.lang.Object

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

Field Detail

ASSEMBLYLINE

public static final String ASSEMBLYLINE

Parameter name.

See Also:

Constant Field Values

SERVER

public static final String SERVER

Parameter name.

See Also:

Constant Field Values

CONFIG

public static final String CONFIG

Parameter name.

See Also:

Constant Field Values

CYCLE_MODE

public static final String CYCLE_MODE

Parameter name.

See Also:

Constant Field Values

SIMULATE_MODE

public static final String SIMULATE_MODE

Parameter name.

See Also:

Constant Field Values

TCB

public static final String TCB

Parameter name.

See Also:

Constant Field Values

CUSTOM_SEC

public static final String CUSTOM_SEC

Parameter name.

See Also:

Constant Field Values

USE_TCB_ATTRS

public static final String USE_TCB_ATTRS

Parameter name.

See Also:

Constant Field Values

SHARE_LOG

public static final String SHARE_LOG

Parameter name.

See Also:

Constant Field Values

OPERATION

public static final String OPERATION

Parameter name.

See Also:

Constant Field Values

OPERATION_INIT_PREFIX

public static final String OPERATION_INIT_PREFIX

Prefix for operation initialization.

See Also:

Constant Field Values

Constructor Detail

AssemblyLineFC

public AssemblyLineFC()

Default constructor.

Method Detail

perform

public Object perform(Object obj)
               throws Exception

Executes the AL in the specified mode.

Parameters:

obj - the initial work entry for the AssemblyLine being executed (an object of type com.ibm.di.entry.Entry)

Returns:

the result entry of the AssemblyLine

Throws:

Exception - An exception is thrown if this method fails.

performOperation

public Object performOperation(Object work,
                               String operation)
                        throws Exception

This method invokes an operation in the target AssemblyLine.

Parameters:

work - The work entry

operation - The operation to invoke

Returns:

The work entry from the target AssemblyLine

Throws:

Exception

performOperation

public Object performOperation(Object work,
                               String operation,
                               Entry opentry)
                        throws Exception

Performs the specified operation.

Parameters:

work - the work entry to use

operation - The AL operation.

opentry - Entry

Returns:

the work entry at the end of the operation.

Throws:

Exception - : if an error occurs.

getTCB

public TaskCallBlock getTCB()
                     throws Exception

Returns the TaskCallBlock to use before starting an instance. Currently, you cannot provide a TCB when cycling a remote AL.

Returns:

TaskCallBlock

Throws:

Exception

initialize

public void initialize(Object obj)
                throws Exception

Called once to initialize the function

Specified by:

initialize in interface FunctionInterface

Overrides:

initialize in class Function

Parameters:

obj - this parameter is ignored

Throws:

Exception - An exception is thrown if this method fails.

connectServer

public Session connectServer(String server)
                      throws Exception

Establish a server connection.

Parameters:

server - server address

Returns:

Session

Throws:

Exception - : never.

getConfigInstance

public ConfigInstance getConfigInstance(String ci)
                                 throws Exception

Retrieves the ConfigInstance object using the provided ID from the current session.

Parameters:

ci - the ID of the ConfigInstance to look for.

Returns:

the ConfigInstance object or null.

Throws:

Exception - if unable to establish a connection to the remote server or the provided ID is null or an empty string.

getSession

public Session getSession()

Retrieves session object.

Returns:

the session

terminate

public void terminate()
               throws Exception

This method frees any resources allocated. If in manual mode, the AssemblyLine will also be terminated gracefully.

Specified by:

terminate in interface FunctionInterface

Overrides:

terminate in class Function

Throws:

Exception - An exception is thrown if this method fails.

updateSchema

public boolean updateSchema(FunctionConfig config)
                     throws Exception

This method modifies the schema in the provided configuration. The intent is to allow the FC to provide a schema definition dynamically based on a given configuration.

Specified by:

updateSchema in interface FunctionInterface

Overrides:

updateSchema in class Function

Parameters:

config - FunctionConfig

Returns:

boolean

Throws:

Exception - : never

updateSchemaConnector

public boolean updateSchemaConnector(ConnectorConfig config)
                              throws Exception

This method modifies the schema in the provided configuration. The intent is to allow the FC to provide a schema definition dynamically based on a given configuration.

Parameters:

config - The connector configuration

Returns:

Returns true when the update is completed.

Throws:

Exception - An exception is thrown if this method fails.

querySchema

public List<Entry> querySchema(Object source)
                        throws Exception

This method translates to whatever means a function component has to discover schema for a connection. The specific FC may implement this, in which case a Vector of Entry objects is returned for each column/attribute it discovered.

Each Entry in the Vector returned should contain the following attributes:

Name	Value
name	The name of the column/attribute/field ....
syntax	The syntax or expected value type
size	If specified this will give the user a hint as to how long the field may be

Specified by:

querySchema in interface FunctionInterface

Overrides:

querySchema in class Function

Parameters:

source - The object on which to discover schema. This may be an Entry or a string value. Boolean value will tell which schema to discover: true - InputMapSchema, false - OutputMapSchema. If not specified the default will be true. Might be a FunctionConfig object which will be set as the configuration of this object. Could be an array of objects (i.e. Object[]). Only the first object of a specific type will be considered, the rest (if any) will be ignored.

Returns:

A Vector of com.ibm.di.entry.Entry objects describing each entity

Throws:

Exception

See Also:

Entry, Vector

getVersion

public String getVersion()

Version information.

Returns:

version information