ERP 2.50:Background Process
Contents |
Introduction
To schedule repetitive tasks within Openbravo, background processes are used. We will present how they are developed, defined and scheduled within this section.
Files Involved
All background processes are stored in $OPENBRAVO_HOME/src/org/openbravo/erpCommon/ad_background folder. There are already a few predefined background processes within the application such as PeriodicAcctServer (accounting), PeriodicAlert (alert process) and PeriodicHeartbeat (heartbeat operation). You can always peek at these to see how these functionalities have been implemented.
We will take the PeriodicAlert example to explain the elements involved with background processes.
The following files are involved (in sequence of execution):
- $OPENBRAVO_HOME/src/org/openbravo/base/PeriodicBackgroundContextListener.java - this object is initialized upon the start of the web application and starts the background processes
- $OPENBRAVO_HOME/src/org/openbravo/erpCommon/ad_background/PeriodicBackground.java - for each background process, an instance of this object is created in a separate thread. This object then executes the background process' code.
- $OPENBRAVO_HOME/src/org/openbravo/erpCommon/ad_background/BackgroundProcess.java - file just defines an interface that our background process needs to implement.
- $OPENBRAVO_HOME/src/org/openbravo/erpCommon/ad_background/PeriodicAlert.java - this is where the code of our actual process resides. Together with PeriodicAlert_data.xsql, these are the only files you will need to write.
- $OPENBRAVO_HOME/src/org/openbravo/erpCommon/ad_background/PeriodicAlert_data.xsql - this is the model (according to MVC principles) description file that our process uses to execute data manipulation and retrieval statements. This file follows typical SQLC rules, is in the same package as PeriodicAlert class and is referred within it.
PeriodicBackgroundContextListener.java
The main background processing object (org.openbravo.base.PeriodicBackgroundContextListener) is initialized upon the start of the web application (context). The constructor of this object (contextInitialized) retrieves all background processes defined within the application (AD_PROCESS table, isbackground=Y) and creates an individual instance of PeriodicBackground class for each one of the marked Active. It also starts them and saves a hashmap of all background processes within the context's runtime session (context.setAttribute(BACKGROUND_ATTRIBUTE, backgroundProcess)).
The destructor (contextDestroyed) of this object safely stops all background processes upon stopping of the web application.
This object is defined to be started within the web.xml of the application server configuration file:
<listener> <listener-class>org.openbravo.base.PeriodicBackgroundContextListener</listener-class> </listener>
PeriodicBackground.java
PeriodicBackground implements all the thread control (start, stop, pause) so you do not need to worry about it. You should not need to ever change this file.
The class is instantiated by the PeriodicBackgroundContextListener, once for each background process defined. The constructor of this class has the following parameters:
- connectionProvider: an instance of the object that contains the pool of connections
- _seconds: seconds between each execution of the background process (parameter defined in the web.xml file)
- _logFileString: unique name of the logfile that stores the PID of the process
- _adProcessId: process identifier (primary key of within the AD_PROCESS table) in the Application Dictionary.
- _objectName: the name of the class that PeriodicBackground must run.
The constructor creates a new thread for itself. This thread is then started by the PeriodicBackgroundContextListener by calling the start() method of the PeriodicBackground class which in turn calls the start() method of the runner (thread) object.
The run() method of the PeriodicBackground class is now automatically executed and this then calls the processPL() method that the PeriodicAlert needs to implement. This method then contains the actual execution of this background process (in our case, check for any pending alerts).
BackgroundProcess.java
Each background process created in the application must implement the BackgroundProcess interface, which defines a processPL(PeriodicBackground, boolean) that needs to be implemented. This method is called within the run() method of the PeriodicBackground class.
See how PeriodicAlert implements this interface:
package org.openbravo.erpCommon.ad_background;
import org.openbravo.erpCommon.utility.SequenceIdData;
import org.openbravo.erpCommon.businessUtility.EMail;
import org.openbravo.erpCommon.utility.Utility;
public class PeriodicAlert implements BackgroundProcess {
public String batchSize="50";
static int counter = 0; // This variable might be used in order to define how often an alert is going to be executed.
public void processPL(PeriodicBackground periodicBG, boolean directProcess) throws Exception {
counter ++;
periodicBG.addLog("Starting Alert Backgrouond Process. Loop "+counter);
PeriodicAlertData [] alertRule = PeriodicAlertData.selectSQL(periodicBG.conn);
PeriodicAlert.java
ProcessPL has two parameters: PeriodicBackground object, where we obtain the connection pool and information about the login (user, client, organization, ....). Boolean: indicates if the process is being launched manually or it is a scheduled job.
Background Processes in the Application Dictionary
To register a Background process in the application, a new record in the Application Dictionary || Report and Process window must be created:
- Enter the search key and name
- Check background checkbox
- Enter the Java Class Name of the class that implements the background process (note that the Process Class tab stays empty!)
Important note:
There is a bug in the version 2.3x of the application because this field is hidden. To display it, mark it as Active in the “Report and Process” record in “Window, tabs and fields” window. Make sure you also recompile that particular window (ant compile.development -Dtab=Process). |
Compiling the Background Process
After introducing the background process to the application dictionary and putting the file(s) inside the correct folder ($OPENBRAVO_HOME/src/org/openbravo/erpCommon/ad_background) we need to recompile the application.
Since background processes are manual code, the following line does the job:
ant compile.development -Dtab=xx
Scheduling
Once the background process is registered in the application and compiled, it must be scheduled. This way, the system will know when to run the new background process.
To do that, go to "General Setup || Application || Process Scheduling" window and enter a new record:
- Process: background process to be executed
- Weekday: select which day of the week the process should be executed or leave empty for every day
- Starting Time: time of the day when execution should commence on the day of the week selected above
- Ending Time: time of the day when the system should stop executing the process
- Full Time: check this if the process needs to be executed repetitively between Starting Time and Ending Time
Let's look at two different scenarios
- Full time process that needs to be executed all the time
- Weekday: empty
- Starting Time: 00:00:01
- Ending Time: empty
- Full Time: checked
- A process that needs to be executed every friday afternoon after work
- Weekday: Friday
- Starting Time: 19:00:00
- Ending Time: 19:00:10
- Full Time: unchecked
Status
Finally, the "General Setup || Application || Background Process" form is used to deactivate or activate the background processes as well as see their logs.
