VDoc agents

VDoc provides a system to plan the tasks execution. It is the "Agent" classes. These agent classes are very simple Java classes that can be planned from the administration.

To create an agent, you just have to create a class that branch off BaseAgent (the RunnableAgent class is then obsolete). By branching off the class BaseAgent, you have to implement the execute() method.

The BaseAgent class

The class com.axemble.vdoc.sdk.agent.base.BaseAgent is the class of any agent inside the VDoc system. By branching off this base class, your class will automatically be known as agent and may be planned or manually executed via the administration interface. This agent class gives a direct access to the APIs. It permits also to register information or error messages in the agent execution log.

Methods of the BaseAgent class

  public abstract class BaseAgent extends ... 
  
  // method to implement 
  protected abstract void execute();

  // helper methods
  
  final protected IWorkflowModule getWorkflowModule() 
  
  final protected void printInfo( String message ) 
  
  final protected void printError( String message ) 
  
  final protected void printSeparator() 
  
  final protected void printLine()

Code extract of the LogAgent class

The following code recovers every documents of an application and registers their reference and title in the agent execution log.

public class LogAgent extends BaseAgent 
{ 
        public void execute() 
        { 
                IContext processContext = getWorkflowModule().getContextByLogin( "sysadmin" ); 
                ICatalog catalog = getWorkflowModule().getCatalog( processContext, "Education" ); 
                // recover an external reference (you must define it)!) 
                IJdbcReference jdbcReference = getWorkflowModule().getJdbcReference( processContext, "vdocDatabase" ); 
                // recover a controller to perform searches 
                ISearchController searchController = getWorkflowModule().getSearchController( jdbcReference ); 
                // recover all the documents 
                this.printSeparator(); 
                this.printInfo( "Recovering all documents of the specified database" ); 
                this.printSeparator(); 
                this.printLine(); 
                Collection worflowInstances = searchController.findElements
                ( 
                        IWorkflowInstance.class, "select id from vdp_treatments where ref_catalog=?", new Object[] 
                                { 
                                        catalog.getId().toString() 
                                } 
                ); 
                for ( Iterator iter = worflowInstances.iterator() ; iter.hasNext() ; )
                { 
                        IWorkflowInstance workflowInstance = (IWorkflowInstance)iter.next(); 
                        this.printInfo( "REFERENCE : " + (String)workflowInstance.getValue( "sys_Reference" ) ); *
                        this.printInfo( "TITLE : " + (String)workflowInstance.getValue( "sys_Title" ) ); 
                        this.printInfo( "IDENTIFIER : " + workflowInstance.getId().toString() ); 
                        this.printLine(); 
                } 
                this.printInfo( "Operation ended successfully" ); 
                this.printSeparator(); 
        } 
}

Managing transactions

The agents are executed, by default, in a non-transactional context. If you want to process treatments inside a transaction, you should use the methods beginTransaction, commitTransaction and rollbackTransaction of the IWorkflowModule module.

Code extract using transactions

The following code shows the implementation of a transaction inside the workflow module.

try 
{ 
        // starting a transaction getWorkflowModule().beginTransaction( this ); ... 
        // validating the transaction getWorkflowModule().commitTransaction( this ); 
} 
catch( Exception e ) 
{ 
        // in case of exception, cancel the treatment getWorkflowModule().rollbackTransaction( this ); 
}

Running the agents by programming

From the VDoc APIs, it is possible to trigger the processing of an agent defined in the Process management.

Example of executing an agent by API

This code extract enables to show how to retrieve an agent by its name and execute it.

// retrieving an agent by its name 
IAgent agent = getWorkflowModule().getAgent( getWorkflowModule().getLoggedOnUserContext(), "Name of the agent" ); 
// executing the retrieved agent 
getWorkflowModule().execute( agent );