Service Orchestration Functional Specification - BPEL Refactoring

$Revision: 1.13 $
$Date: 2006/07/27 12:00:19 $

Note: This document contains hidden sections. You may show them using the following links: Reader Notes: Hide / Show  :  Author Notes: Hide / Show

1. Introduction

The BPEL Module will support BPEL source file refactoring. Wherever refactoring conventions are already in place within the NetBeans IDE, the BPEL Module will follow those conventions. The BPEL Module may also add some particular user interfaces to address particular issues that apply to BPEL refactoring and are not covered by existing NetBeans conventions or user interfaces.

This specification will mention several use cases. The current plan will be to implement solutions for some, but not all, of the use cases for the NetBeans Enterprise Pack 5.5 Release. The other use cases may be supported in subsequent releases.

Some definitions that are assumed by this document.

Upstream vs Downstream artifcacts.

An upstream artifact is something the BPLE file imports. For instance the BPEL file imports partner WSDL files and XSD files). WSDL and XSD are therefore upstream of the BPEL artifact. Conversely, the BPEL artifact is downstream of the WSDL and XSD artifacts. This is an important distinction to understand for refactoring. In refactoring scenarios downstream artifacts must respond to changes in upstream artifacts, but not vice versa. The BPEL file must react to changes that are initiated in WSDL and Schema artifcacts but not vice versa.

Explicit vs Implicit refactoing.

Note that there is a difference between “explicit” and “implicit” refactoring. Explicit refactoring refers the use case where the IDE provides specifict refactoring actions and specific refactoring user interfaces. In NetBeans this refers to the Find Usages action, and the various actions under the Refactor menu. These actions inovke a specific NetBeans refactoring user interface, which involves a specific NetBeans refactoring work flow. See Java refactoing for an example of this workflow. Explicit refactoring is usually required when the change must be propagated across multiple files. In such cases an explicit user interface provides the user with a preview of the changes and allows the user to decide whether to contine or abandon the operation.

Implicit refactoing refers to a refactoing “like” operation that does not involve the special NetBeans refactoing menu or refactoring user interface. The user may not even be aware that they are “refactoring”. They are just aware that they are renaming or deleting something. In implicit refactoing, the operation just works without any secondary user interface required. An example of this is renaming a variable. The variable is only used in the current file. Therefore, the IDE can implicitly change the name of the variable and all references to this variable in the current file. Implicit refactoring is usually perferred when the change does NOT need to be propagated across multiple files. Or in other words, implicit refactoring is preferred when the effect of a change is localized to the current file. In such cases, the user does not need and probably does not want to have the explicit refactoing user interface in this case. The user just wants the implicit refactoing operation to work quickly and transparantly.

See also XML Schema Analysis, Safe Rename, and Safe Delete

2. Use Cases and Scenarios

UC1a: User initiates an explicit refactoring operation “Find Usages” in an upstream artifact.

Scenario:

• User is working with WSDL file or Schema files

• WSDL and Schema editors have Refactor menus that include the actions Rename, Find Usages, and "Safe Delete"

• User invokes the Find Usages action for an element within their WSDL or XSD file.

• The standard NetBeans Find Usages refactoring UI is invoked. (see Java refactoring UI for example).

• The Find Usages window shows all usages of the selected item across the set of files which are in scope for this refactoring type. The list of files containing usages may include other files not just the current WSDL or XSD file - In fact, the list may include BPEL files that contain references to the element which is being refactored (e.g. User wants to change the name of a schema element or schema type which is being used by the BPEL file. Then the find usages list must include those places in the BPEL file which refer to the WSDL or XSD element. See Scope of Find Usages Action .

• 
  

Here is Find Usages window as invoked from Schema editor.

UC1b: User initiates an explicit refactoring operation “Rename” in an upstream artifact.

Scenario:

• User is working with WSDL file or Schema files

• WSDL and Schema editors have Refactor menus that include the actions Rename, Find Usages, and "Safe Delete"

• User invokes the Refactor Rename action for an element within their WSDL or XSD file.

• The standard NetBeans “Rename Field dialog is presented to user. This dialog includes a “Preview All Changes?” check box. This check box is selected by default..

• If user chooses to preview changes, then then the standard NetBeans Preview Changes refactoring UI is invoked. (see Java refactoring UI for example).

• The Preview Changes window shows all usages and allows user to selectively choose where to apply changes. See Scope of Find Usages Action.

• If the user chooses to apply the changes, then we must change the references in the BPEL file to match the change.

• The UI is blocked by a modal progress dialog while the refactoring is running

• After the refactoring has completed, if the Preview was shown, it is automatically closed.

• After the refactoring the files are automatically saved.

Undo/Redo behaviour [ see note ]

1. To undo the rename, the user selects  "Undo Rename" from the schema component node's popup menu.  

2. The Undo menu item is enabled after a rename refactoring has completed.

3. Undo is disabled if any member of the refactoring set is modified after the refactoring

4. After undoing the rename, the user can  redo the rename from the same popup menu

5. The undo depth is one, i.e., only the last refactoring can be undone

Here is intial Refactor Rename dialog

Here is Preview Changes window as invoked by Java refactoring rename action.

UC1c: User initiates an explicit refactoring operation “Safely Delete” in an upstream artifact.

Scenario:

• User is working with WSDL file or Schema files

• WSDL and Schema editors have Refactor menus that include the actions Rename, Find Usages, and "Safe Delete"

• User invokes the Refactor Safely Delete action for an element within their WSDL or XSD file.

• The standard NetBeans “Safe Delete” dialog is presented to user. choose to bypass the Preview.

• If user chooses to Preview the changes, then a Find Usages checks is run.

• If usages are found, a warning dialog will be shown. (The dialog could also contain Errors).

• If only warnings are issued, the user can

1. Continue to the Preview

   • If usages had been found, and the user has chosen to proceed to the Preview, the Preview will display the message "Delete component but keep the 5 usages of it. [1 occurrence]".

   • (The Java delete preview has this message: "Delete classes and keep references to them, if any. [1 occurrence]" )

2. or, if bypassing the Preview, proceed directly to the refactoring,

3. or press the "Show Usages" button

   • The Show Usages results is identical to the TPR3 Show Usages, except that there is a button "Rerun Safe Delete".

4. or cancel the deleteThe refactoring will run automatically if the user has unchecked "Preview All Changes" when first invoking the delete

• The UI is blocked by a modal progress dialog while the refactoring is running

• After the refactoring has completed, if the Preview was shown, it is automatically closed.

• After the refactoring the files are automatically saved.

• Undo/Redo behaviour is similar to the undo redo for rename.

UC2: User initiates an explicit refactoring operation on an element within the BPEL file.

Scenario:

This is the same as UC1a, UC1b and UC1c except that in this use case the user is working with a BPEL artifact and selecting a BPEL element as the refactoring origination point.

• User is working with BPEL file.

• BPEL elements (in Diagram, Navigator and maybe source can have “Refactoring” context menu. With Rename, Find Usages, and perhaps "Safe Delete" actions.

• User selects an element, like a variable in Navigator and invokes one of these actions.

• The standard NetBeans refactoring UI is invoked, with a Preview Changes option.

• The Preview Changes window shows all usages and allows user to choose to apply changes.

• The list of files containing usages may include other files not just the current BPEL file - HOWEVER, I think that in the case of BPEL elements there will not be any other files affected by BPEL element changes because there are now user editable files which are downstream of the BPEL artifcact.

• 
  

UC3: User initiates an implicit refactoring operation “Rename” on an element within the BPEL file..

Scenario:

• User is working with BPEL file.

• User selects an element, like a variable in either Navigator or Diagram and invokes the inplace rename editor.

• If the new name is valid, then the rename is applied and implicit refactoing takes place without any special UI or acknowledgment. All references in the current file to the renamed element are updated transparantly.

UC4: User initiates an implicit refactoring operation “Delete” on an element within the BPEL file..

Scenario:

• User is working with BPEL file

• User selects an element, like a variable in either Navigator or Diagram and invokes the Delete action.

• The object is deleted.

• References to the deleted object are now invalid and should be indicated as such. The validation system should detect these invalid references, badge elements and provide validation details to inform user that the references are broken.

• User must individually correct all broken references.

Indicating and repairing broken references

Both use cases UC1c and UC4 raise the possibility, even likelihood that users will create a situation where they delete something and some or all references to the deleted item remain. These are called broken references. Similarly, users can create this situation by simply editing the source directly at any time. Therefore, the IDE must provide a consistent interaction to indicate broken references and allow user to repair them. This should be covered in the Validation (Design Guidance specification). Effectively, after refactoring has occurred, the automatic validation system should be triggered and this will detect and indicated any such broken references that need to be repaired.

3. Specification

Scope of Find Usages Action

The Find Usages action on the nodes for global component in the Schema editor, WSDL editor and BPEL editor will use refactoring engines provided by the WSDL, BPEL, and Schema modules to find usages of the component in the current project. The file nodes in the visualization will have different icons, node shapes and/or node colors to differentiate them.

Note on Undo/Redo:

If feasible, the following "smart" Undo/Redo behaviour will be implemented:

1. To undo the refactoring, the user can do one of the following:

   1. Select "Undo" from the schema component node's popup menu.

   2. Select Edit | Undo from the IDE main menu when a multiview in the refactoring set is active

   3. Press Ctrl+Z  when a multiview in the refactoring set is active

2. The menu items and  accelerator are enabled after a refactoring is done, and remain enabled even if a model in the refactoring set is subsequently modified.

3. When the user selects Undo, a warning message will be issued if any of the models in the refactoring set have been modified after the refactoring.  The user can choose to 

   1. undo only the model for the currently active multiview

   2. cancel the undo request

4. After undoing the rename, the user can  redo the refactoring from the popup menu, the main Edit menu, or with Ctrl+Y

5. There is no limit to the number of undos that can be accumulated

Implementation Schedule

UC1a, UC1b and UC1c should be implemented for Enterprise Pack 5.5 Beta.

Detailed description below.

UC2 will not be implemented in Coke.

It is not clear that UC2 is required if we have a solution for UC3. The “Find Usages” part of UC2 is desirable and maybe the “Safely Delete”. We can consider adding these after the Enterprise Pack 5.5 release.

UC3 already implemented in Enterprise Pack 5.5 TPR3 -with one outstanding RFE descibed here.

There is only one edge case of the implicit rename which is non-functional. This is the case where the XPath expressions in the the BPEL file are not updated to reflect the renaming. For instance, in TPR3, if you have the following situation. The usages of the variable name are underlined for emphasis.

  <variables>
    <variable name="ItineraryIn" messageType="tres:ItineraryIn"/>
 ...
  </variables>
  <sequence name="Main">
    <receive name="ReceiveItinerary" partnerLink="Travel" 
     portType="tres:TravelReservationPortType" 
     operation="buildItinerary" 
     createInstance="yes" 
     variable="ItineraryIn">
    </receive>
    <assign name="CopyItineraryIn">
      <copy>
        <from variable="ItineraryIn" part="itinerary"/>
        <to variable="ItineraryOut" part="itinerary"/>
      </copy>

</assign>

 <if name="HasVehicle">    
   <condition>
    not($ItineraryIn.itinerary/ItineraryInfo/ReservationItems/Item/Vehicle)
 </condition>

In TPR3, if you use the implicit refactoring to rename the variable from “ ItineraryIn” to “Foo”, you will get the following result:

  <variables>
    <variable name="Foo" messageType="tres:ItineraryIn"/>
 ...
  </variables>
  <sequence name="Main">
    <receive name="ReceiveItinerary" partnerLink="Travel" 
     portType="tres:TravelReservationPortType" 
     operation="buildItinerary" 
     createInstance="yes" 
     variable="Foo">
    </receive>
    <assign name="CopyItineraryIn">
      <copy>
        <from variable="Foo" part="itinerary"/>
        <to variable="ItineraryOut" part="itinerary"/>
      </copy>

</assign>

 <if name="HasVehicle">    
   <condition>
    not($ItineraryIn.itinerary/ItineraryInfo/ReservationItems/Item/Vehicle)
 </condition>

Note that the change was correctly applied to several usages, but the XPath expression in the if condition was not adjusted. The correct thing would be for the XPath expression to ALSO be adjused.

UC4: TODO – what is status of this in TPR3?

Context Menus

Each element in the Diagram and the Navigator should have a variation on the following context menu. Some of the items may be missing for some elements. For instance not all elements will have an Edit or Add action. However, this is provided for illustration of the relative position of the the Refractoring menu items.

Edit   ...   (if appropriate)
Add        > (if appropriate)
Rename (invokes BPEL UC3)
Delete (invokes BPEL UC4)
---
Go To Source
---
Find Usages  (UC1a - Only for WSDL and Schema elements in Coke)
Refactor  > Rename  (UC1b - Only for WSDL and Schema elements in Coke)
            Safely Delete (UC1c - Only for WSDL and Schema elements in Coke)
            ---
            Undo
            Redo

Details of UC1a “User initiates an explicit refactor rename in an upstream artifact.”

Refactoing rules. These are the rules that must be implemented by BPEL refactoing engine(s). The rules describe that when a change is made to an upstream source, the corresponding change must be made in the downstream BPEL. The BPEL refactoing engine implementation is only responsible for implementing the changes to the BPEL file itself. The changes to the upstream artifact will be implementated by the upstream artifact's own refactoring engines. See WSDL and XSD refactoring details.

Refactoring L&F – Usages Window

The primary view in the refactoring UI is the “Usages” window. This window is common to refactoring of any XML artifcact (WSDL, XML Schema, or BPEL). The window will be divided into two panes. The left pane will contain a specialized version of the standard NetBeans Usages tree view. It is “standard” to the extent that it complies with the L&F conventions of the other Refactoring Usages view (e.g. Java Refactoring) in NetBeans. It is specialized in that the sub nodes of the usages tree are XML specific. And they are specific for WSDL , XML Schema and BPEL. This document will only describe the BPEL specific nature of this view.

In the right panel of the Usages window the will be a cloud view. The cloud view is a carry over from the XML Schema editor. It shows the usages relationships in a UML like fashion. The “cloud” refers to the variously colored cloud that enclose the entites for each particular file.

Usages Tree Structure

The structure of the Usages tree goes like this:

[ ] Usages of <queried object name> [<n> occurences]

-- [ ] <project.name>

-- [ ] <folder structure>

-- [ ] <bpel filename>

-- [ ] <usage context>

-- [ ] <usage object>

-- [ ] <usage details>

The terms “usage context” , “usage object” and “usage details” are new terms introduced in this specification. They are not standard NetBeans terms and it is not necessary for user documentation to use these terms. However, user documentation may find these terms as good as anything else.

Usage object

Usage object may be one of the following:

• basic activity referring to the queried object with one of its properties

• if condition or else if condition

• onAlarm or onEvent branch of a pick

• event handler of a scope

• variable

• correlation set

Usage context

#
Usage context is a "fully qualified name" of the structured activity enclosing the usage object, whereas the fully qualified name contains the names of all the structured activities on the path from the usage object to the top level activity excluding sequences. The format of the name goes like this:

<process.name> / <scope.name> / <otherStructuredActivity.name> ...

If the usage object is a condition of if or elseIf then the usage context also includes the enclosing if activity. The same applies to pick.

If the usage object is a loop activity (via one of its properties), the usage context does not contain this loop structured activity. However, if the usage object is an activity nested in a loop activity then the usage context contains the loop activity as well.

TODO - refine how this should work for handlers

Usage details

Usage details are relevent to assign activity, correlation sets, and other usage contexts who's Navigator counterparts have richer internal substructure. For example, in the Navigator, the Assign element has CopyRule children. Therefore, in the Usages view, the Assign is a usage context but its CopyRules will be Usage Details.

If one or more copy rules of an assign activity are referring to the queried object, the usage object is the assign activity. However in this case, the usage object is not a leaf node of the FU tree (in contrast to other cases), but it would include assign activities that make use of the queried object as its children.

Usages Tree View Selection and Activation (DBL-Click)

Usages Tree View nodes are either containers or leaf nodes.

Selection (single click) on any node should result in synchronized selection of peer node in the Usage cloud view. Focus should remain in Usages tree view.

Note – it was originally thought that the selection (single click) should result in selection of peer node in Navigator and Diagram but there is some concern that this might be too busy. Also this is not the case with Java refactoring. However, for implementation reasons, we may get this synchronized selection behaviour for free if we can solve a NetBeans bug related to Navigator visibility.

Double Click activation of a container node should result in the collapse or expansion of the container node. Focus should remain in Usages tree view.

Double click activation of a leaf node should result in the display and selection of the peer node in the BPEL Design view. Also focus should shift to the Design view window.

Note – it was originally thought that Double Click of a container node would also display and select the peer node in the BPEL Design view but after observing behaviour in Java refactoing I think that this should not be done, in order to remain consistent with NetBeans style.

Refactoring Rules

WSDL initiated refactoring

Import : namespace

Import : location

Message : name

Variable : messageType
Catch : faultMessageType
OnEvent : messageType

Message : name

SPEC Adjustment

Mssage : name is used only in defining the variables. It is not used in any
XPath cases that we are aware of.

So there is no work for this case.

Message -> Part  : name

Copy From : part 
Copy To : part 

Message -> Part  : name

** These adjustments are XPath adjustments and require special processing.
Parent Element : XPath Expression 
Wait : for
Wait :  until
OnAlarm Pick : for
OnAlarm Pick :  until
OnAlarm Event : for
OnAlarm Event :  until
OnAlarm Event :  repeatEvery
If : condition
Else If : condition
While : condition
RepeatUntil : condition
ForEach : startCounterValue
ForEach : finalCounterValue
ForEach : completionCondition
Variable : fromSpec [TODO Clarify this one]
Copy From : ? [XPath Expression]
Copy To : ?  [XPath Expression]

Fault : name

Catch : faultName
Reply : faultName
Throw : faultName

Fault : name

TODO – does the faultName affect any XPath usages?

TODO
What affects the PropertyAlias Query?

PortType : name

Receive : portType 
Reply : portType 
Invoke : portType
OnEvent : portType 
OnMessage : portType 

Role : portType

Operation : name

Receive : operation
Reply : operation
Invoke : operation
OnEvent : operation
OnMessage : operation

Receive : messageExchange
Reply : messageExchange
OnEvent : messageExchange
OnMessage : messageExchange

copyFrom : endpointReference

fromPart : toVariable

fromPart : part

toPart: fromVariable

toPart : part

XML Schema initiated refactoring (may come from XSD or schema embedded in WSDL)

Import : namespace

Import : location

complexType : name

Variable : type

complexType : name

** These adjustments are XPath adjustments and require special processing.
Parent Element : XPath Expression 
Wait : for
Wait :  until
OnAlarm Pick : for
OnAlarm Pick :  until
OnAlarm Event : for
OnAlarm Event :  until
OnAlarm Event :  repeatEvery
If : condition
Else If : condition
While : condition
RepeatUntil : condition
ForEach : startCounterValue
ForEach : finalCounterValue
ForEach : completionCondition
Variable : fromSpec [TODO Clarify this one]
Copy From : ? [XPath Expression]
Copy To : ?  [XPath Expression]

simpleType : name

Variable : type

simpleType : name

** These adjustments are XPath adjustments and require special processing.
Parent Element : XPath Expression 
Wait : for
Wait :  until
OnAlarm Pick : for
OnAlarm Pick :  until
OnAlarm Event : for
OnAlarm Event :  until
OnAlarm Event :  repeatEvery
If : condition
Else If : condition
While : condition
RepeatUntil : condition
ForEach : startCounterValue
ForEach : finalCounterValue
ForEach : completionCondition
Variable : fromSpec [TODO Clarify this one]
Copy From : ? [XPath Expression]
Copy To : ?  [XPath Expression]

element : name

Variable : element
Catch : faultElement

element : name

** These adjustments are XPath adjustments and require special processing.
Parent Element : XPath Expression 
Wait : for
Wait :  until
OnAlarm Pick : for
OnAlarm Pick :  until
OnAlarm Event : for
OnAlarm Event :  until
OnAlarm Event :  repeatEvery
If : condition
Else If : condition
While : condition
RepeatUntil : condition
ForEach : startCounterValue
ForEach : finalCounterValue
ForEach : completionCondition
Variable : fromSpec [TODO Clarify this one]
Copy From : ? [XPath Expression]
Copy To : ?  [XPath Expression]

attribute : name

** These adjustments are XPath adjustments and require special processing.
Parent Element : XPath Expression 
Wait : for
Wait :  until
OnAlarm Pick : for
OnAlarm Pick :  until
OnAlarm Event : for
OnAlarm Event :  until
OnAlarm Event :  repeatEvery
If : condition
Else If : condition
While : condition
RepeatUntil : condition
ForEach : startCounterValue
ForEach : finalCounterValue
ForEach : completionCondition
Variable : fromSpec [TODO Clarify this one]
Copy From : ? [XPath Expression]
Copy To : ?  [XPath Expression]

BPEL Extensions to WSDL initiated refactoring

These are special BPEL extensions (defined by BPEL specification) that appear in WSDL files.

We will have to handle both aspects of this refactoring – the WSDL changes AND the BPEL changes.

PartnerLinkType : name

PartnerLink : partnerLinkType

Role : name

PartnerLink : myRole 
PartnerLink : partnerRole

Property : name

Copy From : property 
Copy To : property  
CorrelationSet : properties

Role : portType

Receive : portType  
Reply : portType 
Invoke : portType
OnEvent : portType 
OnMessage : portType
*The port type will probably be blank in most cases since it is already specified
 in the PartnerLinkType -> Role, and is optional in the Web Service activities.

Implicit BPEL Refactoing – local

These are special BPEL extensions (defined by BPEL specification) that appear in WSDL files.

We will have to handle both aspects of this refactoring – the WSDL changes AND the BPEL changes.

 Variable : name

** These adjustments are straight adjustments.
Receive : variable 
Reply : variable 
Invoke : inputVariable
Invoke : outputVariable 

OnMessage : variable 

Throw : faultVariable
Validate : variables
Copy From : variable
Copy To : variable



Note - OnEvent : Variable and Catch : Fault Variable are not references. 
Therefore they are not affected by variable defintiion modification made elsewhere.

 Variable : name

** These adjustments are XPath adjustments and require special processing.
Parent Element : XPath Expression 
Wait : for
Wait :  until
OnAlarm Pick : for
OnAlarm Pick :  until
OnAlarm Event : for
OnAlarm Event :  until
OnAlarm Event :  repeatEvery
If : condition
Else If : condition
While : condition
RepeatUntil : condition
ForEach : startCounterValue
ForEach : finalCounterValue
ForEach : completionCondition
Variable : fromSpec [TODO Clarify this one]
Copy From : ? [XPath Expression]
Copy To : ?  [XPath Expression]

 CorrelationSet : name

Correlation : set
TODO – verify that this is correct mapping.

 ParnerLink : name

Receive : partnerLink 
Reply : partnerLink 
Invoke : partnerLink 
OnEvent : partnerLink 
OnMessage : partnerLink 
Copy From : partnerLink 
Copy To : partnerLink  

 Source : LinkName

 Target : LinkName

Usage Node Details

This section describes the structure of the usage nodes (i.e. the nodes that will appear in the usages window)

Usage Nodes: for BPEL usages of upstream objects

These are the nodes that might appear under the BPEL file node in the usages window to indicate that a BPEL element is using the upstream refactored object.

BPEL Elements that contain refactored XPATH data

These are the nodes that might appear under the BPEL file node in the usages window to indicate that a BPEL element is using the upstream refactored object. These are particular in that they contain refactored XPath data. And their nodes and labels should be consistent

WSDL BPEL Extensions Elements

These are the nodes that might appear under the WSDL file node in the usages window to indicate that a BPEL Extension for WSDL element is using the upstream refactored object.