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