Service Orchestration Functional Specification - Validation (Design Guidance)

$Revision: 1.2 $
$Date: 2009/11/02 14:12:36 $

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

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.


  • BPEL XML Valdiator

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.

  • BPEL Semantic Validator

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 Schema Valdiator
    • BPEL Broken Reference Validator
    • BPEL Semantic 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


    The call out details are described in the following table. The internals of the call out were delivered in a zip file (issue #81468).
    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
    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:


    For errors that are only found with explicit validation action the icons are as follows:

    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.

    Project Features

    About this Project

    SOA was started in November 2009, is owned by slunegov, and has 99 members.
    By use of this website, you agree to the NetBeans Policies and Terms of Use (revision 20160708.bf2ac18). © 2014, Oracle Corporation and/or its affiliates. Sponsored by Oracle logo
    Please Confirm