Service Orchestration Functional
Specification - Orchestration Debugging
$Revision: 1.2 $
$Date: 2006/06/13 17:00:37 $
1. Introduction
Orchestration
Debugging is a user interface and workflow that provides the user
with the ability to debug and executing BPEL process.
BPEL Debugging features are aligned
with Java Debugging; some older specifications can be found here:
The primary objective is to provide
BPEL developers with a powerful and familiar debugging environment.
Whenever possible and practical, the BPEL debugging UI will resemble
the Java debugging UI.
Window Reuse – BPEL Debugger
reuses some of the standard NetBeans debugger windows in order to
keep the user experience as familiar and common as possible across
languages.
Console window
Sessions window
Breakpoints window
Local Variables window
Window Additions – BPEL
Debugger includes some debug views that are not included in the
standard NetBeans debugger user interface. This is because the
particular nature of BPEL processing required new idioms that were
not already present in the Java debugging window set.
Window Exclusions - However, Java
and BPEL are not identical and process debugging is not identical to
java program debugging. BPEL Debugger excludes some of the debug
windows that are included in the Java debugger user interface. This
is because these windows have no relevance to the BPEL debug
experience. Their idiom is not well matched to the BPEL problem
domain.
Call Stack window – this
was not a good idiom match.
Threads window - this was not a
good idiom match.
Classes window – not
applicable to BPEL.
Source window – not
applicable to BPEL debugging. Subject to further review.
2. Use Cases and Scenarios -
Debugging
UC1: Start debug
Description:
User starts debug to be able to perform different debug activites
on the particular BPEL Engine. The examples of such activities are:
executing process instance step-by-step; inspecting process instance
variables.
Actors:
Scenario:
User selects "Attach Debugger..." in the main menu
or on the toolbar.
IDE provides a user with a list of available debuggers.
User selects “BPEL Debugger”.
IDE requests a user to enter required information to attach
to the BPEL Engine (host, port).
User submits the required information.
IDE informs the user that connection to the BPEL Engine is
being established.
If connection can not be established, user is notified and
the use case terminates.
IDE informs the user when connection is established.
Sessions window shows that new debug session is now active
for the target BPEL Engine. This debug session is made current
(see “Change
current debug session” use case).
Processes Instances window is populated with records. Each
record represents a single process instance in the BPEL Engine. Each
reacord shows the Process Type of the process instance, its ID and
current state. Records are added or removed from the Process
Instances window as new instances are created or completed, states
are updated as instances states are changed.
UC2: Toggle breakpoint
Description:
User toggles (i.e. adds or removes) a breakpoint in the
source editor to instruct a BPEL Engine to stop at the breakpoint
position when it reached by some process instance, executing by the
BPEL Engine.
Actors:
Scenario:
UC3: Process instance reaches the
breakpoint
Description:
While process instances are executing by the target BPEL Engine,
they can reach a breakpoint set by a user before. Once it happened,
BPEL Engine suspends the process instance that reached a breakpoint
and notifies the IDE about that.
Actors:
Preconditions:
Scenario:
BPEL Engine notifies the IDE that one of its process
instances has reached the breakpoint and has been suspended.
If the debug session in the context of which the breakpoint
was reached is not a current debug session, “Change
current debug session” use case is included for it.
The corresponding record in the Process Instances window is
updated – its state is set to "suspended".
If the process instance that reached a breakpoint is not a
current process instance, “Change
current process instance” use case is included for it.
“Change
current position” use case is included for the position
where the breakpoint was reached.
UC4: Step Into
Description:
Once a process instance gets suspended due to a breakpoint reach,
user may want to continue its execution step-by-step. This use case
performs a single step to the next activity. “Next”
doesn't mean it would be a syntactically next activity in the .bpel
file, but it would be an activity that the target BPEL Engine would
decide to execute next. Considering the parallel nature of the flow
activity execution, it sometimes imposible to determine which
activity is going to be executed next.
Actors:
User (initiator)
BPEL Engine
Preconditions:
Scenario
User selects "Step Into" in the main menu or on the
toolbar.
Corresponding record in the "Process Instances"
window is updated - process instance state is changed to "running".
Local Variables window is cleared.
The process continue its execution (resumes) until it reaches
the next activity.
The current position is cleared.
If/When the process instance reaches the next activity:
it's suspended by the target BPEL Engine; BPEL Engine
notifies the IDE that the step is completed.
The corresponding record in the "Process Instances"
is updated – its status is set to "suspended".
If the process instance for which the step was issued is not
a current process instance anymore (this could happen e.g. when
user switches to another process instance before the step is
completed), “Change
current process instance” use case is included for it.
“Change
current position” use case is included for the reached
activity's position.
UC5: Continue
Description:
Once a process instance gets suspended due to a breakpoint reach,
user may want to continue its execution. This use case resumes the
exeuction of the currently suspended process instance.
Actors:
Preconditions:
Scenario:
There is a debug session for the target BPEL Engine and it is
a current debug session.
User selects "Continue" in the main menu or on the
toolbar.
Corresponding record in the "Process Instances"
window is updated - process instance state is changed to "running".
Local Variables window is cleared.
IDE directs the target BPEL Engine to continue the process
instance execution.
The current position is cleared.
UC6: Stop debug
Description:
Users stops the debug when it doesn't need to perform debug
activities for the target BPEL Engine anymore.
Actors:
Preconditions:
Scenario:
User selects "Finish Debug
Session" in the main menu or on the toolbar or "Finish"
context menu for the debug session in "Sessions" window or
by pressing "Shift+F5".
The debug session is stopped;
corresponding record is removed from the Sessions window.
Process Instances and Local
Variables windows are cleared; current position annotations are
cleared.
UC7: Change current debug session
Description:
Current debug session can be changed by a user if he or she wants
to perform different debug activities with the BPEL Engine for which
a particular debug dession is created. Also, current debug session
can be changed automatically by the IDE in response to some BPEL
Engine notifications.
There could be only one current debug session.
Actors:
Preconditions:
Scenario:
One of the following events initiatiates the use case:
User double-clicks on some debugger session record in the
Sessions window or selects the record's “Make current”
context menu item.
Some other use case included this use case in response on
some BPEL Engine notification.
Given debug session becomes current; Sessions, Process
Instances and Local Variables windows are updated accordingly.
UC8: Change current process
instance
Description:
Current process instance can be set/changed by a user if he or
she wants to do different debug activities with that process
instance (e.g. to see its variables). Also, current process instance
can be changed automatically by the IDE in response to some BPEL
Engine notifications.
There could be only one current process instance.
Actors:
Preconditions:
Scenario:
One of the following events initiatiates the use case:
User double-clicks on some process instance record in the
Process Instances window or selects the record's “Make
current” context menu item.
Some other use case included this use case in response on
some BPEL Engine notification.
Given process instance becomes current; Process Instances and
Local Variables windows are updated accordingly; current position
annotations are updated to point to the current position of the
current process instance.
UC8: Change current position
Description:
Current position is a point where the current process instance is
suspended at. Current position can not be changed by a user, it's
changed automatically by the IDE in response to some BPEL Engine
notifications.
There could be only one current position.
Preconditions:
Scenario:
IDE tries to
locate the source BPEL-file for the process instance.
If source
file is found, it's opened in the editor (if not have opened yet),
the current position (where the breakpoint is reached) is marked by
the annotation and the caret is put on that position.
Otherwise,
user is notified that the source file can not be found.
Local
Variables window is populated with the variable values of the
process instance, available at the current position.
3. Specification
Debug Windows - Hierarchical
relationship
Except for the Console and Breakpoints windows, all Debug Windows
are hierarchically related view of debug context information.
Process
Instances window lists all the process instances that are running in
the target BPEL Engine. If the active session is not a BPEL Debugger
session, then this view is empty. User may select a particular
process instance to make it the current process instance.
Local
Variables window reflects the state of variables in the current
process instance in its current position.
Debug Console Window Details
This
is the conventional debug console window. It will be used to show
textual debug status messages.
Debug Session Window Details
TODO – will need new picture to reflect the new 1 Sesssion : 1
Runtime server cardinality
Debug
Breakpoints Window Details
Debug Process Instances Window
Details
Debug Local Variables Window
Details
Local Variables view now shows the structure of variables with XML
values (see picture).
Column “Type” may have one of the following values:
“Message”, “Element” and “XSD Simple”
- depending on the type of the BPEL Variable. It's blank for XML
elements and attributes inside a variable.
