Tutorial: Basics

This tutorial shows in four steps how to connect JUseCase to your application, and how to set it up. If you bump into an unknown concept or term, take a look in the concepts or the API section.

Adding event recorders/simulators

The main work of connecting JUseCase to an application is to add event recorders/simulators, i.e., objects that handles the conversion between GUI events, such as button clicks, to user defined use case commands, such as "quit". In recording mode, when events are detected by the recorder/simulator objects, the corresponding use case commands are written to a plaintext file - the use case script - which can later be used in replaying mode. In replaying mode, JUseCase will read the use case, and for each line look up the corresponding recorder/simulator which then simulates the event that corresponds to the command read from the file.

So, to get started, let's create a very simple GUI application (source code available here). The application, when started, shows a message window, and to exit the application you just close the window. For now, the only interaction we're interested in is precisely this - closing the window.

In the source code there are five lines that are related to JUseCase, and they are decribed below.

First we have the imports. ScriptEngine is the class responsible for controlling the record/replay mechanism, and ScriptedWindow is the recording/simulator object that handles Window events.

import jusecase.ScriptEngine; import jusecase.components.ScriptedWindow;

The statement below informs JUseCase that the event of closing the window is associated with the use case command "quit". That is, when JUseCase detects this event, via the ScriptedWindow object, "quit" is recorded to the use case script. In replaying mode it's the other way around - "quit" is read from the use case script and the CLOSING event is generated for the window.

NB: When setting up recorders/replayers like this, what usually happens is that some kind of event listener is attached to the component (e.g. WindowListener attached to a Window). It's usually a good idea to let these JUseCase added listeners be the first listeners that are notified of the events they listen for (listeners are notified sequentially). Since the Sun Java implementation notifies listeners in the reverse order that they are added, you should connect the component to JUseCase after you have added all application specific listeners.

ScriptedWindow.connect("quit", this);

This statement makes sure that all detected events are flushed to the use case script and that the file is properly closed.

ScriptEngine.instance().shutDown();

Starts the JUseCase replayer if the jusecase.properties file contains the line "replay=[name of use case script file]", otherwise the statement does nothing. The replay statement should be one of the last ones before handing over the control to the user, i.e. after all initial GUI components have been created - there's no use trying to replay "quit" if the main window hasn't been created yet. In a way you're handing over the control to JUseCase.

ScriptEngine.instance().replay();

This is all setup work that needs to be done in the code. Now, all you have to do is to create a configuration file and make sure that when you add an interactive GUI component you also connect the events it generates to JUseCase script commands, and you're ready to go! Check the JUseCase API for details on how to connect different components/events to JUseCase.

Creating a configuration file

In order for JUseCase to actually record/replay a use case script, you have to create a configuration file called jusecase.properties. This file should be put in the directory from where you start your application. The file supports three entries and should be very easy to understand. The entries are:

Recording a first use case

So, let's try recording a use case. Compile the application (remember to include the JUseCase jar file in classpath), and create the a jusecase.properties file containing:

record=usecase.txt

Then run the application (again, don't forget the JUseCase jar file) and wait for the main window to appear. Since the only useful interaction right now is closing the window, let's do just that. Click in the upper right corner of the window to close it.

Now you should have a file called usecase.txt in the current working directory. If you list the contents it hopefully contains the following line:

quit

Replaying the use case

So, now for the moment we've all been waiting for - replaying our newly created use case. Open up the configuration file, change record to replay, and set the delay to two seconds so that we have a chance of seeing what happens.

replay=usecase.txt delay=2

Run the application again. Sit back and watch JUseCase close the main window for you!

Event recorders/simulators in the JUseCase release

The JUseCase release package contains recorders/simulators for a set of standard Swing components, listed below. For details on how to set them up, see the API.

Conclusion

This marks the end of the first tutorial. By now you should be familiar with the most basic concepts in JUseCase. Head on over to the next tutorial for information on how to use application events.