com.ibm.websphere.batch

Interface BatchDataStream

  • All Superinterfaces:
    com.ibm.batch.api.BatchDataStream


    public interface BatchDataStream
    extends com.ibm.batch.api.BatchDataStream

    The BatchDataStream (BDS) interface provides an abstraction over the data that is processed by a Batch Step. It provides the set of methods that are called by the Batch Execution Environment (BEE) in order to initialize the data stream, retrieve cursor information from the BDS, and position the BDS to a specified cursor during processing of a Batch Step.

    This is the order in which methods are called on a BDS during normal execution of a batch step:
    • setProperties(Properties properties)
    • initialize(String ilogicalname, String ijobstepid)
    • open()
    • positionAtInitialCheckpoint()
    • externalizeCheckpointInformation() - this is called at every checkpoint
    • intermediateCheckpoint() - this is called right after a checkpoint completes
    • close()
    This is the order in which methods are called on a BDS when a batch step restarts processing a bds:
    • setProperties(Properties properties)
    • initialize(String ilogicalname, String ijobstepid)
    • open()
    • internalizeCheckpointInformation(String chkptinfo) - informs the bds of the previously saved checkpoint information
    • positionAtCurrentCheckpoint() - called to position the bds to the cursor indicated by the saved checkpoint in above method
    • externalizeCheckpointInformation() - this is called at every checkpoint
    • intermediateCheckpoint() - this is called right after a checkpoint completes
    • close()

    Environment The batch data stream is a java object that will be called from both the Batch Execution Environment and the Batch Job Step EJB.

    • Transactional environment: The caller of the BDS will be in a global transaction when any of the methods on the interface are called. There is no guarantee that any two methods on the instance of the object will be called under the same global transactional unit of work. The global transactional unit of work is not owned by the BDS, the only transactional action that can be invoked by the BDS is to mark the global transaction as rollback only.

    • Method Summary

      Methods 
      Modifier and Type Method and Description
      void close()
      The close method is called by the Batch Execution Environment to indicate to the BDS that the user of the BDS is done working with the BDS.
      java.lang.String externalizeCheckpointInformation()
      The externalizeCheckpointInformation method is called by the Batch Execution Environment (BEE) during the checkpoint completion phase of processing.
      java.lang.String getName()
      The getName method returns the logical name of the BDS that was received in the initialize method.
      java.util.Properties getProperties()
      The getProperties method returns the bds properties specified in the xJCL and received in the setProperties method.
      void initialize(java.lang.String ilogicalname, java.lang.String ijobstepid)
      The initialize method is called by the Batch Execution Environment during the initialization of the job step.
      void intermediateCheckpoint()
      The intermediateCheckpoint method is called by the Batch Execution Environment to indicate to the BDS that a checkpoint has just completed (i.e. a global transaction has been committed and a new global transaction has started).
      void internalizeCheckpointInformation(java.lang.String chkptinfo)
      The internalizeCheckpointInformation method is called by the Batch Execution Environment during the restart of a Batch Step Bean.
      void open()
      The open method is called by the Batch Execution Environment to indicate that the BDS is about to be used and to prepare the BDS for operation.
      void positionAtCurrentCheckpoint()
      The positionAtCurrentCheckpoint method is called by Batch Execution Environment to provide a signal to the BDS that it should start processing the stream at the point that was defined in the internalizeCheckpointInformation method.
      void positionAtInitialCheckpoint()
      The positionAtInitialCheckpoint is called by the Batch Execution Environment to provide a signal to the BDS that it should start processing the stream at the initial point as defined by the xJCL inputs.
      void setProperties(java.util.Properties properties)
      The setProperties method is called by the Batch Execution Environment to pass bds properties specified in xJCL to the bds as a java.util.Properties object.
    • Method Detail

      • externalizeCheckpointInformation

        java.lang.String externalizeCheckpointInformation()

        The externalizeCheckpointInformation method is called by the Batch Execution Environment (BEE) during the checkpoint completion phase of processing. This allows the BDS to record a set of information with the BEE, that will be committed with the checkpoint's global transaction to the BEE database. The information that is returned needs to contain enough data to allow the BDS to reposition itself during a restart of the Batch Step Bean.

        Additional information can be stored in this string as well, but the larger the string, the slower the Batch Execution Environment will be in storing it in the RDB that it is maintaining.

        Specified by:
        externalizeCheckpointInformation in interface com.ibm.batch.api.BatchDataStream
        Returns:
        - This is a string that is created to record the BDS's position in the stream being processed. This String is opaque to anyone but the BDS, so only the BDS can interpret its content.
      • internalizeCheckpointInformation

        void internalizeCheckpointInformation(java.lang.String chkptinfo)

        The internalizeCheckpointInformation method is called by the Batch Execution Environment during the restart of a Batch Step Bean. This allows the BDS to restart its internal state to the point it was at when the last successful checkpoint was processed. It is at this point in the process that the Batch Step Bean will begin processing.

        Specified by:
        internalizeCheckpointInformation in interface com.ibm.batch.api.BatchDataStream
        Parameters:
        chkptinfo - - This is a string that was created by the BDS that was returned to the Batch Execution Environment on the externalizeCheckpointInformation method. This String is opaque to anyone but the BDS, so only the BDS can interpret its content.
      • initialize

        void initialize(java.lang.String ilogicalname,
                      java.lang.String ijobstepid)
                        throws BatchContainerDataStreamException

        The initialize method is called by the Batch Execution Environment during the initialization of the job step. This allows the BDS to initialize the stream for use by the Batch Step Bean. The method is passed the logical name of the BDS and the JobStepID. These two pieces of information are used to create a BatchDataStreamConfig object that has the configuration information necessary to establish the stream. The initialize method should configure the stream as defined by the config object and validate the input source or output sink (e.g. is the dataset available? can I connect to the database being processed?). If the BDS is not valid, throw the BatchDataStreamConfigurationFailed exception.

        Specified by:
        initialize in interface com.ibm.batch.api.BatchDataStream
        Parameters:
        ilogicalname - the logical name of the BDS, this name is used to locate the resource in the job's xJCL.
        ijobstepid - an identifier that represents the step within the batch job that is being run. This id is used to locate the resource in the job's xJCL.
        Throws:
        BatchDataStreamConfigurationFailed - is throw if the BDS is not configured properly to access the BDS's source of data or its sink to put data.
        BatchContainerDataStreamException
      • positionAtInitialCheckpoint

        void positionAtInitialCheckpoint()
                                         throws BatchContainerDataStreamException

        The positionAtInitialCheckpoint is called by the Batch Execution Environment to provide a signal to the BDS that it should start processing the stream at the initial point as defined by the xJCL inputs.

        Specified by:
        positionAtInitialCheckpoint in interface com.ibm.batch.api.BatchDataStream
        Throws:
        BatchContainerDataStreamException
      • positionAtCurrentCheckpoint

        void positionAtCurrentCheckpoint()
                                         throws BatchContainerDataStreamException

        The positionAtCurrentCheckpoint method is called by Batch Execution Environment to provide a signal to the BDS that it should start processing the stream at the point that was defined in the internalizeCheckpointInformation method.

        Specified by:
        positionAtCurrentCheckpoint in interface com.ibm.batch.api.BatchDataStream
        Throws:
        BatchContainerDataStreamException
      • open

        void open()
                  throws BatchContainerDataStreamException

        The open method is called by the Batch Execution Environment to indicate that the BDS is about to be used and to prepare the BDS for operation. This includes items such as opening files that are used by the BDS's implementation.

        Specified by:
        open in interface com.ibm.batch.api.BatchDataStream
        Throws:
        BatchContainerDataStreamException
      • close

        void close()
                   throws BatchContainerDataStreamException
        The close method is called by the Batch Execution Environment to indicate to the BDS that the user of the BDS is done working with the BDS. This allows the BDS to free resources that it is holding.
        Specified by:
        close in interface com.ibm.batch.api.BatchDataStream
        Throws:
        BatchContainerDataStreamException
      • getName

        java.lang.String getName()
        The getName method returns the logical name of the BDS that was received in the initialize method.
        Specified by:
        getName in interface com.ibm.batch.api.BatchDataStream
        Returns:
        logical name of the BDS
      • setProperties

        void setProperties(java.util.Properties properties)

        The setProperties method is called by the Batch Execution Environment to pass bds properties specified in xJCL to the bds as a java.util.Properties object.

        Specified by:
        setProperties in interface com.ibm.batch.api.BatchDataStream
      • getProperties

        java.util.Properties getProperties()

        The getProperties method returns the bds properties specified in the xJCL and received in the setProperties method.

        Specified by:
        getProperties in interface com.ibm.batch.api.BatchDataStream
        Returns:
        bds properties defined in the xJCL
      • intermediateCheckpoint

        void intermediateCheckpoint()

        The intermediateCheckpoint method is called by the Batch Execution Environment to indicate to the BDS that a checkpoint has just completed (i.e. a global transaction has been committed and a new global transaction has started).

        Specified by:
        intermediateCheckpoint in interface com.ibm.batch.api.BatchDataStream
IBM WebSphere Application ServerTM
Release 9.0