Service Orchestration Functional Specification - Validation (Design
Guidance)
$Revision: 1.10 $
$Date: 2008/03/06 14:26:03 $
Note: This document contains
hidden
sections. You may show them
using the following links: Reader Notes: Hide
/ Show
| Author Notes: Hide / Show
Status:
Content not perfect, but acceptable
http://discotech.sfbay.sun.com/wiki/coke/Wiki?Orchestration+TPR3+BPEL+Design+Guide+Feature
1. Introduction
This functional specification will give details on the Validation
feature for the BPEL Project. The Validation
features' primary objective is to aid the developer while he is
designing business processes in BPEL. It will assist the user
via multiple sources such as the designer, source editor, navigator,
project tree, properties window, Tasks/Suggestions window, output
window. Some forms in which the validation can be shown are:
* Showing a list of errors in the BPEL or associated files.
* Providing visual annotations on the elements in the designer
and navigator.
This document contains reference to two terms:
Validator: This is a component which can analyse the
artifacts in the project (.bpel and the associated .wsdl and .xsd) and
generate a list of suggestions, errors, tips etc.,
Validation Info Consumer: This is a component which can utilize the
information provided by a Validator and display it in some
form. This will be referred to as Consumer.
This feature will be implemented so that multiple providers and
consumers can be plugged-in.
Modular Validition
The Design Guidance system will make use of a module validation
approach. This will allow multiple validators to be employed. Each
validator will be responsible for validating specfic aspects of the
BPEL process. This is really an implementation detail and end users
will not need to understand this architecture. From the user
perspective validation is a single atomic feature. They need not be
aware that it is implemented as a collection of validation routines.
However, users should be aware of the "range" of validation that will
be undertaken. That is to say, they should be aware of "what" is being
validated, even if they do not need to be aware of the "how" it is
being done.
Validators analyse the BPEL file and related artifacts and come up
with errors, warnings, suggestions etc., These validators
themselves can be either fast in executing (in which case we can get
validation results as the user designs) and some providers can be slow
(in which case the validation results will be available only
periodically / explicit user action). In all cases
the validation results from all validators will be made available to
consumers. Each consumer can only show the result that makes sense in
its context.
Each validator will be responsible for enforcing a specific set of
"rules" and will report violations of the rules in specific messages.
Where possible these rules and messages will be fully documented in
this or accompanying documents.
Here are the planned validators.
-
Not supported by BPEL Runtime Validator
This validator will check the BPEL process for usages of BPEL
language constructs which are valid according to the BPEL 2.0
specification, but are not yet supported by the Sun BPEL SE.
This document BPEL_SE_wsbpel_main.xml
is a version of the BPEL 2.0 xsd that has certain parts
of the schema commented out. The commented out sections are those parts
of the BPEL language which will not be supported by the Sun BPEL SE in
its first release. The commented out sections therefore represent the
"unsupported by runtime" language constructs.
-
BPLE Static Analysis Validator
This validator will check the BPEL process for violations of the
90 plus rules provided by the BPEL specification static analysis
document.
This document Static Analysis Requirement
is a modified copy of the static analysis rules provided
by the BPEL 2.0 specification. The document has been modified to
include the error messages that the BPEL Module wll generate for each
rule violation. This is necessary because the BPEL specification only
specifies the rules, it does not specify the rule violation messages.
This validator will simply invoke the standard XML Schema validation
utility which will then validate the BPEL process to make sure it is
accordance with the BPEL 2.0 xsd. The standard schema validation
reports errors only in terms of source code line numbers, therefore.
there will be an additional task required by our validator to parse the
response from schema validator and turn it into a collection of
ResultItems so that they can be mapped to the BPEL process elements.
This is wsbpel_2_0.xsd
the version of the BPEL 2.0 xsd that was available at the time the BPEL
Module was implemented. Since the BPEL 2.0 specifcation is still not
final, this xsd may change. This version is the version that the BPEL
Module will use to peform schema validation.
Messages - This functional specificaction cannot list all of the
messages that may be generated by the XML Schema validation utility.
That utility is not implemented by us. The BPEL Schema Validator will
simply invoke this utility and present the messages returned from this
utility to the users. These messages will be familiar to all users that
have run the Validate XML action in NetBeans or any other tool that
invokes the standard XML validation utility.
-
BPEL Broken Reference Validator
This validator will check the BPEL process for the presence of any
broken references. This validator will detect "simple" broken
references but will not detect potentially broken reference usage
internal to XPath expressions. "Simple" broken references, refers to
references which are formalized in the object model. For instance the
"input variable" property of an Invoke element will be a refernce to a
BPEL variable. That is a simple reference.
Rules Broken Reference Rules.
The Semantic Validator will add "extra validation" not covered by
other valdiators listed in this document.
This document SemanticValidationRules.html contains both the rules and the messages.
Fast versus Slow Validators
Validators can perform the task in two ways:
Fast (Only validates the current document ).
- This will be invoked as the user designs the
diagram.
- Used to show badges on the BPEL designer.
- This will be executed automatically. The user does not have
invoke it explicitly.
Slow (recursively validates all imported wsdl/schema
files).
- This will be invoked by a user action and can take a few seconds
to complete.
- Output will be shown in the Output window (similar to
results of java compilation).
- Hyperlinks from the output window can be used to open the source
editor for the file.
- This will validate all imported Schema and WSDL files.
Validation Information Consumers
Validation consumers accept the validation
results and display it to the user. The consumers could be:
- Output Window
- Designer
- Source editor annotations
- Navigator
- Project tree nodes
- Properties window and property editors
All validation information from all providers
will be available to all consumers. But it will be upto each
consumer to display only that validation information that makes sense
in
its view.
2. Technical details
Fast vs Slow validation Issues
For the fast Validator.
There will be a Controller which will overlook the entire
vdalidation information process. It will be coordinating activities
between the validators, the BPEL object model and the consumers. It
will work in the following way:
(a) The controller will have a reference
to the BPEL OM.
(b) The controller will receive events whenever the BPEL OM changes.
(c) Based on the type of event from the BPEL_OM,
the controller will invoke a method on the validator passing a
reference
to the BPEL_OM.
(d) The controller will notify all registed clients when this
validation information changes.
3.a Use Cases: Output Window
Results will be displayed here only on an explicit action such
as 'Validate' which will call the 'Slow' validator defined above. This
will display results like a compiler
does with line numbers, hyperlinks to the line in the source editor
etc., Since this will validate the BPEL and all imported WSDL and
Schema files, the user can expect error message from the WSDL and
Schema files also.
This will be the same validator that will be called when 'Compile'
action is performed.
3.b Use Cases: Designer
As the user works in the designer, navigator, modifies
properties in
the property sheet, the designer will be updating annotations on its
elements.
The annotation icon could be 'Error', 'Warning',
'Suggestion'.
The annotation will be updated every few seconds.
(Like the java editor which displays error information a few seconds
after the user stops typing).
3.c Use Cases: Navigator
The navigator node tree can be used to annotate validation
information by badging.
3.d Use Cases: Problems List
This will display results in a table similar to the ToDo
window in Netbeans. This list will be updated periodically
as the user designs the BPEL process.
| Message Type | Message
| File name
|
|---------------------------------------------------------------------------------------------
|
|
|
|
Each row in the table will act as a hyerlink to select the line
if the source editor is open or the element in the designer.
3.e Use Cases: Source editor
The error stripes and editor annotations in the margin can
be used to display validation information. Mouse over on the
margin
annotation can display the assoicated message.
3.f Use Cases: Project tree
The project tree can follow the Netbeans convention
of badging nodes in case there is any error associated with it.
We
should also think about badging the WSDL, Schema and Deployment
descriptor nodes going forward.
Test case message nodes also can be badged (example: If the test
message does not validate against the message schema.
3.g Use Cases: Properties
All the property editors can utilize this validation
information to appropriately badge incorrect properties.
3.h Use Cases: Suggestions framework
This framework assists the user in fixing the error itself
in addition to displaying it to the user. This will again show up
in the editor / designer with a 'bulb' icon and a right click will
present different actions available to fix the error/warning.
This
module is available on the NB5.0 Beta update center. I could use this
for Java sources and some options available were like 'Fix Imports'
etc.,
This might be a stretch goal.
4. Implementation schedule
In Netbeans Enterprise Pack Beta timeframe, the
following clients will be implemented.
- Output Window. (UC 3.a)
- Design Editor. (UC 3.b)
- Navigator (possibly?) (UC 3.c)
In Netbeans Enterprise Pack Beta timeframe, the following
validators will be implemented. These are descibed above.
- BPEL Runtime not supported Validator
- BPLE Static Analysis Validator
- BPEL Broken Reference Validator
5. User Interface Design
#
If there is a warning, suggestion or error message related to an
element on the diagram, an error toggle button shows up. The toggle
button
behaves as a real toggle button in Swing toolbar; it reacts on mouse
over (visual feedback) and
mouse press (besides visual feedbaci a cal out pop out). When it
is toggled on, validation call out pops
up; the visibility of the entire call
out is assured. The call out can be dismissed by toggling the
button off, or by bringing up a
different call out. It also disappears when a different element on the
diagram is selected.
The following mock up shows how the call out is attached to the
diagram, the actual visual appearance of the callout internals is
depicted on the next figure.
Figure - Validation call out mockup
Figure - Actual visual appearance of
the callout internals
Deliverables
The call out details are described in the following table. The
internals of the call out were delivered in a
zip file (
issue
#81468).
Element
|
Description
|
Call out toggle button
|
Inset: 3 px horizontally from
the right border of element or container,
vertically aligned with the top of element or container.
Visual appearance in 4 mouse interactions (same as in Swing toolbar):
|
Call out border
|
Opacity: 80 %
Background: RGB(255,255,255)
Border color: RGB(68,68,68)
Corner Radius: 4 px
Initial Size: 320 x 200 px
Resizable (as JFrame).
Call out pin starts at 1 px to the right from the border of the toggle
button, horizontally and in the center of the button vertically.
|
Call out - title line
|
Line color: RGB(68,68,68),
width: 1 px
Title line starting with the left axis of the call out border.
|
Call out - line between
individual errors
|
Line between errors:
RGB(155,155,155)
Left and right inset of the line is 4 px.
|
Insets inside Call out
|
5 px between error title and
error text (if there is any error title) and error text and line
5 px between the inner lines and call out border
5 px around the icons
4 px around scrollbar
|
Icons
#
|
Dimensions: 10 x 10 px
Insets of the error from the call out border: 8 px
Icon centered vertically with the line of the text.
In the title, the errors are left centered, the warnings are centered,
suggestions are right centered.
The following icons are used for errors found with live validation:
Error: 
Warning: 
Suggestion: 
For errors that are only found with explicit validation action the
icons are as follows:
Error: 
Warning: 
Suggestion: 
|
Call out text formatting
|
The text is in the standard font
size, family and face. If there is an error title, it is highlighted
with bold font face. |
