1  /*
     2   * Licensed to the Apache Software Foundation (ASF) under one or more
     3   *  contributor license agreements.  The ASF licenses this file to You
     4   * under the Apache License, Version 2.0 (the "License"); you may not
     5   * use this file except in compliance with the License.
     6   * You may obtain a copy of the License at
     7   *
     8   *     http://www.apache.org/licenses/LICENSE-2.0
     9   *
    10   * Unless required by applicable law or agreed to in writing, software
    11   * distributed under the License is distributed on an "AS IS" BASIS,
    12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    13   * See the License for the specific language governing permissions and
    14   * limitations under the License.  For additional information regarding
    15   * copyright in this work, please see the NOTICE file in the top level
    16   * directory of this distribution.
    17   */
    18  
    19  package org.apache.roller.weblogger.business.runnable;
    20  
    21  import java.util.Date;
    22  import java.util.Enumeration;
    23  import java.util.Properties;
    24  import org.apache.commons.logging.Log;
    25  import org.apache.commons.logging.LogFactory;
    26  import org.apache.roller.weblogger.WebloggerException;
    27  import org.apache.roller.weblogger.config.WebloggerConfig;
    28  import org.apache.roller.util.DateUtil;
    29  
    30  
    31  /**
    32   * An abstract class representing a scheduled task in Roller.
    33   *
    34   * This class extends the java.util.TimerTask class and adds in some Roller
    35   * specifics.
    36   */
         /* 
    P/P   *  Method: void org.apache.roller.weblogger.business.runnable.RollerTask()
          */
    37  public abstract class RollerTask implements Runnable {
    38      
             /* 
    P/P       *  Method: org.apache.roller.weblogger.business.runnable.RollerTask__static_init
              * 
              *  Postconditions:
              *    init'ed(log)
              */
    39      private static Log log = LogFactory.getLog(RollerTask.class);
    40      
    41      
    42      /**
    43       * Initialization.  Run once before the task is started.
    44       */
    45      public void init() throws WebloggerException {
    46          // no-op by default
             /* 
    P/P       *  Method: void init()
              */
    47      }
    48      
    49      
    50      /**
    51       * Get the unique name for this task.
    52       *
    53       * @return The unique name for this task.
    54       */
    55      public abstract String getName();
    56      
    57      
    58      /**
    59       * Get the unique id representing a specific instance of a task.  This is
    60       * important for tasks being run in a clustered environment so that a 
    61       * lease can be associated with a single cluster member.
    62       *
    63       * @return The unique client identifier for this task instance.
    64       */
    65      public abstract String getClientId();
    66      
    67      
    68      /**
    69       * When should this task be started?  The task is given the current time
    70       * so that it may determine a start time relative to the current time, 
    71       * such as the end of the day or hour.
    72       *
    73       * It is acceptable to return the currentTime object passed in or any other
    74       * time after it.  If the return value is before currentTime then it will
    75       * be ignored and the task will be started at currentTime.
    76       *
    77       * @param currentTime The current time.
    78       * @return The Date when this task should be started.
    79       */
    80      public abstract Date getStartTime(Date currentTime);
    81      
    82      
    83      /**
    84       * Get a string description of the start time of the given task.
    85       * 
    86       * Should be one of ... 'immediate', 'startOfDay', 'startOfHour'
    87       * 
    88       * @return The start time description.
    89       */
    90      public abstract String getStartTimeDesc();
    91      
    92      
    93      /**
    94       * How often should the task run, in seconds.
    95       *
    96       * example: 3600 means this task runs once every hour.
    97       *
    98       * @return The interval the task should be run at, in minutes.
    99       */
   100      public abstract int getInterval();
   101      
   102      
   103      /**
   104       * Get the time, in seconds, this task wants to be leased for.
   105       *
   106       * example: 300 means the task is allowed 5 minutes to run.
   107       *
   108       * @return The time this task should lease its lock for, in minutes.
   109       */
   110      public abstract int getLeaseTime();
   111      
   112      
   113      /**
   114       * Get the properties from WebloggerConfig which pertain to this task.
   115       * 
   116       * This extracts all properties from the WebloggerConfig of the type
   117       * task.<taskname>.<prop>=value and returns them in a properties object
   118       * where each item is keyed by <prop>.
   119       */
   120      protected Properties getTaskProperties() {
   121          
                 /* 
    P/P           *  Method: Properties getTaskProperties()
                  * 
                  *  Preconditions:
                  *    org/apache/roller/weblogger/config/WebloggerConfig.config != null
                  *    org/apache/roller/weblogger/config/WebloggerConfig.log != null
                  * 
                  *  Presumptions:
                  *    java.util.Enumeration:nextElement(...)@129 != null
                  *    java.util.Properties:keys(...)@205 != null
                  * 
                  *  Postconditions:
                  *    return_value == &new Properties(getTaskProperties#2)
                  *    new Properties(getTaskProperties#2) num objects == 1
                  * 
                  *  Test Vectors:
                  *    java.lang.String:startsWith(...)@131: {0}, {1}
                  *    java.util.Enumeration:hasMoreElements(...)@128: {0}, {1}
                  */
   122          String prefix = "tasks."+this.getName()+".";
   123          
   124          Properties taskProps = new Properties();
   125          
   126          String key = null;
   127          Enumeration keys = WebloggerConfig.keys();
   128          while(keys.hasMoreElements()) {
   129              key = (String) keys.nextElement();
   130              
   131              if(key.startsWith(prefix)) {
   132                  taskProps.setProperty(key.substring(prefix.length()), 
   133                          WebloggerConfig.getProperty(key));
   134              }
   135          }
   136          
   137          // special addition for clientId property that applies to all tasks
   138          taskProps.setProperty("clientId", WebloggerConfig.getProperty("tasks.clientId"));
   139          
   140          return taskProps;
   141      }
   142      
   143      
   144      /**
   145       * A convenience method for calculating an adjusted time given an initial
   146       * Date to work from and a "changeFactor" which describes how the time 
   147       * should be adjusted.
   148       *
   149       * Allowed change factors are ...
   150       *   'immediate' - no change
   151       *   'startOfHour' - top of the hour, beginning with next hour
   152       *   'startOfDay' - midnight, beginning on the next day
   153       */
   154      protected Date getAdjustedTime(Date startTime, String changeFactor) {
   155          
                 /* 
    P/P           *  Method: Date getAdjustedTime(Date, String)
                  * 
                  *  Postconditions:
                  *    init'ed(return_value)
                  * 
                  *  Test Vectors:
                  *    changeFactor: Inverse{null}, Addr_Set{null}
                  *    startTime: Addr_Set{null}, Inverse{null}
                  *    java.lang.String:equals(...)@162: {0}, {1}
                  *    java.lang.String:equals(...)@164: {0}, {1}
                  */
   156          if(startTime == null || changeFactor == null) {
   157              return startTime;
   158          }
   159          
   160          Date adjustedTime = startTime;
   161          
   162          if("startOfDay".equals(changeFactor)) {
   163              adjustedTime = DateUtil.getEndOfDay(startTime);
   164          } else if("startOfHour".equals(changeFactor)) {
   165              adjustedTime = DateUtil.getEndOfHour(startTime);
   166          }
   167          
   168          return adjustedTime;
   169      }
   170      
   171  }