User: schaefera
  Date: 02/01/20 06:10:42

  Modified:    src/xdocs/howto howtotimer.2.xml
  Log:
  Update the Scheduler documentation to be up to date with the Scheduler 
implementation.
  
  Revision  Changes    Path
  3.2       +151 -25   manual/src/xdocs/howto/howtotimer.2.xml
  
  Index: howtotimer.2.xml
  ===================================================================
  RCS file: /cvsroot/jboss/manual/src/xdocs/howto/howtotimer.2.xml,v
  retrieving revision 3.1
  retrieving revision 3.2
  diff -u -r3.1 -r3.2
  --- howtotimer.2.xml  2002/01/18 10:25:25     3.1
  +++ howtotimer.2.xml  2002/01/20 14:10:42     3.2
  @@ -451,21 +451,31 @@
            </note>
         </para>
         <para>
  -         To use the Scheduler your class receiving the Time Notification must 
implement the Schedulable
  -         interface. Then whenever an appropriate Time Notification comes in, its 
<function>perform</function>
  -         method will be called. It contains two parameters. The first is the time 
when the notification is
  -         sent and the second is the number of remaining occurrencies (where -1 
means no limit).
  +         To use the Scheduler you need a target which the Scheduler will call when 
the Timer sends
  +         a notification based on your settings. This can be either an instance of a 
class implementing
  +         the Schedulable interface (which will be created by the Scheduler) or 
another MBean available
  +         in the JMX MBeanServer of JBoss. From now on we will call this a 
Schedulable (class / instance
  +         or MBean).
         </para>
  -      <para>
  -         The example coming with the Scheduler what a Schedulable class should look 
like is
  -         the internal class SchedulableExample. It just takes a name and a value 
used to identify
  -         the log when a timed call comes in. To create a Schedulable class just 
build a Constructor
  -         taking basic data types, String or any other class having a constructor 
taking a single String
  -         as parameter. Then implement the <function>perform</function> method where 
you can use the
  -         given date of call, number of remaining repetitions and the value set by 
the constructor.
  -         The <function>perform</function> method can start backups, nightly data 
transfers, purge old
  -         data from the DB etc. The default example looks like this:
  -         <programlisting><![CDATA[
  +      <orderedlist>
  +         <listitem>
  +            <para>
  +               When you want to use a Schedulalbe instance then you have to create 
a class with
  +               implement the Schedulable interface. Then whenever an appropriate 
Time Notification
  +               comes in, its <function>perform</function> method will be called. It 
contains two
  +               parameters. The first is the time when the notification is sent and 
the second is the
  +               number of remaining occurrencies (where -1 means no limit).
  +            </para>
  +            <para>
  +               The example coming with the Scheduler what a Schedulable class 
should look like is
  +               the internal class SchedulableExample. It just takes a name and a 
value used to identify
  +               the log when a timed call comes in. To create a Schedulable class 
just build a Constructor
  +               taking basic data types, String or any other class having a 
constructor taking a single String
  +               as parameter. Then implement the <function>perform</function> method 
where you can use the
  +               given date of call, number of remaining repetitions and the value 
set by the constructor.
  +               The <function>perform</function> method can start backups, nightly 
data transfers, purge old
  +               data from the DB etc. The default example looks like this:
  +               <programlisting><![CDATA[
      public static class SchedulableExample
         implements Schedulable
      {
  @@ -492,13 +502,23 @@
               ", test, name: " + mName + ", value: " + mValue );
         }
      }
  -         ]]></programlisting>
  -      </para>
  -      <para>
  -         The last step of the preparation is that all the new classes coming along 
with
  -         your Schedulable must be made available to the JMX agent. Therefore you 
have to add
  -         it to the classpath or with JBoss 3 reference the JAR file in the 
service.xml file.
  -      </para>
  +               ]]></programlisting>
  +            </para>
  +            <para>
  +               The last step of the preparation is that all the new classes coming 
along with
  +               your Schedulable must be made available to the JMX agent. Therefore 
you have to add
  +               it to the classpath or with JBoss 3 reference the JAR file in the 
service.xml file.
  +            </para>
  +         </listitem>
  +         <listitem>
  +            <para>
  +               When you want to use another MBean to be called by the Scheduler you 
must make
  +               sure that the MBean is available to the JMX Agent of the JBoss 
server. It must be
  +               loaded when the first call is made from the Scheduler otherwise the 
call wil not
  +               be made but the number of repetitions will be decreased (if not 
endless).
  +            </para>
  +         </listitem>
  +      </orderedlist>
      </section>
      
      <section id = "scheduler-usage">
  @@ -509,9 +529,13 @@
            create your own scheduler-service.xml file. When you use a JMX Connector 
then you
            can create the Scheduler MBean, set the Attributes and then invoke the 
<function>
            init</function> and <function>start</function> methods (please have a look 
at the
  -         timer-usage above for more informations). To setup a Scheduler in a 
service.xml file
  -         add this code snippet and adjust it:
  -         <programlisting><![CDATA[
  +         timer-usage above for more informations). The Scheduler can be setup in 
two ways.
  +         <orderedlist>
  +            <listitem>
  +               <para>
  +                  To setup a Scheduler in a service.xml file using a Schedulable 
class add
  +                  this code snippet and adjust it to your needs:
  +                  <programlisting><![CDATA[
     <mbean code="org.jboss.util.Scheduler" name=":service=Scheduler">
       <attribute 
name="SchedulableClass">org.jboss.util.Scheduler$SchedulableExample</attribute>
       <attribute name="InitArguments">Schedulabe Test,12345</attribute>
  @@ -521,7 +545,39 @@
       <attribute name="NrOfRepetitions">-1</attribute>
       <attribute name="StartAtStartup">true</attribute>
     </mbean>
  -         ]]></programlisting>
  +                  ]]></programlisting>
  +               </para>
  +            </listitem>
  +            <listitem>
  +               <para>
  +                  To setup a Scheduler in a service.xml file using a Schedulable 
MBean add
  +                  this code snippet and adjust it to your needs:
  +                  <programlisting><![CDATA[
  +  <mbean code="org.jboss.util.SchedulableExample" 
name="jboss:type=example,name=schedulable">
  +  </mbean>
  +  <mbean code="org.jboss.util.Scheduler" name="jboss:service=Scheduler">
  +    <attribute name="StartAtStartup">true</attribute>
  +    <attribute 
name="SchedulableMBean">jboss:type=example,name=schedulable</attribute>
  +    <attribute name="SchedulableMBeanMethod">hit( NOTIFICATION, DATE, REPETITIONS, 
SCHEDULER_NAME, java.lang.String )</attribute>
  +    <attribute name="InitialStartDate">NOW</attribute>
  +    <attribute name="SchedulePeriod">10000</attribute>
  +    <attribute name="InitialRepetitions">10</attribute>
  +  </mbean>
  +                  ]]></programlisting>
  +                  Note that the first MBean is the target (Schedulable) MBean which 
is created
  +                  before the Scheduler. This is not necessary especially when you 
want to use
  +                  JBoss MBeans but they should be available when the first hit (see 
initial start
  +                  date) from the Timer is in.
  +               </para>
  +            </listitem>
  +         </orderedlist>
  +         <important>
  +            <para>
  +               Do NOT mix these two types. The last call to either 
<function>setSchedulableClass</function>
  +               or <function>setSchedulableMBean</function> will determine if a 
Schedulable Class or
  +               MBean is used.
  +            </para>
  +         </important>
            <variablelist>
               <varlistentry>
                  <term>SchedulableClass</term>
  @@ -566,6 +622,64 @@
                  </listitem>
               </varlistentry>
               <varlistentry>
  +               <term>SchedulableMBean</term>
  +               <listitem>
  +                  <para>
  +                     Object Name of the MBean you want to be called when timer send 
a notification.
  +                     Note that this must not be null and must be a valid JMX Object 
Name.
  +                  </para>
  +               </listitem>
  +            </varlistentry>
  +            <varlistentry>
  +               <term>SchedulableMBeanMethod</term>
  +               <listitem>
  +                  <para>
  +                     Can contain two parts. The first is the method name which must 
be in front of
  +                     the opening bracket. The second is inside the opening and 
closing bracket. There
  +                     must not be any other characters after the closing bracket 
except white spaces
  +                     which will be trimmed away with 
<function>java.lang.String.trim()</function>.
  +                     The second part must be a comma seperated list of the 
following items (if written
  +                     in uppercase then this literal without the colon):
  +                     <itemizedlist>
  +                        <listitem>
  +                           <para>
  +                              NOTIFICATION: Timer Notification object sent by the 
Timer. The signature
  +                              is: javax.management.Notification.
  +                           </para>
  +                        </listitem>
  +                        <listitem>
  +                           <para>
  +                              DATE: Date instance when the timer sent the call. The 
signature is:
  +                              java.util.Date.
  +                           </para>
  +                        </listitem>
  +                        <listitem>
  +                           <para>
  +                              REPETITIONS: Number of remaining repetitions. The 
signature is: long.
  +                           </para>
  +                        </listitem>
  +                        <listitem>
  +                           <para>
  +                              SCHEDULER_NAME: Object Name of the Scheduler calling 
the MBean. With
  +                              this Object Name you can call back and investigate 
the Scheduler. The
  +                              signature is: javax.management.ObjectName.
  +                           </para>
  +                        </listitem>
  +                        <listitem>
  +                           <para>
  +                              Anything else will be treated as fully qualified 
Class name where the
  +                              Scheduler send a "null" as value but this Class as 
signature. This
  +                              method is here to satisfy your method signature.
  +                           </para>
  +                        </listitem>
  +                     </itemizedlist>
  +                     When you omit the method name "perform" will be set. If you 
omit the parameter
  +                     list (second part) then the same signature as 
<function>perform</function> of
  +                     the Schedulable instance will be assumed.
  +                  </para>
  +               </listitem>
  +            </varlistentry>
  +            <varlistentry>
                  <term>InitialStartDate</term>
                  <listitem>
                     <para>
  @@ -640,6 +754,18 @@
            performed. Whenever you stop the Scheduler with argument "false" the 
<function>isRestartPending
            </function> returns "true" until the Scheduler is stopped. The other 
<function>stopService</function>
            belongs to the life-cycle of the MBean and should only be used in this 
context.
  +      </note>
  +      <note>
  +         The Scheduler is showing this message when the Scheduler remaining 
repetitions went to 0
  +         and became inActive:
  +         <programlisting><![CDATA[
  +02:12:00,908 ERROR [Default] java.lang.NullPointerException
  +02:12:00,908 ERROR [Default]    at 
javax.management.timer.Timer.updateTimerTable(Timer.java:984)
  +02:12:00,908 ERROR [Default]    at 
javax.management.timer.Timer.notifyAlarmClock(Timer.java:1093)
  +02:12:00,918 ERROR [Default]    at 
javax.management.timer.TimerAlarmClock.run(Timer.java:1165)
  +         ]]></programlisting>
  +         Please just ignore this message because it is catched and then reported 
inside JMX. It seems
  +         to be a bug from a bug fix of Sun.
         </note>
      </section>
      
  
  
  

_______________________________________________
Jboss-development mailing list
[EMAIL PROTECTED]
https://lists.sourceforge.net/lists/listinfo/jboss-development

Reply via email to