BPEL Editor: New Partner Link Editor & Drag'n'Drop of Web Service Nodes (WSDL and NB Web Service nodes)

$Revision: 1.5 $
$Date: 2006/09/17 17:33:55 $

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

This document describes several new use cases that were raised by the useability testing. As a result of these use cases the PartnerLink editor has been modified (see below).

Difference between a PartnerLink and a PartnerLinkType.

The PartnerLink is a BPEL element. It is defined in the BPEL process file. It makes reference to a PartnerLinkType. The PartnerLink is therefore dependent on the PartnerLinkType definition. The PartnerLink is downstream from the PartnerLinkType definition.

The PartnerLinkType is a BPEL extension for WSDL. It is defined in a WSDL file. It has no knowledge of PartnerLink, as it is upstream from the PartnerLink definitions.

Ways to create a Partner Link

The IDE must support several ways to create Partner Links. Some of the use cases below can be initiated from several directions. All of these initiating actions will cause the Partner Link editor to appear so that the user can complete or acknowledge the configuration of the new partner link. In some cases, depending on the initiating action, more than a partner link is created. Also, depending on the initiating action, the Partner Link editor may or may not be pre-populated with values. Those additional details are described in the specific use cases below.

Those directions are as follows:

• DnD the Partner Link element from the BPEL palette onto a BPEL diagram

• DnD a WSDL file node from the BPEL project explorer onto the BPEL diagram in the same project.

• DnD a NetBeans Web Service node from a NetBeans EJB project explorer onto a BPEL diagram in a BPEL project.

• DnD a WSDL file node from the an arbitrary NetBeans project explorer onto a BPEL diagram in a BPEL project.

Use Cases

• User wants to define a Partner Link based on an already defined Partner Link Type

• User wants to create a Partner Link but the partner WSDL file does not yet contain any Partner Link Type definitions

• User wants to create a Partner Link but the partner WSDL file does not yet contain the desired Partner Link Type definition

• User wants to create a Partner Link that refers to a Web Service defined in NB EJB project

• User wants to create a Partner Link that refers to a Web Service defined in another arbitrary NB project

• User wants to create a Partner Link that refers to a Web Service defined by another NB BPEL project

Use Case: User wants to define a Partner Link based on an already defined Partner Link Type

User tries to create a Partner Link (this can be done several different ways) . The PartnerLink editor is invoked. In the PartnerLink editor the user selects the partner WSDL. The partner wsdl contains one or more partner link type definitions. The user wishes to define a partner link that refers to one of the already defined partner link types.

Scenario

• User invokes PartnerLink editor (any number of ways)

• The Partner Link name field is pre-populated with a default name based on a simple algorithm to guarantee PartnerLink name uniqueness (i.e. PartnerLink<n> where <n> is a numeric increment. The user may change the name to any valid and unique value.

• User specifies partner WSDL in PartnerLink editor (or in case of DnD , the partner WSDL may already be pre-selected). The user may change the selection of partner WSDL at any time. When they do so, the other fields (excepting the PartnerLink name field) in the editor will adjust because they are derivative of the WSDL file.

• Assuming that the selected WSDL file contains one or more PartnerLinkType definitions then the drop down list of PartnerLinkType definitions is pre-populated with these partner link type names, and the first partner link type in the list is selected by default. The user may change the selection to any of the available partner link types.

• The My Role and Partner Role non-editable text fields are automatically populated based on the choice of PartnerLinkType. Some PartnerLinkTypes have only one role defined. That is normal, that is not a problem. The user may reverse the role assignment values by selecting the “Swap Roles” button.

• The user may commit the configuration of the PartnerLink by selecting the OK button. At this moment the new Partner Link is added to the BPEL process.

Open questions

There was some internal debate on whether the editor should foreground the idea of “Role” or subsume this concept and foreground the PortType instead. Ideally, the UI would be able to show the user what a given Role means, in terms of what PortType and hence what operations that Role implies.

Should we keep the WSDL File drop down list or would it be better to have a drop down list of Namespaces? The concern is transparency and design center for users. This becomes more of an issue when we start using wrapper WSDLs, and we need to decide how to allow users to interact with these wrapper wsdls in general. Should they be aware of the presence of the wrapper wsdl (as a file) or should they be unaware of it and only shown Namespaces? This is a useability question.

Use Case: User wants to create a Partner Link but the partner WSDL file does not yet contain any Partner Link Type definitons

User tries to create a Partner Link (this can be done several different ways) . The PartnerLink editor is invoked. In the PartnerLink editor the user selects the partner WSDL. But the partner WSDL file does not contain any PartnerLinkType definitions. The user does not want to cancel the operation. The user wants to be able to add the PartnerLinktype to the partner WSDL at this moment from within the PartnerLink editor.

Scenario

• User invokes PartnerLink editor (any number of ways)

  • The name of the PartnerLink is automatically generated by default to be unique, starting at “PartnerLink1” and incrementing upward. User can adjust this name.

• User specifies partner WSDL in PartnerLink editor (or in case of DnD , the partner WSDL may already be pre-selected)

• Partner wsdl does not have any PartnerLinkType definitions therefore the “Use Existing Partner Link Type” option is not useful.

  • Note: the editor should preselect this option only if there is 1 or more PartnerLinkTypes already defined.

• User chooses “Use a Newly Created Partner Link Type” option

  • Note: The editor should preselect this option if there are 0 PartnerLinkTypes already defined.

• User specifies a new PartnerLinkType name

  • Note: The PartnerLinkType name should be pre-populated with a default name based on the first PortType in the WSDL. (i.e. <FirstPortType>LinkType )

• User may check/uncheck the “Process will implement (My Role)” and/or the “Partner service will implement (Partner Role)” check boxes. User must check at least one. User may check both

  • Note: The “Partner service will implement (Partner Role)” is chekced, and its text field is prepopulated with a name based on the first PortType in the partner WSDL. This is based on assumption that in most cases the user is defining a PartnerLin that the partner already implements.

  • Note: The “Process will implement (My Role)” is left unchecked and blank by default. This is based on weak assumption that most times the PartnerLinkType will be simple. See Open Questions/Issues below.

• For each checked role, the user must specify a Role Name and Port Type, in order to complete the definition of the PartnerLinkType.

  • In case where the Role is prepopulated, the prepopulated Role name is based on simply applying the “Role” as a suffix to the portType. (i.e. <PortType>Role )

  • User must select the appropriate PortType from the drop down list of available PortTypes.

• User selects OK.

One effect of this scenario is that a new PartnerLinkType is added to the the Partner WSDL file. For example:

        <plnk:partnerLinkType name="VehicleReservationPartnerLinkType">
                <plnk:role name="VehicleReservationServiceRole"
                    portType="tns:VehicleReservationPortType" >
                </plnk:role>
                <plnk:role name="VehicleReservationCallbackServiceRole"
                    portType="tns:VehicleReservationCallbackPortType" >
                </plnk:role>            
        </plnk:partnerLinkType> 

Another effect of this scenario is that the PartnerLink is added to the BPEL process. For example

<partnerLink name="Vehicle" partnerLinkType="vres:VehicleReservationPartnerLinkType" partnerRole="VehicleReservationServiceRole" myRole="VehicleReservationCallbackServiceRole"/>

Open questions/issues

Should we prepopulate the “Process will implement (My Role)” with the seond portType or should we leave this Role blank by default. The only hint we might get from the Partner wsdl would be based on Service defintions. If the partner wsdl defined a service which did include a portType then we could infer that it would be the PartnerRole port. If it defined a portType which was not included in any Service definiton then we might infer that this should be the My Role. However, these assumptions would be entirely reversed for the case where the WSDL is meant to be the WSDL for the BPEL process itself. We really do not know at the time of creation what user intent might be, so either inference would be right some of the time and wrong some of the time.

Should we do more when it comes to prefilling the new PartnerLinkType and PartnerLink fields in the editor? For instance there was this proposal but it has not been implemented..

First of all, i will check if name ends with "Service" and add "Service"
to the name, if not so.
PartnerLinkType will be named as name + "Type"
Role will be named as name + "Provider"
PartnerLink will be named as name + "Link"

Should the Editor be modified further to help user understand what each PortType really means in terms of operatons? Right now, we only show the names of the PortTypes, but user may actually not be in a good position to decide based on porttype name alone. They might need to refer to the WSDL in order to recall which portType is the one they care about. However, if we showed them enough information in the editor (i.e.some read only summation of the porttype they would not have to refer to the WSDL.

The list of available PortTypes should probably be based on recursive descent into all imported WSDLs for a given WSDL. Specifically, if the user selects a “wrapper” WSDL, and wishes the PartnerLinkType to be added to the wrapper WSDL, they will need to choose a porttype that is defined in the wsdl imported by the wrapper wsdl. That is the reason for having wrapper wsdls. But today our PortType list only shows those porttypes immediately defined in the specific WSDL. It does not recursively disover all recursively imported porttypes , as it really should.

Use Case: User wants to create a Partner Link but the partner WSDL file does not yet contain the desired Partner Link Type definition

This is just a variation on the use case described above “User wants to create a Partner Link but the partner WSDL file does not yet contain any PartnerLinkType definitons”. In this use case, the Partner WSDL may already have 1 or more PartnerLinkType definitions, but , for whatever reason, the user does not want to use any of them. For,whatever reason, the user would prefer to define a new PartnerLinkType and use that as the basis of the PartnerLink.

Scenario

Scenario is the same as “User wants to create a Partner Link but the partner WSDL file does not yet contain any PartnerLinkType definitons”.

Use Case: User wants to create a Partner Link that refers to a Web Service defined in NB EJB project

User wants to create a new PartnerLink that refers to a web service implemented as an EJB in a NetBeans EJB project. The user wishes to do this in the least number of steps. They do not want to have to manually do the following logical operations

• Retrieve the partner WSDL using the File New > XML > Retrieve external WSDL

• Import retrieved WSDL into BPEL process

• Add PartnerLink.

User wishes to do all three of those steps in one gesture.

Scenario

• User opens EJB project.

• User expands the EJB > Web Services folder

• User selects a web service node.

• User drag'n'Drop the web service node onto the BPEL diagram

Upon drop the following occurs:

If the IDE can retrieve the WSDL file for the dropped service then that file (and any files required for closure will be automatically “retrieved” and copied into a directory within the BPEL project.

BPEL Module
---Process Files
-------Partners
----------<ServiceName>
-------------------<ServiceName>.wsdl
------------------- *.wsdl / *.xsd (required by retreival closure)

Note that the retrieved files are placed in a flat sturcture under the leaf directory <ServiceName>. That is because the retrieved files are fetched from the Application Server where they have been stored in a very unfriendly directory structure. We did not want to replicate that incrredibly unfriendly directory structure in the users development environment, so we are using a new retrieval API in order to put all of the files into a single directory. Any internally complex imports are managed by the catalog.xml , a hidden file.

This scenario now intersects with either the “User wants to create a Partner Link but the partner WSDL file does not yet contain any PartnerLinkType definitons” or “User wants to define a PartnerLink based on an already defined PartnerLinkType” - depending on whether dragged service has zero or more already defined PartnerLinkTypes.

If the IDE cannot retrieve the WSDL file for the dropped service, then the user will be presented with an error dialog indicating that the retrieval was unsuccessful. This will abort the PartnerLink addition and the user must correct the root cause of the failed retrieval and then try the drag'n'Drop again. The retrieval will fail (by design) if the partner web service is not deployed to the Sun Java Application Server, and the Java Application Server is running. If either of those condtions are not met, then the WSDL retrieval will fail. User will be informed of the failure via an information dialog.

The Unable to retrieve WSDL dialog.

Open questions/issues

Should the failure be in an Error dialog insstead of an inforamtion dialog?

In case of DnD of Partner wsdls/Web service nodes, it would be better for the new PartnerLinkType to be written to a new wrapper WSDL file instead of the original WSDL. This would allow user to re-retrieve the original WSDL without fear of overwriting or losing PartnerLinkTypes which were added as result of this scenario. We should implement the Wrapper wsdl solution as soon as possible. However, once we implement a wrapper WSDL story, we have to also decide which WSDL file will be design center in PartnerLink editor. Will it be the original WSDL or will it be the wrapper WSDL? There are issues for both approaches. If the design center is the wrapper WSDL then the issue is that the PartnerLink editor needs to present port types and operation for the imported wsdl (i.e the wsdl imported by the wrapper – in order to facilitate the creation of the PartnerLinkType. If the design center is the “original” WSDL then there needs to be some way (either implicit or explicit) to push the changes into the wrapper WSDL (and also import the wrapper WSDL file into the BPEL process. At this time it is not clear which “center” is the best from a useability perspective.

Use Case: User wants to create a Partner Link that refers to a Web Service defined in another arbitrary NB project

User wants to create a new PartnerLink that refers to a web service definition (WSDL file) already present in another arbitrary NetBeans. The user wishes to do this in the least number of steps. They do not want to have to manually do the following.

• Retrieve the partner WSDL using the File New > XML > Retrieve external WSDL

• Import retrieved WSDL into BPEL process

• Add PartnerLink.

User wishes to do all three of those steps in one gesture.

Scenario

• User opens arbitrary NetBeans project.

• User expands Project explorer until he finds the WSDL file for the web service that he wishes to use as a partner.

• User selects the WSDL file node.

• User drag'n'Drop the WSDL file node onto the BPEL diagram

Upon drop the following occurs:

If the IDE can retrieve the WSDL file for the dropped service then that file (and any files required for closure will be automatically “retrieved” and copied into a directory within the BPEL project.

BPEL Module
---Process Files
-------Partners
----------<ServiceName>
-------------------<ServiceName>.wsdl
------------------- *.wsdl / *.xsd (required by retreival closure)

This scenario now intersects with either the “User wants to create a Partner Link but the partner WSDL file does not yet contain any PartnerLinkType definitons” or “User wants to define a PartnerLink based on an already defined PartnerLinkType” - depending on whether dragged service has zero or more already defined PartnerLinkTypes.

This retrieval should not fail for any reason by design. The retrieval in this scenario is implemented differently than the retrieval described for “User wants to create a Partner Link that refers to a Web Service defined in NB EJB project”. That retrieval required that the dropped service be deployed to a running Application Server. In this scenario we are retrieving the WSDL directly from the other project's file system. So this should succeed.

Open questions/issues

Since we are retrieving the WSDL file(s) and XSD files from another NB project I have some concerns about how the retrieved files are referenced in the catalog.xml which is used to track retrieved files. I am also concerned about what happens when the BPEL project is used in a team development fashion (i.e. One developer executes the scenario described above and then checks this project into a source code repository and eventually another team member checks this file out. We need to make sure that the project is still viable across such developer work flow.

Use Case: User wants to create a Partner Link that refers to a Web Service defined by another NB BPEL project

User wants to create a new PartnerLink that refers to a web service definitin (WSDL file) defined in another BPEL project.

Scenario

• One can consider this to be just a special case of “User wants to create a Partner Link that refers to a Web Service defined in another arbitrary NB project”

  • This is reasonably addressed by “User wants to create a Partner Link that refers to a Web Service defined in another arbitrary NB project”

  • See open question below. We could eventually address this another way vis DnD of BPEL node. But that is out of scope for this release.

Open questions/issues

I believe we should eventually enable the DnD of one BPEL process into another, but this will require a non-trivial UI. It is not as simple as DnD of a single WSDL file because the BPEL process potentially implements one Role in several PartnerLinkTypes, which may be defined in different WSDL files. (see TravelReservationService for example). Therefore, it is not easy to determine just how much to automatically retrieve for the DnD'd BPEL process. This will have to wait until the next development cycle.

Partner Link Editor

The Partner Link editor has been modified to address the above use cases. It is presented here for reference when reading the user cases.

Name : Text Field. The name of the Partner Link element. This name is arbitrary and may be set by the developer. It must be valid according to the BPEL specfication and it must be unique. For new PartnerLinks it will be pre-populated with a unique name.

WSDL File : Drop down list. This contains the list of WSDL files that are present under the src directory of the current BPEL module. The file names are relative to the src directory. (Note, it appears there is a bug and the names are preceded by an unnecessary “/”. This does not seem to have any negative affect on the generated code but it hurts readability of the list ). When the user changes the selecton in the WSDL file drop down list, many of the fields below that are derivative of the WSDL file selection must automatically adjust their values.

Use Existing Partner Link Type : Radio Button. If selected, this radio button indicates the user's decision to base the PartnerLink definition on an existing PartnerLinkType definition. For new PartnerLink definitions this choice should be the default choice if the currently selected WSDL file has one or more already defined PartnerLinkTypes.

PartnerLinkType : Drop down list. This contains the names of the PartnerLinkType elements that are already defined in the currently selected WSDL file. The contents of this list are derivative of the value in the WSDL file drop down list. The user may choose from any of the available PartnerLinkTypes in this list.

My Role : non-editable text. This field shows the name of one of the roles defined for the selected PartnerLinkType. Each PartnerLinkType may declare one or two roles. The PartnerLink definition may associate one of the available PartnerLinkType roles with the ParnterLink MyRole attribute. See also Partner Role. At least one of the two, My Role and/or Partner Role must have a value. If there are two roles defined for the selected ParnterLinkType, then this field is pre-populated with the second of the two.

Partner Role : non-editable text. This field shows the name of one of the roles defined for the selected PartnerLinkType. Each PartnerLinkType may declare one or two roles. The PartnerLink definition may associate one of the available PartnerLinkType roles with the ParnterLink PartnerRole attribute. See also My Role. At least one of the two, My Role and/or Partner Role must have a value. This field is pre-populated with the first of the available roles defined for the selected PartnerLinkType.

Swap Roles: button. This button allows the developer to swap the values in the My Role and Partner Role fields.

Use a Newly Created Partner Link Type : Radio Button. If selected, this radio button indicates the user's decision to base the PartnerLink definition on a brand new PartnerLinkType definition. For new PartnerLink definitions this choice should be the default choice if the currently selected WSDL file does not have any already defined PartnerLinkTypes. This choice has the effect of indicating that the user wished to define not only the ParterLink in the current BPEL process, but that he also wishes to modify the selected WSDL file (see WSDL File drop down list) by adding a new ParterLinkType definition at this moment. That means that two files will be modified by this edit action.

Partner Link Type Name : Text Field. The name of the new PartnerLinkType element. This name is arbitrary and must be set by the developer. It must be valid according to the BPEL specfication and it should be unique within the target WSDL file's PartnerLinkTypes.. It is not pre-populated at this time. (TODO – it would be nice to pre-populate and it would be nice to check for uniqueness. Today we are not checking for uniqueness in the target WSDL file. This could be considered a bug).

Process will implement (My Role) : check box. This check box indicates the user's intent to define the select this role as the role that will be referenced by the MyRole attribute in the PartnerLink definition. Effectively, the user will be doing two things at once in this definition. He will be giving the role a name that will be used in the role attribute of the ParterLinkType definition in the WSDL file. And at the same time he is indicating that this role will be referenced by the MyRole attribute in the new ParterLink definition. Effectively, the user is indicating that the current BPEL process will implement the web service PortType associated with this PartnerLinkType. That is why the label read's “Process will Implement”. That is to help the user understand the implications of selecting a MyRole value.

Partner will implement (Partner Role) : check box. This check box indicates the user's intent to define the select this role as the role that will be referenced by the PartnerRole attribute in the PartnerLink definition. Effectively, the user will be doing two things at once in this definition. He will be giving the role a name that will be used in the role attribute of the ParterLinkType definition in the WSDL file. And at the same time he is indicating that this role will be referenced by the PartnerRole attribute in the new ParterLink definition. Effectively, the user is indicating that the partner sevice must implement the web service PortType associated with this PartnerLinkType. That is why the label read's “Partner will Implement”. That is to help the user understand the implications of selecting a PartnerRole value.

Role Name: text field. The name of one of the roles that will be added to the new ParnterLinkType definition in the WSDL file. This name is arbitary and must conform to the BPEL specfication.

Port Type: drop down list. The list of PortTypes that are present in the WSDL file. The value of this field will be used for the PortType attribute in the newly defined ParterLinkType.

TODO – add the mnemonic and a11y details.