/*
 * JBoss, the OpenSource J2EE webOS
 *
 * Distributable under LGPL license.
 * See terms of license at gnu.org.
 */
package org.jboss.varia.scheduler;

/**
 * MBean interface.
 */
public interface SingleScheduleProviderMBean extends org.jboss.varia.scheduler.AbstractScheduleProviderMBean
{

   //default object name
   public static final javax.management.ObjectName OBJECT_NAME = org.jboss.mx.util.ObjectNameFactory
         .create("jboss:service=SingleScheduleProvider");

   void startProviding() throws javax.management.JMException;

   void stopProviding();

   java.lang.String getTargetName();

   /**
    * Sets the fully qualified JMX MBean Object Name of the Schedulable MBean to be called.
    * @param pTargetObjectName JMX MBean Object Name which should be called.
    * @throws InvalidParameterException If the given value is an valid Object Name.    */
   void setTargetName(java.lang.String pTargetObjectName) throws java.security.InvalidParameterException;

   java.lang.String getTargetMethod();

   /**
    * Sets the method name to be called on the Schedulable MBean. It can optionally be followed by an opening bracket, list of attributes (see below) and a closing bracket. The list of attributes can contain: <ul> <li>NOTIFICATION which will be replaced by the timers notification instance (javax.management.Notification)</li> <li>DATE which will be replaced by the date of the notification call (java.util.Date)</li> <li>REPETITIONS which will be replaced by the number of remaining repetitions (long)</li> <li>SCHEDULER_NAME which will be replaced by the Object Name of the Scheduler (javax.management.ObjectName)</li> <li>any full qualified Class name which the Scheduler will be set a "null" value for it</li> </ul> <br> An example could be: "doSomething( NOTIFICATION, REPETITIONS, java.lang.String )" where the Scheduler will pass the timer's notification instance, the remaining repetitions as int and a null to the MBean's doSomething() method which must have the following signature: doSomething( javax.management.Notification, long, java.lang.String ).
    * @param pTargetMethod Name of the method to be called optional followed by method arguments (see above).
    * @throws InvalidParameterException If the given value is not of the right format    */
   void setTargetMethod(java.lang.String pTargetMethod) throws java.security.InvalidParameterException;

   long getPeriod();

   /**
    * Sets the Schedule Period between two scheduled call.
    * @param pPeriod Time between to scheduled calls (after the initial call) in Milliseconds. This value must be bigger than 0.
    * @throws InvalidParameterException If the given value is less or equal than 0    */
   void setPeriod(long pPeriod);

   java.lang.String getDateFormat();

   /**
    * Sets the date format used to parse date/times
    * @param dateFormat The date format when empty or null the locale is used to parse dates    */
   void setDateFormat(java.lang.String dateFormat);

   java.lang.String getStartDate();

   /**
    * Sets the first scheduled call. If the date is in the past the scheduler tries to find the next available start date.
    * @param pStartDate Date when the initial call is scheduled. It can be either: <ul> <li> NOW: date will be the current date (new Date()) plus 1 seconds </li><li> Date as String able to be parsed by SimpleDateFormat with default format </li><li> Date as String parsed using the date format attribute </li><li> Milliseconds since 1/1/1970 </li> </ul> If the date is in the past the Scheduler will search a start date in the future with respect to the initial repe- titions and the period between calls. This means that when you restart the MBean (restarting JBoss etc.) it will start at the next scheduled time. When no start date is available in the future the Scheduler will not start.<br> Example: if you start your Schedulable everyday at Noon and you restart your JBoss server then it will start at the next Noon (the same if started before Noon or the next day if start after Noon).    */
   void setStartDate(java.lang.String pStartDate);

   long getRepetitions();

   /**
    * Sets the initial number of scheduled calls.
    * @param pNumberOfCalls Initial Number of scheduled calls. If -1 then the number is unlimted.
    * @throws InvalidParameterException If the given value is less or equal than 0    */
   void setRepetitions(long pNumberOfCalls);

}
