Partner Link elements identify the parties that interact with your business process. Each link is defined by a partner link type and a role name.
The type determines the relationship between a process and its partners by defining the roles played by each service in a conversation. The relationship is further determined by specifying the port type provided by each service to receive messages. Each role specifies one port type in the WSDL file.
Roles determine the conversational aspect of this process or its partner. You use a single role for a synchronous operation as the results are returned using the same operation. You use two roles in an asynchronous operation as the partner role switches during a callback.
It is easy to confuse partner links and partner link types, however:
Partner link types and roles are special WSDL extensions defined by the BPEL specification. As such, they are defined in WSDL files, not in the process BPEL file.
Partner Link is a BPEL 2.0 element. It is defined in the process BPEL file.
Partner link types are prerequisites to the Partner Link element definition. A Partner Link element can only be defined by referring to a particular partner link type and role which, as mentioned, must be defined in a WSDL file.
To add the Partner Link element to the BPEL process, do one of the following:
Drag the Partner Link element from the Palette to the diagram.
Drag a WSDL file node from the same project in the Projects window to the diagram.
Drag a WSDL file node from a different project in the Projects window to the diagram.
Drag a web service node from an EJB project or a Web Application project in the Projects window to the diagram.
When you drag the web service node, the BPEL Designer retrieves the WSDL file from the Application Server. To successfully retrieve the WSDL file, the Application Server has to be running and the web service project must be deployed.
When you attempt to create a Partner Link by dragging a WSDL or Web Service to the BPEL Designer's Design View, the Partner Link Property Editor appears and a reference is created in the Project tree and source code. If the resulting Partner Link is cancelled, the reference remains in the Project tree and source code. These references do not affect the process or project. The reference can be removed manually if desired.
When you drag the Partner Link element, a WSDL file node, or a web service node to the diagram, the Partner Link Property Editor appears.
The Partner Link Property Editor allows you to establish partner links for your BPEL processes.
The Partner Link Property Editor is invoked by double-clicking a Partner Link element on the diagram, or right-clicking the Partner Link element and choosing Edit. The Partner Link Property Editor also appears when you drag the Partner Link element, a WSDL file node, or a web service node to the diagram.
With the Partner Link Property Editor, you can specify:
Name: Specifies the name of the Invoke element.
WSDL File: Indicates the WSDL file associated with the Partner Link.
Partner Link Type: Indicates the Partner Link type defined in the WSDL.
My Role: Indicates the role of the business process itself.
Partner Pole: Indicates the role of the partner.
Documentation: Accessed on the Properties window. Specifies documentation to attach to the element. This documentation is included in the source code of the BPEL process and can be extracted and included in a report.
You can choose whether to use the existing partner link type or create a new partner link type.
If the WSDL file you selected contains partner link types, the Use Existing Partner Link Type option is selected and the Partner Link Type drop-down list is populated with the partner link types found in the WSDL file. You can use one of the existing partner link types or select the Use a Newly Created Partner Link Type option to create a new partner link type.
If the WSDL file does not contain partner link types, the Use a Newly Created Partner Link Type option is selected.
Use Existing Partner Link Type
Choose the partner link type from the drop-down list. The My Role and/or Partner Role fields are filled in automatically.
To swap the roles of the business process itself (My Role) and the partner (Partner Role), click the Swap Roles button.
Use a Newly Created Partner Link Type
Specify the WSDL file in which to add a partner link type. You can do one of the following:
Add the partner link type to the wrapper WSDL file, as suggested by the IDE in the Create in File field by default. If you choose this option, the IDE will automatically create the wrapper WSDL file in your project structure. You can use wrapper WSDL files when the original WSDL file is read-only or when you do not want to modify the original WSDL file. The original WSDL file will be imported to the newly created wrapper WSDL file.
Add the partner link type to a WSDL file within your project. Click Browse and locate the WSDL file in which to add the partner link type.
Specify the partner link type name.
Specify the role of the business process itself (My Role) and/or the role of the partner (Partner Role) as follows:
Select the appropriate checkbox.
Specify the role name.
Choose the port type from the drop-down list.
You can also review and modify the Partner Link's properties in the Properties window invoked by right-clicking the element and choosing Properties.
The partner links are placed in the left and right margins of the process diagram. Service requestors are placed on the left side, service providers are placed on the right side. To define the role and to choose the appropriate side for each partner link the IDE uses the order of roles defined for the partnerLinkType in the WSDL file.
The role defined first in the partnerLinkType in the WSDL file is considered to be a service role, the second defined role is considered to be the role for the requestor and callback receiver. If the roles are defined in the reverse order in the WSDL file (the callback receiver role is defined in the first place, and the service role in the second place) then you get the improper partner link layout in the BPEL process diagram, though the operation is not damaged. If a partner link appears on the wrong side you should go to the WSDL file and swap places for the role definitions in the partnerLinkType.
During the design-time of an application, you may need to configure certain services whose endpoints (addresses) are not known beforehand, or it may be necessary to change an endpoint reference while the application is running. The Dynamic Partner link feature allows you to dynamically assign an endpoint reference to the partner link. This means that you can use one partner link for subsequent calls to different web-services (provided that the services use the same interface).
See Using Dynamic Partner Links and Dynamic Addressing for additional use cases and more information.
Assigning an Endpoint Reference
Each partner link defines abstract information and concrete information. While abstract information, describing the web-service interface, should be static, the concrete information, such as the address and port, can be discovered and used dynamically.
For successful deployment of the process, a partner link should be completely defined. When you deploy the project, the WSDL file for the partner link should contain and define both the abstract and the concrete information for the partner link, including address and port, though later the concrete information can be changed independently from the WSDL file.
The BPEL specification mandates that only the partner endpoint reference (EPR) can be changed dynamically. In BPEL terms, only the partnerRole of a partner link element can have a new value assigned. The myRole value doesn't change after the BPEL has been deployed.
To assign a new endpoint reference to a partner link you can use the standard Assign activity and the BPEL Mapper.
The EPR information can be provided in several different ways:
Use literal to construct endpoint: Provide the endpoint address as literal syntax and map it to the partner link.
Use an existing partner link's endpoint: Extract a partner link's endpoint and assign it to another partner link in the BPEL Mapper.
Use an incoming message to extract the endpoint address: Define the message with the end point schema as part of it, and use the message variable to assign the endpoint to the partner link at runtime.
Using a database query to provide an endpoint address The BPEL service does a dynamic addressing invocation, with the address coming from a database.
Each of these options is explained in more detail in the advanced section of this book. For more information on each of these alternatives, see Using Dynamic Partner Links and Dynamic Addressing.
If you use an incoming message, an EPR schema should be defined as a part of the message in WSDL. To assign the EPR to a partner link, use the message variable.
Create a new Assign activity in the process.
Open the BPEL Mapper.
In the target tree on the right, find the partner link to which you want to deliver a new concrete part.
In the source tree, find a variable containing the new endpoint address.
The address of the web-service can be defined in terms of different schemas, and the JBI container requires a special data type called ServiceRefType which is a simple wrapper for any endpoint-describing data type.
To wrap your data:
In the mapper toolbar, choose BPEL -> Wrap with Service Reference.
This function is a doXslTranform function that uses a predefined XSL-style sheet. A new concrete part is assigned to the partner link.
The runtime supports only schemas included into WS-BPEL 2.0 specification. The WS-Addressing schema is not included in the BPEL specification and as a result it is not supported by the BPEL runtime. When the WS-Addressing schema is used for the first time it is copied from NetBeans global catalog to the BPEL Module project source root and further the project refers to the local copy of the schema. The adressing.xsd schema also appears among the Module's process files in the Projects window.