Package com.ibm.di.fc

Class 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 Detail

      • ASSEMBLYLINE

        public static final java.lang.String ASSEMBLYLINE
        Parameter name.
        See Also:
        Constant Field Values

      • CYCLE_MODE

        public static final java.lang.String CYCLE_MODE
        Parameter name.
        See Also:
        Constant Field Values

      • SIMULATE_MODE

        public static final java.lang.String SIMULATE_MODE
        Parameter name.
        See Also:
        Constant Field Values

      • CUSTOM_SEC

        public static final java.lang.String CUSTOM_SEC
        Parameter name.
        See Also:
        Constant Field Values

      • USE_TCB_ATTRS

        public static final java.lang.String USE_TCB_ATTRS
        Parameter name.
        See Also:
        Constant Field Values

      • SHARE_LOG

        public static final java.lang.String SHARE_LOG
        Parameter name.
        See Also:
        Constant Field Values

      • OPERATION

        public static final java.lang.String OPERATION
        Parameter name.
        See Also:
        Constant Field Values

      • OPERATION_INIT_PREFIX

        public static final java.lang.String OPERATION_INIT_PREFIX
        Prefix for operation initialization.
        See Also:
        Constant Field Values

    • Constructor Detail

      • AssemblyLineFC

        public AssemblyLineFC()
        Default constructor.

    • Method Detail

      • perform

        public java.lang.Object perform​(java.lang.Object obj)
                         throws java.lang.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:
        java.lang.Exception - An exception is thrown if this method fails.

      • performOperation

        public java.lang.Object performOperation​(java.lang.Object work,
                                         java.lang.String operation)
                                  throws java.lang.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:
        java.lang.Exception

      • performOperation

        public java.lang.Object performOperation​(java.lang.Object work,
                                         java.lang.String operation,
                                         Entry opentry)
                                  throws java.lang.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:
        java.lang.Exception - : if an error occurs.

      • getTCB

        public TaskCallBlock getTCB()
                     throws java.lang.Exception
        Returns the TaskCallBlock to use before starting an instance. Currently, you cannot provide a TCB when cycling a remote AL.
        Returns:
        TaskCallBlock
        Throws:
        java.lang.Exception

      • initialize

        public void initialize​(java.lang.Object obj)
                throws java.lang.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:
        java.lang.Exception - An exception is thrown if this method fails.

      • connectServer

        public Session connectServer​(java.lang.String server)
                      throws java.lang.Exception
        Establish a server connection.
        Parameters:
        server - server address
        Returns:
        Session
        Throws:
        java.lang.Exception - : never.

      • getConfigInstance

        public ConfigInstance getConfigInstance​(java.lang.String ci)
                                 throws java.lang.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:
        java.lang.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 java.lang.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:
        java.lang.Exception - An exception is thrown if this method fails.

      • updateSchema

        public boolean updateSchema​(FunctionConfig config)
                     throws java.lang.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:
        java.lang.Exception - : never

      • updateSchemaConnector

        public boolean updateSchemaConnector​(ConnectorConfig config)
                              throws java.lang.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:
        java.lang.Exception - An exception is thrown if this method fails.

      • querySchema

        public java.util.List<Entry> querySchema​(java.lang.Object source)
                                  throws java.lang.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:
        java.lang.Exception
        See Also:
        Entry, Vector

      • getVersion

        public java.lang.String getVersion()
        Version information.
        Returns:
        version information