Index of XML Batch Processing

Some of the text and images has been copied from Luca Perrone (StuderAG) and translated into english.

1. Introduction

The XML Batch processing allows to run processes described as X-Objects (in XML). The batch processor loads a project (XML file) and starts a target process. There are different running modes:

  • dry run: The processing is simulated only
  • regular run: Runs the process. If an error occurs the process is aborted
  • no abort run: Runs the process without aborting it

The structure of the XML starts with a root object of type TXProcProject. The root object contains different targets. A target describes a processing for a specific goal. A target can also depend on other targets. This allows to create a dependency graph. The target contains various step-objects which implement IXProcess interface. Each step-object class can perform an action.

Following example simply copies a file called TestFile.txt from the temporary directory into a sub directory called test:

<?xml version="1.0"?>
<Projekt Name="MyProcessProject" ClassName="TXProcProject">
 
    <Target Name="Proc_01" ClassName="TXProcTarget">
        <copy ClassName="TXProcCopy"
              SourceDir="C:/Temp/"
              SourceFile="TestFile.txt"
              TargetDir="C:/Temp/test/"
              FailOnError="1"/>
    </Target>
   ...
</Projekt>

2. How to run

In your program code you have to create a XMLBatchProcessor object and to load a xml file with loadProject(). The following code loads a ProcessFile.xml into the batch processor

  TAutoPtr<TXMLBatchProcessor> ptrBatchProcessor 
    = new TXMLBatchProcessor();

  if(ptrBatchProcessor->loadProject(TString(L"ProcessFile.xml")) 
    == RET_NOERROR)
  {
    ptrBatchProcessor->processTarget(TString(L"ProcessMainNode"), m_rMonitor);
  }

The monitor (see m_rMonitor) is an object created outside of the batch processing. You have to implement the the interface IXProcessMonitor.


  class TMyProcessMonitor : public TZObject, 
                            public IXProcessMonitor
  {
    public:
      // Creates the processing monitor
      inline TProcessMonitor() { }

      // callback if a target has been started
      inline virtual void MQUALIFIER onProcessingTargetStarted(IXProcTarget& rTarget,
                                                    IXProcess::EProcessingMode eMode)
      {
        ...
      }

      // callback if a target has been ended
      inline virtual void MQUALIFIER onProcessingTargetEnded(IXProcTarget& rTarget,
                                                             Retval retValue)
      {
        ...
      }

      // callback when processing a step
      inline virtual void MQUALIFIER onProcessing(IXProcess& rProcess,
                                                  const IString& rActionKey,
                                                  const IString& rActionValue,
                                                  bool bFailOnError,
                             IXProcessMonitor::EMonitorErrorLevel eErrorState)
      {
        ...
      }

      ...
       
      // Memory Management
      MEMORY_MANAGER_INLINEIMPL()
      MEMORY_MANAGER_IMPL_END;

    private:
  };

2.1 Dry run

The dry run allows to run all processes without taking any actions (such as copying or deleting files). The dry run can be used to establish to number of files, actions or other items to be processed by a monitor. We often use this to set the maximum of a progress bar or precalculate a processing time.

2.2 Regular run

All processes of a traget and the dependend targets are executed. If a process fails the execution is aborted and an error is returned. This mode can be used to run critical targets or if a result of a target is used as input for a next target.

2.3 Regular run without abort

All processes of a traget and the dependend targets are executed. If a process fails the execution is NOT aborted. The error is only passed to a registered monitor object. We use this mode mostly for checking of states. Here it is not really critical, but we want to find all bugs at once.


3. Class structure

The Zeus-Framework provides various classes and interface to run the XML Batches.

  • TXMLBatchProcessor: Is the base to load an xml batch.
  • IXProcessMonitor: Interface to define a monitor. The monitor receives callbacks of the running processes. The state, errors and results of each process can be evaluated here.
  • TBatchContext: The batch context object provides additional information for the processing. The context object can contain objects used by specialized or customized processing objects.
  • TXProcProject: contains the whole structure of the XML Batch File. It is internally used by the TXMLBatchProcessor object.
  • TXProcTraget: Can be executed by a batch processor.
    • Name: Name of the target
    • Depends: Optional the target can define dependency targets. All dependency targets are executed before the target is processed. All dependency targets are listed in the depends attribute, seperated by [;].

The Zeus-Framework provides following processing steps:

  • TXProcCall: calls a target explicilty.
    • Name: Name of the target to be executed.
  • TXProcGroup: Wrapps different processes to a logical group
    • Name: Name of the group. Only used for monitoring.
    • Combination: Logical combination of the grouped processes. Default value is OR, the group processing ends after the first successfully executed process. With AND all processes has to end successfully.
  • TXProcCopy: Copies one or more files from a source to a target directory
    • SourceDir: Must parameter. Declares the source directory.
    • SourceFile: Must parameter. Declares the source files. Wildcards can be used.
    • TargetDir: Must parameter. Declares the target directory.
    • TargetFile: Optional parameter. Name of the target file. If none is given then the original file name is used. Use this parameter to rename a file while copying.
    • FailOnError: Optional parameter. If set to one an error is returned if a copy operation fails.
    • Recursive: Optional parameter. Copies all files and folders recursively.
    • Forced: Optional parameter. If set also write protected files are overwritten. Default is 0.
  • TXProcDelete: Removes one or more files from a directory
    • TargetDir: Must parameter. Target directory which contains files to remove.
    • TargetFile: Must parameter. File to remove. Wildcards can be used.
    • RemoveEmptyDir: Optional parameter. If the last file is removed and the parameter is set to 1 the folder is also removed.
    • FailOnError: Optional parameter. If set to one an error is returned if a delete operation fails.
    • Recursive: Optional parameter. Deletes all files and folders recursively.
    • Forced: Optional parameter. If set also write protected files are removed. Default is 0.
  • TXProcProperty: Sets a property value for further processing
    • Name: Name of the property.
    • Value: Value of the property.