Tutorial: Creating a Web Service with Timer Control

In this tutorial, we will create a web service that declares/instantiates a timer control (an instance of the com.bea.control.TimerControl base class) that calls back the client web service every two seconds. For this example, we will have two web service operations (web methods):

When the callback is received, the sample program will simply display text in the console window. Normally some programming logic would be inserted in the callback routine to perform some appropriate action.

To Set up Web Service and Timer Control Annotations

At this point, you have a project containing a package with a web service with the Web Service Design View (Designer pane) displayed in the editor pane.

Conversational web services must implement the java.io.Serializable interface. To set this in your web service:

Edit the source file for your web service by right clicking on the designer and choosing Edit Source. On the class definition line for your web service, insert implements Serializable so that the class definition looks something like this:
```
public class TimerService implements Serializable {
```
Note that an error marker has appeared in the marker bar on the class declaration line. Right click on the error marker and choose Quick Fix.
The Quick Fix pull-down will appear:

Click Import Serializable and press Enter and a new import line will be generated to resolve the error. Save the file with File > Save.

By default, a hello() method was inserted when you created the web service. This method is not needed.

Click on the Designer tab of your web service. Right click on the standard hello() method and choose Delete.

Confirm the deletion by clicking Yes.

To create the timer control:

Right click on the Designer pane and click New Control Reference . Under New System Control, click on Timer Control and click OK. The control declaration is inserted into the body of the class, with the name (timerControl) highlighted. If you click on the TimerControl.java tab, you can verify that the following code was inserted:
```
@Control
private TimerControl timerControl;
```
The properties of the TimerControl annotation are displayed in the Annotations view to the right. Click on the Annotations tab if it is not already open and visible.
Click in the cell under the Value column beside the repeatsEverySeconds property.

Type 2 and push the Enter key. In the source code editor window, the control annotation is updated to:
```
	@Control
	@TimerControl.TimerSettings(repeatsEverySeconds=2)
	private TimerControl timerControl;
```
and the new property value is also displayed in the Annotations view.

We now have a timer control called timerControl which will call back the web service every two seconds. Next we will define two web methods, one to start the timer control and one to stop it.

To define the web method to start the timer:

From the Designer pane, right click and choose New Web Method. A new operation (web method) is created in the editor, with the default name of the method highlighted and the properties of the web method in the Annotations view at the right. Enter the new method name: start and press the Enter key.
Right click on the start method name and choose Conversation Start from the pulldown.

Now edit the source code and replace the return; statement of the method body to call the timer start method with

timerControl.start();
System.out.println("**************");
System.out.println("Timer started");
System.out.println("**************");

The web method now looks like this:

@Conversation(Conversation.Phase.START)
@WebMethod
public void start()
{
   timerControl.start();
   System.out.println("**************");
   System.out.println("Timer started");
   System.out.println("**************");
}

To define the web method that ends the timer:

Insert a web method named stop as above.
Right click on the method name and choose Conversation Finish .
From the source code editor, change the method declaration to return a String value.

Replace the return; statement of the method body to call the timer stop method with

timerControl.stop();
System.out.println("**************");
System.out.println("Timer stopped");
System.out.println("**************");
return "ok";

The web method now looks like this:

@Conversation(Conversation.Phase.FINISH)
@WebMethod
public String stop()
{
   timerControl.stop();
   System.out.println("**************");
   System.out.println("Timer stopped");
   System.out.println("**************");
   return "ok";
}

To define the event handler for when the timer control signals that the timer has elapsed:

Right click on the Designer pane or the source code pane and choose Insert > Control Event Handler.
From the Insert Event Handler dialog, click on timerControl and click OK.

Insert the following lines into the event handler body in the source code pane:

System.out.println("***********************************");
System.out.println("Callback received from timer firing");
System.out.println("***********************************");

The event handler should look like this:

@EventHandler(field="timerControl", eventSet=TimerControl.Callback.class, eventName="onTimeout")        
protected void timerControl_Callback_onTimeout(long p0, Serializable p1) {

{
   System.out.println("***********************************");
   System.out.println("Callback received from timer firing");
   System.out.println("***********************************");
}

Save all of your changes with the File > Save command.

We now have a web service that contains:

a timer control
an operation (web method) to start the timer
an operation (web method) to stop the timer
an event handler to invoke whenever the timer elapses (every two seconds in our case)

The source for your web service should now look like this:

package timer;

import java.io.Serializable;

import javax.jws.*;
import org.apache.beehive.controls.api.bean.Control;
import com.bea.control.TimerControl;
import weblogic.jws.Conversation;
import org.apache.beehive.controls.api.events.EventHandler;

@WebService
public class TimerService implements Serializable{
	
  @Control
  @TimerControl.TimerSettings(repeatsEverySeconds=2)
  private TimerControl timerControl;
  private static final long serialVersionUID = 1L;


  @WebMethod
  @Conversation(Conversation.Phase.START)
  public void start() {
		timerControl.start();
	 System.out.println("**************");
		System.out.println("Timer started");
		System.out.println("**************"); 
  }

  @WebMethod
  @Conversation(Conversation.Phase.FINISH)
  public String stop() {
		timerControl.stop();
		System.out.println("**************");
     System.out.println("Timer stopped");
		System.out.println("**************");
		return "ok";
  }

  @EventHandler(field = "timerControl", eventSet = TimerControl.Callback.class, eventName = "onTimeout")
  protected void timerControl_Callback_onTimeout(long p0, Serializable p1) {
		System.out.println("***********************************");
		System.out.println("Callback received from timer firing");
		System.out.println("***********************************");
	 }
}

Test the Web Service / Timer Control

To test the web service and the timer control:

Right click on the editor pane and choose Run As > Run on Server. The WebLogic Test Client will run in a tab in the editor window.
Click the start button to invoke the start operation. The Test Client will display the results returned from the start operation.
Switch to the WebLogic Server console window (command prompt window with the header bar WebLogic Server - 10.0 ) to see the startup and callback results. The console window is iconized on the status bar by default. When you open the console window, you can see the timer starting and the message lines:
```
**************
Timer started
**************
```
generated by the start operation. This message will quickly scroll away, since the timer will immediately begin firing every two seconds.

The console window will then show the timer firing. Each time the timer fires, a block of status information will be displayed, including the lines:
```
***********************************
Callback received from timer firing
***********************************
      
```
that are generated by the event handler that receives callbacks when the timer fires every two seconds.
To stop the timer firing, click on the Continue this conversation link just above the start Request Summary in the body of the test client window. The test client will then display the operation(s) for the next phase of the conversation, in this case, the stop operation.
Click stop. The result of the stop operation will be displayed in the test client window:

The console window will no longer show the timer firing every two seconds, and will display the lines:
```
**************
Timer stopped
**************
```
to indicate that the stop operation was successful.