com.ibm.di.fc
Class AssemblyLineFC

java.lang.Object
  extended by com.ibm.di.fc.Function
      extended by 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