H-Sphere Documentation Developer Guide

 

Adding Custom CP Cron Jobs

(version 2.4 and higher)

 

Related Docs:   CP Cron Configuration

CP cron jobs are internal H-Sphere Java utilities that perform regular tasks such as accounting, trouble ticket management, etc.

Starting from HS 2.4, it is possible to manage crons in XML configuration files and to add custom cron jobs.

To add a new cron job:

  1. Log in as the cpanel user:

    su -
    su - cpanel

  2. Create the cron job class

    1) You need to inherit the psoft.hsphere.cron.Cron class and implement the following two abstract methods:

    - protected abstract void cronAction() throws Exception - implements the action performed by the given cron job; and
    - protected abstract String getDBMark(); - returns the unique cron job identifier (name) used in cron_config.xml.

    2) The custom cron job class should have 2 constructors:

    public CustomCron(long sleepPeriod, CP cp) throws Exception {
    super(sleepPeriod, cp);
    }

    public CustomCron(Long sleepPeriod, CP cp) throws Exception {
    super(sleepPeriod, cp);
    }

    3) The structure of the cron job class should be as follows:

    package custom.cron;
    import ../../HSdocumentation/devel/psoft.hsphere._.css;
    import ../../HSdocumentation/devel/psoft.hsphere.cron._.css;
    import ../../HSdocumentation/devel/psoft.util._.css;
    import ../../HSdocumentation/devel/java.util.Date.css;
    public class CustomCron extends Cron {
       public CustomCron(long sleepPeriod, CP cp) throws Exception {
           super(sleepPeriod, cp);
       }
       public CustomCron(Long sleepPeriod, CP cp) throws Exception {
           super(sleepPeriod, cp);
       }
       protected String getDBMark() {
           return "CUSTOM_CRON";
       }
       protected void cronAction() throws Exception {
           cronWait(); // stops the cron job if it is disabled in cron_config.xml (disabled="1");
                       // ignored if disabled="0"
           Date startDate = TimeUtils.getDate();
           try {
               // here you type in your custom cron job actions
               // NOTE: you may add several cronWait(); calls in the code
           } catch (Exception ex) {
               Session.getLog().warn("Custom cron error", ex);
           } catch (Throwable ex) {
               Session.getLog().warn("Custom cron error", ex);
           } finally {
               // here you put some final actions
           }
           long timeDiff = TimeUtils.currentTimeMillis() - startDate.getTime();
           Session.getLog().info("Custom Cron FINISHED. Process took: " +
               timeDiff / 60000 + " min " +
               (timeDiff - timeDiff / 60000 * 60000) / 1000 + " sec");
       }
    }
    
  3. Add the custom cron job class to CLASSPATH

    CLASSPATH is set in the .bash_profile file located in the cpanel home directory.

  4. Create the custom cron XML configuration file if it is not created yet

    We recommend to add all custom cron jobs into the custom cron configuration file, not to the standard cron XML configuration file.

    1) Create the custom cron configuration file, for example, /hsphere/local/home/cpanel/shiva/custom/xml/cron_config.xml

    2) The XML structure of the custom cron config file should be the same as of the standard cron configuration file.

    DTD scheme | Example

    3) Set the full pathname to the custom cron configuration file in hsphere.properties (/hsphere/local/home/cpanel/shiva/psoft_config/hsphere.properties):

    CRON_CONFIG = /hsphere/local/home/cpanel/shiva/custom/xml/cron_config.xml

  5. Add the custom cron job to the custom cron configuration file

    1) If the custom cron configuration is not created, create it according to the procedure specified in the previous step.

    2) Add a new group of jobs if required or add your custom cron job there, or, add your custom job to an existing group. Group is set by the group tag. Jobs are set in the cron tags within their groups. For example:

    <config>
    ...
      <group name="GroupN" maxpriority="10" defpriority="3">
      <!-- priority of jobs within the group is ranked from 1 to 10;
           if job priority is not specified, it is 3 by default -->

      ...
        <job name="CustomCron" class="custom.cron.CustomCron"
          starttime="5:00" period="1440"/>
        <!-- job starts every day (1440 minutes) at 5am -->
      ...
      <group>
    </config>

    XML syntax is described in the CP Cron Configuration guide.

    Read how to merge XML config files in Customization Guide.


Related Docs:   CP Cron Configuration



Home   Products   Services   Partners   Support   News   Contact   Forum
© 2020 psoft.net.
All rights reserved.