Console Online Help
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
This section includes the following topics:
This section includes the following topics:
Proxy services are AquaLogic Service Bus definitions of Web services implemented locally on WebLogic Server. You define a proxy service in terms of WSDLs, pipelines, and policies. If the proxy service requires security credentials, you can create a proxy service provider to manage these security credentials from the AquaLogic Service Bus Console. For information on how to configure a proxy service provider, see Adding a Proxy Service Provider. You can configure access control policies on HTTP/S proxy services. To learn more, see Listing and Locating Access Control Policies.
You implement a proxy service through configuring its Message Flow. Message Flows can include pipeline pairs and the following nodes: Start, Route, Echo, and Branch. To learn more, see Overview of Message Flow and Viewing and Changing Message Flow.
The following table lists the pages you can access from the Project Explorer and Resource Browser modules. The tasks and help topics associated with each are provided.
Table 14-1 Pages Accessed from Project Explorer and Resource Browser Modules
Each service type is modeled following the same pattern. Their configuration is composed of a common part and a service type specific part.
The common configuration consists of the following properties:
Table 14-2 Service Type Configuration
Each service type must define the following configurations:
$operation
, $body
, $header
, $attachments
)Table 14-3 Service Type Configuration
You can base SOAP and XML services on an existing WSDL resource. A WSDL document is available for proxy and business services for any transport. This WSDL is used as the base for the final WSDL document. When you create a business service or proxy service based on a WSDL, you can select only a WSDL port or a WSDL binding, as a WSDL may only have one of these entities defined. The WSDL port describes what the actual transport address is. You use it for a concrete interface. For a definition of a WSDL port, see http://www.w3.org/TR/wsdl#_ports. When you create a proxy service based on a WSDL Binding, AquaLogic Service Bus sets the new service and port definitions in the WSDL generated for the proxy service. Regardless of whether you define a proxy service based on a WSDL port or a WSDL binding, the WSDL generated for the proxy service defines only a single port. If the service is generated from port X in the template WSDL, then port X is also defined in the generated WSDL. Any other ports defined in the template WSDL are not included in the generated WSDL. Furthermore, if you base the proxy service on a WSDL port, the generated WSDL uses that port name and preserves any WS-Policies associated with that port. The binding is determined from the port, and in turn, the port type is determined from the binding. If the service is generated from binding Y in the template WSDL, the generated WSDL defines a new service and port (<service-name>QSService and <port-name>QSPort). None of the ports defined in the template WSDL are included in the generated WSDL. If you base the service on a WSDL binding template, there may be multiple ports in that WSDL associated with that binding. Each port can use a different URL and have a different WS-Policy attached to it. Therefore, the generated WSDL uses the binding but generates an artificial port for that binding with no WS-Policy. For all WSDL-based services, the transport type and transport URL can be overwritten in the transport section of the service definition. Note: You can get the WSDL for an HTTP(S)-based proxy service by entering the URL for the service appended with ?WSDL in your browser's Address field. |
|
You can base SOAP and XML services on an existing WSDL resource. A WSDL document is available for proxy and business services for any transport. This WSDL is used as the base for the final WSDL document. When you create a business service or proxy service based on a WSDL, you can select only a WSDL port or a WSDL binding, as a WSDL may only have one of these entities defined. The WSDL binding describes the structure of the interface and how it is packaged. You use it to map the transport address. For a definition of a WSDL Binding, see http://www.w3.org/TR/wsdl#_bindings. You may change the transport protocol of a service to another compatible one. The transport attribute of the For SOAP services, any existing For XML services, the only standard WSDL binding definition available is the one defined for HTTP. However, BEA has added its own standard definition for JMS. So, except in the case of the JMS transport protocol, the standard HTTP binding is used. As for SOAP, any existing |
|
Binding Definition: The only information this service type defines is that the service is receiving or sending SOAP messages—regardless of their WSDL binding definition. Therefore the binding configuration for this type is empty. In addition, as there is no binding configuration, the combination of this type and the content-type of the message is sufficient to determine whether or not there are attachments to the message. As per their definition, any services (SOAP or XML) do not have any WSDL definition. It is not possible to request a WSDL document for those services. The The The To learn more about the message context variables, see Message-Related Variables and Constructing Messages to Dispatch. |
|
Binding Definition: The only information this service type defines is that the service is receiving/sending XML messages—regardless of their WSDL binding definition. Therefore, the binding configuration for this type is empty. In addition, as there is no binding configuration, the combination of this type and the content-type of the message is sufficient to determine whether or not there are attachments to the message. As per their definition, any services (SOAP or XML) do not have any WSDL definition. It is not possible to request a WSDL document for those services. The The The The To learn more about the message context variables, see Message-Related Variables and Constructing Messages to Dispatch. |
|
Binding Definition: The binding definition for messaging services consists of configuring the content-type of the messages that are exchanged. The content-type for the response does not need to be the same as for the request; therefore, the response is configured separately (for example, the service could accept an MFL message and return an XML acknowledgment receipt). As per their definition, messaging-based services do not have any WSDL definition. It is not possible to request a WSDL document for those services. There are four available content types to choose from for the request (and response): This service type is message based. There is no concept of multiple "operations" as for Web services. Therefore, the The The The To learn more about the message context variables, see Message-Related Variables and Constructing Messages to Dispatch. |
The following types of service types and transports are supported by AquaLogic Service Bus:
Table 14-4 Service Types and Transports Supported by AquaLogic Service Bus
JMS1 |
|
XML (no WSDL)2 |
|
The Edit a Proxy Service - General Configuration page enables you to add a proxy service.
Proxy services are AquaLogic Service Bus definitions of Web services implemented locally on WebLogic Server. You define a proxy service in terms of WSDLs, pipelines, and policies. To learn more, see Overview of Proxy Services.
To add a proxy service, you must first configure general information for the service, configure general and protocol-dependent transport information for the service, then configure operation selection algorithms for the service if it includes operations. If this is a messaging service, you must also configure the message types. You can review the configuration before you create the proxy service.
The tasks in this procedure include:
Note: Click the name of a folder to select it. The Folder View page is displayed.
Note: A service type defines the types and packaging of the messages exchanged by the service. This is a required field.
Note: When you create a business service or proxy service based on a WSDL, you can select only a WSDL port or a WSDL binding, as a WSDL may only have one of these entities defined. The WSDL port describes what the actual transport address is. You use it for a concrete interface. To learn more about this service type, see Service Types and Service Types and Transports in Overview of Proxy Services. See also Generating WSDLs from a Proxy Service in this topic. |
|
Note: When you create a business service or proxy service based on a WSDL, you can select only a WSDL port or a WSDL binding, as a WSDL may only have one of these entities defined. The WSDL binding describes the structure of the interface and how it is packaged. You use it to map the transport address. To learn more about this service type, see Service Types and Service Types and Transports in Overview of Proxy Services. See also Generating WSDLs from a Proxy Service in this topic. |
|
Select Messaging Service to create a service that can receive messages of one data type and respond with messages of a different data type. These exchanges can be either request/response or one-way. Unlike Web services, the content-type of the request and response need not be the same. To learn more about this service type, see Service Types and Service Types and Transports in Overview of Proxy Services. |
|
Create a SOAP service that does not have an explicitly defined, concrete interface |
Select Any SOAP Service to create a SOAP service that does not have an explicitly defined, concrete interface. To learn more about this service type, see Service Types and Service Types and Transports in Overview of Proxy Services. |
Create an XML service that does not have an explicitly defined, concrete interface |
Select Any XML Service to create an XML service that does not have an explicitly defined, concrete interface. Note: HTTP GET is only supported in the Any XML Service service type. To learn more about this service type, see Service Types and Service Types and Transports in Overview of Proxy Services. |
This enables you to create a proxy service with a route node that routes to the business service you select. To learn more about business services, see Overview of Business Services. |
|
This enables you to clone a new proxy service from the proxy service you select. |
A proxy service provider is only required in certain cases: Outbound 2-way TLS/SSL, where the proxy service routes messages to HTTPS services that require client-certificate authentication, or in some Web service security scenarios; for example, if the proxy service requires messages to be encrypted. To learn more about proxy service providers, see Overview of Proxy Service Providers. To learn how to create a proxy service provider, see Adding a Proxy Service Provider.
If you selected Messaging Service in the Service Type field, the Edit a Proxy Service - Message Type Configuration page is displayed. Continue in To Add a Proxy Service - Messaging Type Configuration.
For all other service types, the Edit a Proxy Service - Transport Configuration page is displayed. Continue in To Add a Proxy Service - Transport Configuration.
If you selected Messaging Service in the Service Type field, the Edit a Proxy Service - Message Type Configuration page is displayed when you click Next on the Edit a Proxy Service - General Configuration page.
The binding definition for messaging services consists of configuring the content-type of the messages that are exchanged. The content-type for the response does not need to be the same as for the request; therefore, the response is configured separately (for example, the service could accept an MFL message and return an XML acknowledgment receipt).
Table 14-6 Request Message Type Field
Table 14-7 Response Message Type Field
The Transport Configuration page is displayed. Continue in To Add a Proxy Service - Transport Configuration.
The Transport Configuration page is displayed when you click Next on the Edit a Proxy Service - General Configuration page. It is displayed for messaging services when you click Next on the Edit a Proxy Service - Message Type Configuration page.
This page enables you to configure transport information for the proxy service. To learn more about the types of service types and transports supported by AquaLogic Service Bus, see Service Types and Transports.
Note: Inbound transport-level security applies to the client applications and AquaLogic Service Bus proxy services. Outbound transport-level security applies to the connections between AquaLogic Service Bus proxy services and business services. To learn more about transport-level security, see "Transport-Level Security" in Securing Inbound and Outbound Messages in the BEA AquaLogic Service Bus User Guide.
To target a target a JMS destination to multiple servers, use the following URI format: |
Note: You can configure multiple URLs. You can click Delete in the Action column to delete them at any time. At run time, the URLs are selected based on the load balancing algorithm you selected in the Load Balancing Algorithm field.
An additional Transport Configuration page is displayed. This page enables you to configure protocol-dependent transport information for the proxy service. Continue in To Add a Proxy Service - Protocol-Dependent Transport Configuration.
The [Protocol] Transport Configuration page is displayed when you click Next on the Edit a Proxy Service - Transport Configuration page. This page enables you to configure additional transport information for the proxy service, based on the transport protocol you selected in the Protocol field.
1. Select the Basic Authentication Required checkbox to specify that basic authentication is required to access this service, or leave it blank to specify that basic authentication is not required. Basic authentication instructs WebLogic Server to authenticate the client using a username and password against the authentication providers configured in the security realm, such as a Lightweight Directory Access Protocol (LDAP) directory service and Windows Active Directory. The client must send its username and password on the HTTP request header. Note: Basic authentication is strongly discouraged over HTTP because the password is sent in clear text. However, it is safe to send passwords over HTTPS because HTTPS provides an encrypted channel. Warning: When you create an HTTP proxy service endpoint that requires Basic Authentication, a transport-authorization policy is not automatically associated with the inbound endpoint URI. For Basic Authentication to be enforced, you must define a transport-authorization policy for the endpoint. To learn more, see Securing Inbound and Outbound Messages in the BEA AquaLogic Service Bus User Guide. 2. In the Dispatch Policy field, select a dispatch policy for this endpoint. Leave blank to use the default dispatch policy.
|
|
1. In the Client Authentication field, select the client authentication method: None, Basic, or Client certificates. Warning: When you create an HTTPS proxy service endpoint that requires Basic Authentication, a transport-authorization policy is not automatically associated with the inbound endpoint URI. For Basic Authentication to be enforced, you must define a transport-authorization policy for the endpoint. To learn more, see Securing Inbound and Outbound Messages in the BEA AquaLogic Service Bus User Guide. 2. In the Dispatch Policy field, select a dispatch policy for this endpoint. Leave blank to use the default dispatch policy.
|
|
2. Select the Use SSL checkbox if the requests are made over a TLS/SSL connection or leave blank if they are not. TLS/SSL (Secure Sockets Layer) provides secure connections by allowing two applications connecting over a network to authenticate the other's identity and by encrypting the data exchanged between the applications. Authentication allows a server, and optionally a client, to verify the identity of the application on the other end of a network connection. Additionally, if the administrator has restricted access to individual JMS destinations (queues or topics) by setting access control on the JNDI entry for the destination, the Business Service must authenticate when looking up the entry in the JNDI tree with a username and password. 3. If you selected Queue in the Destination Type field, select the Is Response Required checkbox or leave it blank. This checkbox determines whether or not a response is expected after an outbound message is sent. When you select the checkbox, you must enter data in an additional field: Response URI. 4. In the Response URI field, enter a response URI in the format 6. In the Request encoding field, accept the default 7. In the Response encoding field, accept the default 8. In the JMS service account field, select a service account to use for the JMS server connection. A service account is an alias resource for a User ID and its associated password. To learn more about service accounts, see Overview of Service Accounts. |
|
3. In the Email Protocol field, select POP3 or IMAP as the server type for the email account. This is a required field. 4. In the Read Limit field, specify the maximum number of messages to read per polling sweep. Enter 5. Select the Pass By Reference field to stage the file in the archive directory and pass it as a reference in the headers, or leave the field blank not to do this.
Note: This is a required field. 8. In the IMAP Move Folder field, enter the folder to which the message is moved if the Post Read Action field is set to Move. 9. In the Download Directory field, enter a temporary location for downloading the emails. This is a required field. 10. In the Archive Directory field, specify the path to the archive location if the Post Read Action field is set to Archive. The Archive Directory field is also a required field if you have selected the Pass By Reference field. |
|
1. In the File Mask field, enter the regular expression for the files to be picked. The default is *.*.This is a required field. 2. In the Polling Interval field, enter a polling interval, in seconds. The default is 60. This is a required field. 3. In the Read Limit field, specify the maximum number of messages to read per polling sweep. Enter 4. Select the Sort By Arrival checkbox to deliver events in the order of arrival, or leave blank not to do this. 5. Select the Scan SubDirectories checkbox to recursively scan all the directories or leave blank not to do this. 6. Select the Pass By Reference checkbox to stage the file in the archive directory and pass it as a reference in the headers, or leave the field blank not to do this. 8. In the Stage Directory field, enter an intermediate directory to temporarily stage the files while processing them. This is a required field. 9. In the Archive Directory field, specify the path to the archive location if the Post Read Action field is set to Archive. The Archive Directory field is also a required field if you have selected the Pass By Reference field. |
|
1. In the User Authentication field, select anonymous if the user of the FTP server is anonymous or select external_user if the user of the FTP server is an externally configured account. 2. In the Mail ID or Service Account field, enter the mail ID for the anonymous user if you selected anonymous in the User Authentication field, or enter the service account if you selected external_user in the User Authentication field. This is a required field if you selected external_user. 3. Select the Scan SubDirectories checkbox to recursively scan all the directories or leave blank not to do this. 4. Select the Pass By Reference checkbox to stage the file in the archive directory and pass it as a reference in the headers. 6. Select the Remote Streaming checkbox to directly stream the ftp files from the remote server at the time of processing or leave blank not to do this. 7. In the Timeout field, enter the socket timeout interval, in seconds, before the connection is dropped. If you enter 0, there is no timeout. 9. In the File Mask field, enter the regular expression for the files to be picked. The default is *.*.This is a required field. 10. In the Polling Interval field, enter a polling interval, in seconds. The default is 60. This is a required field. 11. In the Read Limit field, specify the maximum number of messages to read per polling sweep. Enter 12. In the Post Read Action field, select what happens to a message after it has been read. This is a required field: 14. In the Archive Directory field, specify the path to the archive location if the Post Read Action field is set to Archive. The Archive Directory field is also a required field if you have selected the Pass By Reference field. 15. In the Download Directory field, enter the directory on your local machine where files are downloaded during the file transfer. This is a required field. |
If this service has operations, the Edit a Proxy Service - Operation Selection Configuration page is displayed. Continue in To Add a Proxy Service - Operation Selection Configuration.
If this service does not have operations, the General Configuration Review page is displayed. Continue in To Add a Proxy Service - General Configuration Review.
If this service has operations, the Operation Selection Configuration page is displayed when you click Next on the Protocol Transport Configuration page. This page enables you to select the selection algorithm to use to determine the operation called by this proxy service. This option is only available for SOAP or XML services defined from a WSDL.
The WSDL specification defines a default algorithm to compute which operation is called based on the type of the SOAP message received. However, there are cases (for example, performance issues, signature/encryption issues, or the default algorithm is not applicable) when you may need to select the operation based on other means.
AquaLogic Service Bus provides additional algorithms. Each of them follows the same pattern and are based on the evaluation of an expression to get a value that is then used to lookup the corresponding operation in a static table.
Table 14-10 Selection Algorithm Field
Note: If you are creating an XML service type based on a WSDL port or binding, the following selection algorithms are displayed on this page: Transport Header and Payload Type.
Note: Additional fields are displayed depending on the selection algorithm you select.
Table 14-11 Selection Algorithm Field
The General Configuration Review page is displayed. Continue in To Add a Proxy Service - General Configuration Review.
Note: If the proxy service is created from a WSDL (port or binding) that has WS-Policies attached, the Web Services Security Configuration page is displayed when you click Next. This page displays read-only views of the effective request/response WS-Policy for all operations.
To learn more, see see Securing Inbound and Outbound Messages in the BEA AquaLogic Service Bus User Guide.
The General Configuration Review page is displayed when you click Next on the Operation Selection Configuration page. This page enables you to review the configuration data that you have entered for this proxy service. If necessary, you can click Edit to make changes to the configuration before you save the proxy service.
The Project View or Folder View page is displayed. The new proxy service is included in the list of resources.
Note: After you create a proxy service, the next step is to configure its Message Flow. Message Flow defines the implementation of a proxy service. Message Flows can include pipeline pairs and the following nodes: Start, Route, Echo, and Branch. To learn more, see Overview of Message Flow and Viewing and Changing Message Flow.
Note: The new proxy service is saved in the current session. When you have finished making changes to this configuration, from the left navigation pane, click Activate under Change Center. The session ends and the core configuration is updated. Alternatively, click Discard at any time during the session to delete the changes you have made so far in the current session.
When you create a proxy service based on a WSDL Binding, AquaLogic Service Bus sets the new service and port definitions in the WSDL generated for the proxy service. Regardless of whether you define a proxy service based on a WSDL port or a WSDL binding, the WSDL generated for the proxy service defines only a single port. If the service is generated from port X in the template WSDL, then port X is also defined in the generated WSDL. Any other ports defined in the template WSDL are not included in the generated WSDL. Furthermore, if you base the proxy service on a WSDL port, the generated WSDL uses that port name and preserves any WS-Policies associated with that port. The binding is determined from the port, and in turn, the port type is determined from the binding.
If the service is generated from binding Y in the template WSDL, the generated WSDL defines a new service and port (<service-name>QSService and <port-name>QSPort). None of the ports defined in the template WSDL are included in the generated WSDL.
If you base the service on a WSDL binding template, there may be multiple ports in that WSDL associated with that binding. Each port can use a different URL and have a different WS-Policy attached to it. Therefore, the generated WSDL uses the binding but generates an artificial port for that binding with no WS-Policy. For all WSDL-based services, the transport type and transport URL can be overwritten in the transport section of the service definition.
You can get the WSDL for an HTTP(S)-based proxy service by entering the URL for the service appended with ?WSDL in your browser's Address field.
Listing and Locating Proxy Services
Viewing and Changing Proxy Services
Viewing and Changing Message Flow
The Summary of Proxy Services page enables you to view a list of proxy services. Proxy services are AquaLogic Service Bus definitions of Web services implemented locally on WebLogic Server. To learn more, see Overview of Proxy Services.
Table 14-12 Summary of Proxy Services Page
A unique name for the proxy service. The name is a link to the View Details page. To learn more, see Viewing and Changing Proxy Services. |
|
The path is the project name and the name of the folder in which the proxy service resides. It is a link to the project or folder that contains this resource. To learn more, see Viewing Project Details or Viewing Folder Details. |
|
The Options column displays the following:
|
Viewing and Changing Message Flow
The View Details page enables you to view and edit details of a specific proxy service. To learn more, see Overview of Proxy Services.
The View Details page displays the following information
The number of objects that this proxy service references. If such references exist, click the link to view a list of the objects. To learn more, see Viewing References. |
|
The number of objects that reference this proxy service. If such references exist, click the link to view a list of the objects. To learn more, see Viewing References. |
|
The View Details page displays the following General Configuration information:
Table 14-14 General Configuration Information
If the service type for this proxy service is Messaging Service, the page displays the following Message Type Configuration information:
Table 14-15 Message Type Configuration Information
A message type for the request message: Binary, Text, MFL, or XML. |
|
A message type for the response message: None, Binary, Text, MFL, or XML. |
The page displays the following Transport Configuration information:
Table 14-16 Transport Configuration Information
If the transport protocol is Email, the page displays the following Email Transport Configuration information:
Table 14-17 Email Transport Configuration Information
If the transport protocol is File, the page displays the following File Transport Configuration information:
Table 14-18 File Transport Configuration Information
If the transport protocol is FTP, the page displays the following FTP Transport Configuration information:
Table 14-19 FTP Transport Configuration Information
If the transport protocol is HTTP, the page displays the following HTTP Transport Configuration information:
Table 14-20 HTTP Transport Configuration Information
If the transport protocol is HTTPS, the page displays the following HTTPS Transport Configuration information:
Table 14-21 HTTPS Transport Configuration Information
If the transport protocol is JMS, the page displays the following JMS Transport Configuration information.
Table 14-22 JMS Transport Configuration Information
The page displays the following Operation Selection Configuration information:
Table 14-23 Operation Selection Configuration Information
Note: You cannot change the Service Name or Service Type fields.
Note: The proxy service is updated in the current session. When you have finished making changes to this configuration, from the left navigation pane, click Activate under Change Center. The session ends and the core configuration is updated. Alternatively, click Discard at any time during the session to delete the changes you have made so far in the current session.
Viewing and Changing Message Flow
The Summary of Proxy Services page enables you to delete a proxy service. To learn more, see Overview of Proxy Services.
Note: You cannot delete a resource if it is referenced by other resources in AquaLogic Service Bus. Instead of the Delete icon, a Delete icon with a red X is displayed for these resources.
Note: You must delete all service-level access control policies and transport-level access control policies associated with a proxy service before you delete that service from AquaLogic Service Bus.
The proxy service is removed from the list.
Note: If necessary, you can undo the deletion of this resource. To learn more, see Undoing a Task.
The proxy service is deleted in the current session. When you have finished making changes to this configuration, from the left navigation pane, click Activate under Change Center. The session ends and the core configuration is updated. Alternatively, click Discard at any time during the session to delete the changes you have made so far in the current session.
Viewing and Changing Proxy Services
Viewing and Changing Message Flow
Message Flow defines the implementation of a proxy service. Message Flows can include pipeline pairs and the following nodes: Start, Route, Echo, and Branch. To learn how to implement Message Flow, see Viewing and Changing Message Flow.
This section includes the following topics:
A pipeline is a named sequence of stages representing a non-branching one-way processing path.
Pipelines are typed into one of three categories:
Table 14-24 Pipeline Categories
Request pipelines are used for processing the request path of the Message Flow. |
|
Response pipelines are used for processing the response path of the Message Flow. |
|
To create the request and response paths, request and response pipelines are paired together and organized into a single-rooted tree structure. A branch node allows you to conditionally execute these pipeline pairs, and route nodes at the ends of the branches perform any request/response dispatching. This tree structure allows for a clear overview of the Message Flow behavior, making both route actions and branch conditions explicit parts of the overall design, rather than burying them deep inside a pipeline stage.
A message flow tree is constructed by chaining together instances of these top-level components:
Table 14-25 Pipeline Categories
The pipeline pair node ties together a single request and a single response pipeline into one top-level element. A pipeline pair node may have only 1 direct descendant in the message flow tree. During request processing, only the request pipeline is executed when visiting a pipeline pair node. When reversing the path for response processing, only the response pipeline is executed. To learn how to add a pipeline pair node, see Adding a Pipeline Pair Node. |
|
A branch node allows processing to proceed down exactly one of several possible paths. Branching is driven by a simple lookup table with each branch tagged with a simple but unique string value. A variable in the message context is designated as the lookup variable for that node, and its value is used to determine which branch to follow. If no branch matches the value of the lookup variable, then the always-present default branch is followed. Setting the value of the lookup variable must be done before reaching the branch node. This approach ensures that exceptions do not occur within the branch node itself. A branch node may have several descendants in the message flow tree: one for each branch including the default branch. To learn how to add a branch node, see Adding a Conditional Branch Node. |
|
The route node is used to perform request/response communication with another service. It represents the boundary between request and response processing for the proxy. When the route node dispatches a request message, request processing is considered finished. When the route node receives a response message, response processing begins. The route node itself has support for conditional routing as well as outbound and response transformations. You can choose whether conditions appear inside the route node or up in the message flow tree as branch nodes—it depends upon whether the condition is important enough to call out as part of the message flow tree structure. As the route node represents the boundary between request and response processing, it cannot have any descendants in the message flow tree. To learn how to add a route node, see Adding a Route Node. |
|
An echo node is a node that routes (or echoes) a message from the end of the request pipeline to the start of the response pipeline. In other words, the message is not routed from the proxy service to another service. It remains within the proxy service. |
The following table demonstrates the journey of a message:
Any element may appear at the root of the message flow tree. One of the simplest of Message Flow designs is to have just a route node at the top representing the entire tree. There is also no restriction on what two elements may be chained together. For example, two pipeline pair nodes may be chained together without a branching node in between. With regards to branching, each branch may start with a different element - one branch may immediately terminate with a route node, another may be followed by a pipeline pair and yet another may have no descendant whatsoever. In the latter case, a branch with no descendants means that response processing begins immediately if that branch is selected. In general, however, a message flow tree is likely to come in two forms: for non-operational services, the tree is likely to consist of a single pipeline pair at the root followed by a route node. For operational services, the tree is likely to consist again of a single pipeline pair at the root, followed by a branch node based on operation, with each branch consisting of a pipeline pair followed by a route node.
Since Message Flow is typically used with WSDL-based services, there is frequently a need to perform processing that is operation-specific. Rather than requiring you to manually configure a branching node based on operation, AquaLogic Service Bus provides a zero-configuration branching node that automatically branches based on operation. A branch is created for each operation defined on the service; the branching variable is $operation
.
To learn how to add an operational branch node, see Adding an Operational Branch Node.
Listing and Locating Proxy Services
Viewing and Changing Proxy Services
The Edit Message Flow page enables you to view and change the Message Flow of a specific proxy service. To learn more about Message Flow, see Overview of Message Flow. To learn more about proxy services, see Overview of Proxy Services.
Alternatively, you can select a project or folder from under Project Explorer to display the project or folder's list of resources.
Alternatively, if you selected a project or folder, click the Edit Message Flow icon for the appropriate proxy service in the list of resources.
The Edit Message Flow page is displayed. The page includes the following functionality:
Table 14-27 Edit Message Flow Page
Click the Start Node icon, then click Add Pipeline Pair. To learn more, see Adding a Pipeline Pair Node. |
|
Click the Start Node icon, then click Add Route Node. To learn more, see Adding a Route Node. |
|
Click the Start Node icon, then click Add Conditional Branch Node. To learn more, see Adding a Conditional Branch Node. |
|
Click the Start Node icon, then click Add Operational Branch Node. To learn more, see Adding an Operational Branch Node. |
|
Click the Start Node icon, then click Add Service Error Handler. To learn more, see Adding Error Handling for the Proxy Service. |
|
Click the Echo Node icon, then click Convert to Route Node. To learn more, see Adding a Route Node. |
|
Save the updates and return to the Summary of Proxy Services page |
|
Disregard changes and return to the Summary of Proxy Services page |
|
Note: When you click Save, the Message Flow is updated in the current session. When you have finished making changes to this configuration, from the left navigation pane, click Activate under Change Center. The session ends and the core configuration is updated. Alternatively, click Discard at any time during the session to delete the changes you have made so far in the current session.
Listing and Locating Proxy Services
Viewing and Changing Proxy Services
The Edit Message Flow page enables you to add a pipeline pair node. A pipeline pair node consists of a request pipeline and a response pipeline. Message Flows can include zero or more pipeline pair nodes: request and response pipelines for the proxy service (or for the operations on the service), and error handler pipelines that can be defined for stages, pipelines, and proxy services. Pipelines can include one or more stages, which in turn include actions. To learn more, see Overview of Message Flow.
On the Summary of Proxy Services page in the Resource Browser, click the Edit Message Flow icon for the appropriate proxy service. Alternatively, if you are in the Project Explorer module, click the Edit Message Flow icon for the appropriate proxy service in the list of resources for a selected project or folder.
The Edit Message Flow page is displayed for the proxy service you selected. The page includes the following functionality:
The Pipeline Pair Node icon and the name you assigned to the pipeline pair node are displayed on the Edit Message Flow page.
Table 14-28 Pipeline Pair Node
Click the appropriate request or response pipeline, then click Add Stage. To learn more, see Adding a Stage. |
|
Click the Stage icon for the appropriate pipeline (if you have already created a stage), click Edit, then click Stage. To learn more, see Adding an Action. |
|
Click the Pipeline Pair Node icon for the pipeline pair you created, click Add, then click Add Pipeline Pair. Alternatively, you can click the Start Node icon again, then click Add Pipeline Pair. |
|
Click the Pipeline Pair Node icon for the pipeline pair you created, click Add, then click Add Route Node. To learn more, see Adding a Route Node. |
|
Click the Pipeline Pair Node icon for the pipeline pair you created, click Add, then click Add Conditional Branch Node. To learn more, see Adding a Conditional Branch Node. |
|
Click the Start Node icon, then click Add Service Error Handler. To learn more, see Adding Error Handling for the Proxy Service. |
|
Click the Echo Node icon, then click Convert to Route Node. To learn more, see Adding a Route Node. |
|
Click the Pipeline Pair Node icon for the pipeline pair you created, click Edit, then click Name and Description. Note: When you rename a pipeline or a route node, the number of messages displayed on the Dashboard page in the Monitoring module may not correlate with those of other components due to the pipeline counters being reset to zero. This is because AquaLogic Service Bus treats the rename as a delete and recreate action. The numbers should correlate again after a time period equal to the service's monitoring interval has elapsed. |
|
Click the Pipeline Pair Node icon for the pipeline pair you created, then click Delete. |
|
Save the updates and return to the Summary of Proxy Services page |
|
Disregard changes and return to the Summary of Proxy Services page |
|
Note: When you click Save, the Message Flow is updated in the current session. When you have finished making changes to this configuration, from the left navigation pane, click Activate under Change Center. The session ends and the core configuration is updated. Alternatively, click Discard at any time during the session to delete the changes you have made so far in the current session.
Listing and Locating Proxy Services
Viewing and Changing Proxy Services
Viewing and Changing Message Flow
The Edit Message Flow page enables you to add a conditional branch node. A branch node allows processing to proceed down exactly one of several possible paths. To learn more, see Overview of Message Flow.
The Edit Message Flow page is displayed for the proxy service you selected. The page includes the following functionality:
Table 14-29 Adding a Conditional Branch Node
Table 14-30 Adding a Conditional Branch Node
Click the Start Node icon, then click Add Pipeline Pair. To learn more, see Adding a Pipeline Pair Node. |
|
Click the appropriate request or response pipeline, then click Add Stage. To learn more, see Adding a Stage. |
|
Click the Stage icon for the appropriate pipeline, click Edit, then click Stage. To learn more, see Adding an Action. |
|
Click the Start Node icon, then click Add Service Error Handler. To learn more, see Adding Error Handling for the Proxy Service. |
|
Click the Conditional Branch icon, click Edit, then click Name and Description. |
|
Click the Conditional Branch icon, click Edit, then click Branch Node. |
|
Click the Conditional Branch icon, then click Delete Branch Node. |
|
Save the updates and return to the Summary of Proxy Services page |
|
Disregard changes and return to the Summary of Proxy Services page |
|
Note: When you click Save, the Message Flow is updated in the current session. When you have finished making changes to this configuration, from the left navigation pane, click Activate under Change Center. The session ends and the core configuration is updated. Alternatively, click Discard at any time during the session to delete the changes you have made so far in the current session.
Viewing and Changing Message Flow
Listing and Locating Proxy Services
Viewing and Changing Proxy Services
The Edit Message Flow page enables you to add an operational branch node.
The Edit Message Flow page is displayed for the proxy service you selected. The page includes the following functionality:
Table 14-31 Adding an Operational Branch Node
Table 14-32 Adding an Operational Branch Node
Click the Start Node icon, then click Add Pipeline Pair. To learn more, see Adding a Pipeline Pair Node. |
|
Click the appropriate request or response pipeline, then click Add Stage. To learn more, see Adding a Stage. |
|
Click the Stage icon for the appropriate pipeline, click Edit, then click Stage. To learn more, see Adding an Action. |
|
Click the Start Node icon, then click Add Conditional Branch Node. To learn more, see Adding a Conditional Branch Node. |
|
Click the Start Node icon, then click Add Route Node. To learn more, see Adding a Route Node. |
|
Click the Start Node icon, then click Add Service Error Handler. To learn more, see Adding Error Handling for the Proxy Service. |
|
Click the Operational Branch icon, click Edit, then click Name and Description. |
|
Click the Operational Branch icon, click Edit, then click Branch Node. |
|
Click the Operational Branch icon, then click Delete Branch Node. |
|
Save the updates and return to the Summary of Proxy Services page |
|
Disregard changes and return to the Summary of Proxy Services page |
|
Note: When you click Save, the Message Flow is updated in the current session. When you have finished making changes to this configuration, from the left navigation pane, click Activate under Change Center. The session ends and the core configuration is updated. Alternatively, click Discard at any time during the session to delete the changes you have made so far in the current session.
Viewing and Changing Message Flow
Listing and Locating Proxy Services
Viewing and Changing Proxy Services
The Edit Message Flow page enables you to add a stage. A stage is a container of actions. To learn more, see Overview of Message Flow.
Note: You must create a pipeline pair node before you can add a stage. To learn more, see Adding a Pipeline Pair Node.
Click the Stage icon, click Edit, then click Stage. To learn more, see Adding an Action. |
|
Click the pipeline, then click Add Pipeline Error Handler. To learn more, see Adding Pipeline Error Handling. |
|
Click the Start Node icon, then click Add Pipeline Pair. Alternatively, you can click an existing Pipeline Pair Node icon, click Add, then click Add Pipeline Pair. To learn more, see Adding a Pipeline Pair Node. |
|
Click the Pipeline Pair Node icon, click Add, then click Add Route Node. To learn more, see Adding a Route Node. |
|
Click the Pipeline Pair Node icon, click Add, then click Add Conditional Branch Node. To learn more, see Adding a Conditional Branch Node. |
|
Click the Start Node icon, then click Add Service Error Handler. To learn more, see Adding Error Handling for the Proxy Service. |
|
Click the Echo Node icon, then click Convert to Route Node. To learn more, see Adding a Route Node. |
|
Click the Stage icon, click Edit, then click Name and Description. |
|
Save the updates and return to the Summary of Proxy Services page |
|
Disregard changes and return to the Summary of Proxy Services page |
|
Clear the unsaved changes and remain on the Edit Message Flow page |
Note: When you click Save, the Message Flow is updated in the current session. When you have finished making changes to this configuration, from the left navigation pane, click Activate under Change Center. The session ends and the core configuration is updated. Alternatively, click Discard at any time during the session to delete the changes you have made so far in the current session.
Viewing and Changing Message Flow
Viewing and Changing Stage Configuration Details
Listing and Locating Proxy Services
Viewing and Changing Proxy Services
The Edit Stage Configuration page enables you to add actions. Actions are the elements of a pipeline stage that define the handling of messages as they flow through a proxy service. To learn more about Message Flow, see Overview of Message Flow.
Note: You must create a pipeline pair node and add a stage before you can add actions. To learn more, see Adding a Pipeline Pair Node and Adding a Stage.
Note: To learn more about actions, see Modeling Message Flow in AquaLogic Service Bus in the BEA AquaLogic Service Bus User Guide for usage scenarios, design patterns, and best practices.
Assign the result of an XQuery expression to a context variable:
2. Click Expression. The Edit an XQuery Expression page is displayed. To learn more, see Editing an XQuery Expression 3. When you have finished editing the expression, enter a context variable in the variable field. To learn more about context variables, see Message Context. |
|
Delete a context variable or all the nodes specified by an XPath expression:
2. To delete a context variable, select the radio button associated with this option, then enter a context variable in the Variable field. To learn more about context variables, see Message Context.
Note: The Delete action is one of a set of Update actions. To learn more, see Update Actions. |
|
Perform if then else actions based on the Boolean result of an XQuery expression: Note: Condition actions can be nested. However, there is a nesting limit of 4 cumulative levels in the stage editor. If you attempt to add a 5th level, this nesting action is not displayed. Cumulative levels include all branching actions: If... Then... Conditions, Publish Tables, and Route Tables. For example, you can have 2 levels of conditionals, then a publish table with a route table inside of it, bringing the total to 4 levels. If you attempt to add another conditional (to the last publish table), the conditional is not displayed.
2. Click Condition. The Edit an XQuery Condition page is displayed. To learn more, see Editing an XQuery Condition. 3. When you have finished editing the XQuery condition, click Add an Action, then select an action that you want to associate with the condition. To learn more about the type of action you want to add, see the appropriate procedure in this table. |
|
Insert the result of an XQuery expression at an identified place relative to nodes selected by an XPath expression:
2. Click Expression. The Edit an XQuery Expression page is displayed. To learn more, see Editing an XQuery Expression. 3. When you have finished editing the expression, select the relative location from the drop-down list. The relative location is used to control where the insert is performed relative to the result of the XPath expression:
4. Click XPath. The Edit an XPath Expression page is displayed. To learn more, see Editing an XPath Expression. 5. When you have finished editing the XPath expression, enter a context variable in the in variable field. To learn more about context variables, see Message Context. Note: XQuery and XPath expressions must both return elements. However, if the XPath expression does not return elements, then the XQuery expression must return attributes. Note: The Insert action is one of a set of Update actions. To learn more, see Update Actions. |
|
Define a set of attributes with which the message is logged:
2. Click Expression. The Edit an XQuery Expression page is displayed. You specify the message context to be logged through XQuery expressions on context variables. To learn more, see Editing an XQuery Expression. |
|
Identify a target service for the message and configure how the message is packaged and sent to that service:
3. Select a service from the list, then click Submit. The service is displayed instead of the default link. This is the target service for the message. 4. In the Request Actions field, to configure how the message is packaged and sent to the service, click Add an Action, then select an action that you want to associate with the service. You can add more than one action. To learn more about the types of actions you want to add, see the appropriate procedure in this table. 5. Continue adding actions as necessary. When you have finished adding request actions, continue to the next step. Note: When a message is published to another service as the result of a Publish or Publish Table action, the default quality of service (QoS) is best effort, if the proxy service inbound transport and the outbound publish action use the JMS/XA transport. Best effort meaning that there is no reliable messaging and there is no elimination of duplicate messages—however, performance is optimized. To override the default best effort quality of service attribute, you must set the Note: Each publish request transformation maintains its own local copy of message context. For more information, see Example Scenarios in Constructing Messages to Dispatch. |
|
A publish table is a set of routes wrapped in a switch-style condition table. It is a short-hand construct that allows different routes to be selected based upon the results of a single XQuery expression. Note: There is a nesting limit of 4 cumulative levels in the stage editor. If you attempt to add a 5th level, this nesting action is not displayed. Cumulative levels include all branching actions: If... Then... Conditions, Publish Tables, and Route Tables. For example, you can have 2 levels of conditionals, then a publish table with a route table inside of it, bringing the total to 4 levels. If you attempt to add another conditional (to the last publish table), the conditional is not displayed. Identify target services for messages and configure how the messages are packaged and sent to these services: 1. Click Add an Action, then select Publish Table. The Publish Table action is displayed, which includes the following functionality:
2. Click Expression. The Edit an XQuery Expression page is displayed. To learn more, see Editing an XQuery Expression. 6. Select a service from the list, then click Submit. The service is displayed instead of the default link. This is the target service for the message. 7. In the Request Actions field, to configure how the message is packaged and sent to the service, click Add an Action, then select an action that you want to associate with the service. You can add more than one action. To learn more about the type of action you want to add, see the appropriate procedure in this table. 8. Continue adding actions as necessary. When you have finished adding actions, continue to the next step. Note: Click the Diamond icon of the last defined case, then select Insert Default Case to add a default case at the end whose routes are selected if none of the preceding cases is satisfied. |
|
Raise an exception with a specified error code (a string) and description:
Note: To learn more about error handling actions, see Error Messages and Handling. |
|
Rename elements selected by an XPath expression without modifying contents:
2. Click XPath. The Edit an XPath Expression page is displayed. To learn more, see Editing an XPath Expression. 3. Enter a context variable in the in variable field. To learn more about context variables, see Message Context.
Note: The Rename action is one of a set of Update actions. To learn more, see Update Actions. |
|
Replace nodes specified by an XPath expression with the result of an XQuery expression:
2. Click XPath. The Edit an XPath Expression page is displayed. To learn more, see Editing an XPath Expression. 3. When you have finished editing the XPath expression, enter a context variable in the in variable field. To learn more about context variables, see Message Context.. 4. Click Expression. The Edit an XQuery Expression page is displayed. To learn more, see Editing an XQuery Expression. 5. When you have finished editing the XQuery expression, select the Replace entire node radio button to replace the nodes your XPath expression selects along with all of its contents, or select the Replace node contents radio button to leave the nodes in place and only replace their contents. Note: The Replace action can be used to replace simple values or elements (XQuery expressions cannot return attributes). If the XPath identifies attributes, then the XQuery expression must evaluate to a simple value. An XQuery expression that returns nothing is equivalent to making the identified nodes empty or deleting the identified attributes. Note: Selecting the Replace node contents option and leaving the XPath field blank is more efficient than selecting the Replace entire node option and setting the XPath to ./*. Note: The Replace action is one of a set of Update actions. To learn more, see Update Actions. |
|
The Reply action can be used in the request, response or error pipeline. It has an option of replying with success or failure. If failure, for SOAP, a HTTP 500 error is returned. Immediately reply to the invoker: 2. Select the With Success radio button to reply that the message was successful or select the With Failure radio button to reply that the message has a fault. Note: To learn more about error handling actions, see Error Messages and Handling. |
|
Enable message reporting for this proxy service:
2. Click Expression. The Edit an XQuery Expression page is displayed. To learn more, see Editing an XQuery Expression. 3. When you have finished editing the XQuery expression, click Add a Key. Two additional fields are displayed: a Key Name field and a Key Value field, which includes an XPath link that you can click to edit an XPath expression and an in variable field in which you can enter a context variable.
5. Click XPath. The Edit an XPath Expression page is displayed. To learn more, see Editing an XPath Expression. 6. Enter a context variable in the in variable field. To learn more, see Message Context. |
|
Skip execution of this stage and proceed to the next stage: Note: This action has no parameters and can be used in the request, response or fault pipelines: |
|
Validate elements selected by an XPath expression against a top level XML schema element or WSDL resource:
2. Click XPath. The Edit an XPath Expression page is displayed. To learn more, see Editing an XPath Expression. 4. Click resource, then select WSDL or XML schema. Depending on what you select, the WSDL Browser or XML Schema Browser is displayed. 6. To save the boolean result of this validation, select the radio button associated with this option and enter a variable in the Save result of validation in variable field. Alternatively, to raise an error if the element fails validation against the WSDL or XML schema element, select the Raise Error on validation failure radio button. Note: The Validate action enables you to validate Global elements only; AquaLogic Service Bus does not support validation against local elements. |
|
Populate context by specifying a service and operation, and enter context variables to bind to the invocation input and output parameters:
3. Select a service from the list, then click Submit. The service is displayed instead of the default link. Note: The service must have a WSDL with a SOAP or XML over HTTP or HTTPS binding without attachments. |
Click the appropriate request or response pipeline, then click Add Stage. To learn more, see Adding a Stage. |
|
Click the Start Node icon, then click Add Pipeline Pair. Alternatively, click an existing Pipeline Pair Node icon, click Add, then click Add Pipeline Pair. To learn more, see Adding a Pipeline Pair Node. |
|
Click the Pipeline Pair Node icon, click Add, then click Add Route Node. To learn more, see Adding a Route Node. |
|
Click the Pipeline Pair Node icon, click Add, then click Add Conditional Branch Node. To learn more, see Adding a Conditional Branch Node. |
|
Click the Start Node icon, then click Add Service Error Handler. To learn more, see Adding Error Handling for the Proxy Service. |
|
Click the Echo Node icon, then click Convert to Route Node. To learn more, see Adding a Route Node. |
|
Click the appropriate Stage icon, click Edit, then click Name and Description. |
|
Save the updates and return to the Summary of Proxy Services page |
|
Disregard changes and return to the Summary of Proxy Services page |
|
Note: When you click Save, the Message Flow is updated in the current session. When you have finished making changes to this configuration, from the left navigation pane, click Activate under Change Center. The session ends and the core configuration is updated. Alternatively, click Discard at any time during the session to delete the changes you have made so far in the current session.
Update actions include Delete, Rename, Insert, and Replace actions. They are evaluated and executed as follows:
Listing and Locating Proxy Services
Viewing and Changing Proxy Services
Viewing and Changing Message Flow
The Edit Message Flow page enables you to add a route node. The route node is used to perform one way communication, such as using file or email transport. It represents the boundary between request and response processing for the proxy service. When the route node dispatches a request message, request processing is considered finished. When the route node receives a response message, response processing begins. To learn more about Message Flow, see Overview of Message Flow.
AquaLogic Service Bus supports reliable messaging. When messages are routed to another service from a route node, the default quality of service (QoS) is exactly once if the proxy service transport is defines as JMS/XA; otherwise best effort QoS is supported. Exactly once reliability means that messages are delivered from inbound to outbound exactly once, assuming a terminating error does not occur before the outbound message send is initiated. The exactly once delivery reliability is a hint, not a directive. When exactly once is specified, exactly once reliability is provided if possible. If exactly once is not possible, then at least once delivery semantics are attempted; if that is not possible, best effort delivery is performed.
At least once semantics means the message is delivered to the outbound from the inbound at least once, assuming a terminating error does not occur before the outbound message send is initiated. Delivery is considered satisfied even if the target service responds with a transport-level error. However it is not satisfied in the case of a timeout, a failure to connect, or a broken communication link. If fail over URLs are specified, at least once semantics is provided with respect to at least one of the URLs.
Best effort means that there is no reliable messaging and there is no elimination of duplicate messages—however, performance is optimized.
To override the default exactly once quality of service attribute, you must set the qualityOfService
in the outbound message context variable ($outbound
). For more information, see Message Context Schema.
The Edit Message Flow page is displayed for the proxy service you selected. The page includes the following functionality:
The Route Node icon and the name you assigned to the route node are displayed on the Edit Message Flow page.
Table 14-37 Adding a Route Node
Click the Start Node icon, then click Add Pipeline Pair. To learn more, see Adding a Pipeline Pair Node. |
|
Click the Start Node icon, then click Add Service Error Handler. To learn more, see Adding Error Handling for the Proxy Service. |
|
Click the appropriate request or response pipeline, then click Add Stage. To learn more, see Adding a Stage. |
|
Click the Stage icon for the appropriate pipeline, then click Edit Stage. To learn more, see Adding an Action. |
|
Click the Route Node icon, click Edit, then click Name and Description. Note: When you rename a pipeline or a route node, the number of messages displayed on the Dashboard page in the Monitoring module may not correlate with those of other components due to the pipeline counters being reset to zero. This is because AquaLogic Service Bus treats the rename as a delete and recreate action. The numbers should correlate again after a time period equal to the service's monitoring interval has elapsed. |
|
Click the Route Node icon, click Edit, then click Route Node. |
|
Click the Route Node icon, then click Add Error Handler. To learn more, see Adding Error Handling for the Route Node. |
|
Save the updates and return to the Summary of Proxy Services page |
|
Disregard changes and return to the Summary of Proxy Services page |
|
Note: When you click Save, the Message Flow is updated in the current session. When you have finished making changes to this configuration, from the left navigation pane, click Activate under Change Center. The session ends and the core configuration is updated. Alternatively, click Discard at any time during the session to delete the changes you have made so far in the current session.
Listing and Locating Proxy Services
Viewing and Changing Proxy Services
Viewing and Changing Message Flow
Modeling Message Flow in AquaLogic Service Bus in the BEA AquaLogic Service Bus User Guide.
The Edit Stage Configuration page enables you to add route node actions when you click Edit, then click Route Node on the Edit Message Flow page. Route node actions define the handling of messages as they flow through the route node of the proxy service. To learn more about Message Flow, see Overview of Message Flow.
Note: To learn more about actions, see Modeling Message Flow in AquaLogic Service Bus in the BEA AquaLogic Service Bus User Guide for usage scenarios, design patterns, and best practices.
Table 14-38 Adding Route Node Actions
Assign if then else actions based on the Boolean result of an XQuery expression: Note: Condition actions can be nested. However, there is a nesting limit of 4 cumulative levels in the stage editor. If you attempt to add a 5th level, this nesting action is not displayed. Cumulative levels include all branching actions: If... Then... Conditions, Publish Tables, and Route Tables. For example, you can have 2 levels of conditionals, then a publish table with a route table inside of it, bringing the total to 4 levels. If you attempt to add another conditional (to the last publish table), the conditional is not displayed.
2. Click Condition. The Edit an XQuery Condition page is displayed. To learn more, see Editing an XQuery Condition. 3. When you have finished editing the XQuery condition, click Add an Action, then select an action that you want to associate with the condition. Note: In the route node, you can select the Routing or Routing Table actions only. To learn more about these actions, see the appropriate procedure in this table. However, these actions can contain request and response actions inside of them. To learn more, see the table of actions in Adding an Action. |
|
Note: This is a terminal action, which means you cannot add another action after this one. However, this action can contain request and response actions inside of it. Identify a target service for the message and configure how the message is routed to that service:
3. Select a service from the list, then click Submit. The service is displayed instead of the default link. 4. In the Request Actions field, click Add an Action to add an action, then select an action that you want to associate with the service. You can add more than one action. To learn more about the type of actions you want to add, see the table of actions in Adding an Action. 5. In the Response Actions field, click Add an Action to add an action, then select an action that you want to associate with the service. You can add more than one action. To learn more about the type of actions you want to add, see the table of actions in Adding an Action. |
|
Note: This is a terminal action, which means you cannot add another action after this one. However, this action can contain request and response actions inside of it. A routing table is a set of routes wrapped in a switch-style condition table. It is a short-hand construct that allows different routes to be selected based upon the results of a single XQuery expression. There is a nesting limit of 4 cumulative levels in the stage editor. If you attempt to add a 5th level, this nesting action is not displayed. Cumulative levels include all branching actions: If... Then... Conditions, Publish Tables, and Route Tables. For example, you can have 2 levels of conditionals, then a publish table with a route table inside of it, bringing the total to 4 levels. If you attempt to add another conditional (to the last publish table), the conditional is not displayed. Identify target services for messages and configure how the messages are routed to these services: 1. Click Add an Action, then select Routing Table. The Routing Table action is displayed, which includes the following functionality:
2. Select one of these comparison operators: =, !=, < , >, <=, or >=, then enter a value expression in the field provided. 5. In the Request Actions field, click Add an Action to add an action, then select an action that you want to associate with the service. You can add more than one action. 6. In the Response Actions field, click Add an Action to add an action, then select an action that you want to associate with the service. You can add more than one action. Note: To learn more about the types of request and response actions you want to add, see the table of actions in Adding an Action. |
Table 14-39 Adding Route Node Actions
Table 14-40 Adding Route Node Actions
Click the Route Node icon, click Edit, then click Name and Description. |
|
Click the Route Node icon, then click Add Error Handler. To learn more, see Adding Error Handling for the Route Node. |
|
Save the updates and return to the Summary of Proxy Services page |
|
Disregard changes and return to the Summary of Proxy Services page |
|
Note: When you click Save, the Message Flow is updated in the current session. When you have finished making changes to this configuration, from the left navigation pane, click Activate under Change Center. The session ends and the core configuration is updated. Alternatively, click Discard at any time during the session to delete the changes you have made so far in the current session.
Listing and Locating Proxy Services
Viewing and Changing Proxy Services
Viewing and Changing Message Flow
The Edit Branch Node page enables you to view and change conditional branch details. To learn more about branch nodes, see Adding a Conditional Branch Node and Overview of Message Flow.
Note: If you want to edit an operational branch, see Viewing and Changing Operational Branch Details.
The Edit Message Flow page is displayed for the proxy service you selected. The page includes the following functionality:
Table 14-41 Branch Configuration Fields and Branch Definitions
Click Edit. To learn more, see Editing an XPath Expression. |
|
Click Add a New Branch from the flyout menu of the Options column. |
|
Click Delete this Branch from the flyout menu of the Options column. |
|
Click Move Branch Down from the flyout menu of the Options column. Note: This option displays only when more than one branch definition exists. |
|
Click Move Branch Up from the flyout menu of the Options column. Note: This option displays only when more than one branch definition exists. |
Note: When you click Save, the Message Flow is updated in the current session. When you have finished making changes to this configuration, from the left navigation pane, click Activate under Change Center. The session ends and the core configuration is updated. Alternatively, click Discard at any time during the session to delete the changes you have made so far in the current session.
Listing and Locating Proxy Services
Viewing and Changing Proxy Services
Viewing and Changing Message Flow
The Edit Branch Node page enables you to view and change operational branch details. To learn more about operational branches, see Adding an Operational Branch Node and Overview of Message Flow.
The Edit Message Flow page is displayed for the proxy service you selected. The page includes the following functionality:
Table 14-42 Branch Configuration Fields and Branch Definitions
Note: When you click Save, the Message Flow is updated in the current session. When you have finished making changes to this configuration, from the left navigation pane, click Activate under Change Center. The session ends and the core configuration is updated. Alternatively, click Discard at any time during the session to delete the changes you have made so far in the current session.
step in Service Types and Transports
Listing and Locating Proxy Services
Viewing and Changing Proxy Services
Viewing and Changing Message Flow
The Edit Stage Configuration page enables you to edit a stage. To learn more about stages, see Adding a Stage, Adding an Action, and Overview of Message Flow.
The Edit Message Flow page is displayed for the proxy service you selected. The page includes the following attributes:
Table 14-43 Edit Stage Configuration Page
Click Add an Action, then select the appropriate action. To learn more, see Adding an Action. |
|
Click the expression you want to edit. To learn more, see Editing an XQuery Expression. |
|
Click the expression you want to edit. To learn more, see Editing an XPath Expression. |
|
Click the condition you want to edit. To learn more, see Editing an XQuery Condition. |
Note: When you click Save, the Message Flow is updated in the current session. When you have finished making changes to this configuration, from the left navigation pane, click Activate under Change Center. The session ends and the core configuration is updated. Alternatively, click Discard at any time during the session to delete the changes you have made so far in the current session.
Listing and Locating Proxy Services
Viewing and Changing Proxy Services
Viewing and Changing Message Flow
The Edit an XQuery Condition page enables you to add or edit an XQuery condition. You can access this page through the Message Flow of a proxy service. To learn more about Message Flow, see Overview of Message Flow.
Table 14-44 Edit an XQuery Condition Page
1. In the Message Context Variables panel, select one of these context variable types from the drop-down list: 2. Click the displayed name to make the variable appear in the XPath field of the Message Context Variables panel. Note: The displayed names are a tree view that may be expanded to reveal sub elements that may in turn be selected. |
|
To learn more, see Defining a New Message Context Variable. |
|
1. In the Namespace Definitions panel, click the + for User Namespaces. The New Namespace Declaration dialog box is displayed. Note: An XML namespace is a way of making the element and attribute names globally unique. You qualify the element and attribute names, which are local names, with the namespace prefix to achieve this uniqueness. |
|
In the Namespace Definitions panel, click the - (minus sign) that corresponds to the user namespace you want to delete. |
|
Note: To build the condition, you can drag XQuery functions from the XQuery Functions Palette, or you can drag message context variables from the Message Context Variables Panel, and drop them in the Edit an XQuery Condition field. You can also add predefined default namespaces, variable namespaces, and user-defined namespaces, which are listed in the Namespace Definitions panel.
|
|
Enter a comparison expression using the Condition Builder option |
Note: To build the expression, you can drag XQuery functions from the XQuery Functions Palette, and drop them in the Edit an XQuery Transformation field. You can also add predefined default namespaces, variable namespaces, and user-defined namespaces, which are listed in the Namespace Definitions panel. Note: You must enter the text in quotations—that is, enter "true", not true. 7. Repeat steps 2-6 to build additional conditions. Each condition is added to the end of the list of conditions. Note: When you build additional expressions, make sure to select the and or the or options. Note: You can select a condition and click Remove to delete it, click Up to move it up the list of conditions, click Down to move it down the list of conditions, and click Update to update it.
|
Note: To build the expression, you can drag XQuery functions from the XQuery Functions Palette, and drop them in the Edit an XQuery Transformation field. You can also add predefined default namespaces, variable namespaces, and user-defined namespaces, which are listed in the Namespace Definitions panel. 5. Repeat steps 2-6 to build additional conditions. Each condition is added to the end of the list of conditions. Note: When you build additional expressions, make sure to select the and or the or options. Note: You can select a condition and click Remove to delete it, click Up to move it up the list of conditions, click Down to move it down the list of conditions, and click Update to update it. Note: Unary expressions may be intermixed with Comparison expressions in the overall definition of a condition.
|
Note: When you click Submit, the Message Flow is updated in the current session. When you have finished making changes to this configuration, from the left navigation pane, click Activate under Change Center. The session ends and the core configuration is updated. Alternatively, click Discard at any time during the session to delete the changes you have made so far in the current session.
Listing and Locating Proxy Services
Viewing and Changing Proxy Services
Viewing and Changing Message Flow
The Edit an XQuery Expression page enables you to add or change an XQuery expression. You can access this page through the Message Flow of a proxy service. To learn more about Message Flow, see Overview of Message Flow.
Note: The XQuery and XPath editors allow you to declare a variable's structure by mapping it to a type or element and then creating path expressions with a drag and drop action from the graphical representation of the structure. This is an ease-of-use feature. You can also enter the path expressions manually instead.
You can use this feature directly for all user-defined variables, as well as $inbound, $outbound, and $fault. However, you cannot use it directly to access XML attachments in $attachments, headers in $header, or documents and RPC parameters in $body, with one exception— you can use it directly to access documents and parameters in $body for request messages received by a WSDL proxy service.
Table 14-45 Edit an XQuery Expression Page
1. In the Message Context Variables panel, select one of these context variable types from the drop-down list: 2. Click the displayed name to make the variable appear in the XPath field of the Message Context Variables panel. Note: The displayed names are a tree view that may be expanded to reveal sub elements that may in turn be selected. |
|
To learn more, see Defining a New Message Context Variable. |
|
1. In the Namespace Definitions panel, click the + for User Namespaces. The New Namespace Declaration dialog box is displayed. Note: An XML namespace is a way of making the element and attribute names globally unique. You qualify the element and attribute names, which are local names, with the namespace prefix to achieve this uniqueness. |
|
In the Namespace Definitions panel, click the - (minus sign) that corresponds to the user namespace you want to delete. |
|
Note: To build the expression, you can drag XQuery functions from the XQuery Functions Palette, and drop them in the Edit an XQuery Transformation field. You can also add predefined default namespaces, variable namespaces, and user-defined namespaces, which are listed in the Namespace Definitions panel.
|
|
2. In the Select the Transformation to execute field, select the XQuery Transformation you want to execute, then click Select. 3. Under the Variable Mapping field, a label and a corresponding text box that you can scroll to see each input parameter of the transformation are displayed. Each label corresponds to the name of a parameter, and each text box is for defining an XQuery expression to be mapped to the parameter. You must define a mapping for each parameter. For example, if an XQuery transformation has two input parameters named one and two, the Variable Mapping field has two labels—one and two. A text box, into which the XQuery expression is entered, is associated with each label. Note: The following variable name is not a valid entry for this field and results in an exception:
|
|
2. In the Select the XSL transformation to execute field, select the XSL Transformation you want to execute, then click Select. 3. Under the Variable Mapping field, a label and a corresponding text box is displayed for each input parameter of the transformation. Each label corresponds to the name of a parameter, and each text box is for defining an XQuery expression to be mapped to the parameter. You must define a mapping for each parameter. For example, if an XSL transformation has two input parameters named one and two, the Variable Mapping field has two labels—one and two—with a text box associated with each into which the XQuery expression is entered. In addition to the mapping for any input variables, you must also specify an XQuery expression for the Input Document to the transformation. The mapping is specified in the text box with the label Input Document. Note: The following variable name is not a valid entry for this field and results in an exception:
|
Note: When you click Submit, the Message Flow is updated in the current session. When you have finished making changes to this configuration, from the left navigation pane, click Activate under Change Center. The session ends and the core configuration is updated. Alternatively, click Discard at any time during the session to delete the changes you have made so far in the current session.
Listing and Locating Proxy Services
Viewing and Changing Proxy Services
Viewing and Changing Message Flow
The Edit an XPath Expression page enables you to edit an XPath expression. You can access this page through the Message Flow of a proxy service. To learn more about Message Flow, see Overview of Message Flow.
Note: The XQuery and XPath editors allow you to declare a variable's structure by mapping it to a type or element and then creating path expressions with a drag and drop action from the graphical representation of the structure. This is an ease-of-use feature. You can also enter the path expressions manually instead.
You can use this feature directly for all user-defined variables, as well as $inbound, $outbound, and $fault. However, you cannot use it directly to access XML attachments in $attachments, headers in $header, or documents and RPC parameters in $body, with one exception— you can use it directly to access documents and parameters in $body for request messages received by a WSDL proxy service.
Table 14-46 Edit an XPath Expression Page
1. In the Message Context Variables panel, select one of these context variable types from the drop-down list: attachments, header, outbound, body, or inbound. To learn more about message context variables, see Message Context. 2. Click the displayed name to make the variable appear in the XPath field of the Message Context Variables panel. Note: The displayed names are a tree view that may be expanded to reveal sub elements that may in turn be selected. |
|
To learn more, see Defining a New Message Context Variable. |
|
1. In the Namespace Definitions panel, click the + for User Namespaces. The New Namespace Declaration dialog box is displayed. Note: An XML namespace is a way of making the element and attribute names globally unique. You qualify the element and attribute names, which are local names, with the namespace prefix to achieve this uniqueness. |
|
In the Namespace Definitions panel, click the - (minus sign) that corresponds to the user namespace you want to delete. |
|
Note: To build the expression, you can drag context variables from the Message Context Variables Panel, and drop them in the Edit an XPath Expression field. You can also add predefined default namespaces, variable namespaces, and user-defined namespaces, which are listed in the Namespace Definitions panel.
|
Note: When you click Submit, the Message Flow is updated in the current session. When you have finished making changes to this configuration, from the left navigation pane, click Activate under Change Center. The session ends and the core configuration is updated. Alternatively, click Discard at any time during the session to delete the changes you have made so far in the current session.
Listing and Locating Proxy Services
Viewing and Changing Proxy Services
Viewing and Changing Message Flow
The Define a New Message Context Variable page enables you to define a new message context variable type. You can access this page from the Edit an XQuery Expression, Edit an XPath Expression, or Edit an XQuery Condition pages. To learn more, see Editing an XQuery Expression, Editing an XPath Expression, or Editing an XQuery Condition.
Note: You can click Browse and use the appropriate Browser to select an XML Schema, WSDL, or MFL, then click Submit.
Viewing and Changing Message Flow
This section includes the following topics:
BEA AquaLogic Service Bus enables you to configure your system to format and return error messages.
Errors can occur during Message Flow processing for various reasons. For example, security errors occur if a username is not correctly validated or authorized; transformation errors occur if AquaLogic Service Bus is unable to successfully transform or validate a message; a routing error is raised if a routing service is unavailable, and so on. Typically, these errors originate from a specific stage, route node or from the proxy service, as this is where most of the Message Flow logic is implemented.
AquaLogic Service Bus provides a mechanism to handle these errors by enabling you to define error handlers. An error handler is a pipeline that allows you to perform various actions such as logging, transformation, and publishing to handle errors appropriately.
If an error occurs within a stage a sequence of steps are executed. This sequence of steps constitutes an error pipeline for that stage.
You can configure an error handler for the entire Message Flow as well as for every pipeline and stage within the Message Flow. You may also configure error handlers for route nodes but not for branch nodes.
When an error occurs, it is handled by the inner-most encompassing error handler. For example, a stage's error handler handles a transformation error if it occurs while executing the assign action in that stage. If there is no error handler configured for the stage, it is handled by the next level error handler, which is that of the pipeline that contains the transformation stage. If that error handler does not exist, it is then handled by the Message Flow-level error handler. If that fails, then a default system-level error handler processes the error.
The next level error handler for uncaught errors that occur in a route node is the Message Flow-level handler. Thus, unlike stage errors which can be handled at 3 levels by user-configured handlers, Message Flow errors can only be caught by at most 2 levels of user-configured handlers.
Every component—stage, pipeline or Message Flow—can have at most 1 error handler. Therefore, only 1 Message Flow-level error handler is used to process any error that occurs during either request or response processing (that is not handled at a lower level by a pipeline or stage error handler). Since the inbound binding layer is not associated with any particular stage or pipeline, errors that occur in the binding layer are always handled by the Message Flow-level error handler. Outbound binding layer errors may occur in several places, depending on what entity is performing communication. For example, binding layer errors that occur during routing can be caught by the routing node's error handler. Similarly, binding layer errors that occur during a publish operation in a publish stage can be caught by the stage-level error handler.
An empty or unconfigured error handler is identical to not having an error handler. For example, if the stage-level error handler was created but never configured, then the error bubbles-up to the next level handler.
When an error handler processes an error, it can finish with one of two actions:
Table 14-47 Error Handler Actions
If neither the Reply nor the Resume action is initiated, the error is rethrown. In this case, the error is pushed forward and handled by the next level error handler. Unless otherwise specified, the rethrow action is the default action of an error handler.
To learn how Message Flow chooses among these actions, see Error Handler Configuration.
Since an error handler is another pipeline, it is configured like any other pipeline. For example, the Publish action may be used to send error notifications to other services, the Assign action may be used to modify the context variables, and so on. Some actions, however, are not allowed to appear in an error handler.
In addition to the standard context variables, there is an additional context variable available to an error handler—the $fault
variable. The $fault
variable contains information about any error that occurs during Message Flow processing. When an error occurs, this variable is populated with information about the error, prior to the error-handler being invoked. The $fault
variable is only ever defined within error handlers. It is never defined within a simple request and response pipeline. This is the key difference between an error pipeline and any other pipeline.
There are four core elements within the $fault
variable:
Table 14-48 Error Handler Configuration
You can modify the $fault variable; however it is only relevant inside an error handler.
Listing and Locating Proxy Services
Viewing and Changing Proxy Services
Viewing and Changing Message Flow
The Edit Message Flow page enables you to add error handling for the proxy service. You can configure error handling at the Message Flow, pipeline, route node, and stage level. To learn more, see Error Messages and Handling.
The Edit Message Flow page is displayed for the proxy service you selected. The page includes the following functionality:
Since an error handler is another pipeline, it is configured like any other pipeline. For example, the Publish action may be used to send error notifications to other services, the Assign action may be used to modify the context variables, and so on. To learn more about the type of action you want to add, see the appropriate procedure in Adding an Action. There is no restriction on what actions may be chained together.
In addition, three commonly-used error actions are Raise Error, Reply, and Resume. To learn more about these actions, see Error Handler Actions in Error Messages and Handling.
When you have finished adding actions, continue to the next step.
Table 14-49 Adding Proxy Service Error Handling
Click the Stage icon, click Edit, then click Name and Description. |
|
Select the Error Handler or Stage icon, then click Add Stage. |
|
Note: When you click Save, the Message Flow is updated in the current session. When you have finished making changes to this configuration, from the left navigation pane, click Activate under Change Center. The session ends and the core configuration is updated. Alternatively, click Discard at any time during the session to delete the changes you have made so far in the current session.
Adding Pipeline Error Handling
Adding Error Handling for the Route Node
Viewing and Changing Message Flow
The Edit Message Flow page enables you to add error handling for a pipeline. You can configure error handling at the Message Flow, pipeline, route node, and stage level. To learn more, see Error Messages and Handling.
Note: You must create a pipeline pair node before you can add a pipeline error handler. To learn more, see Adding a Pipeline Pair Node.
Since an error handler is another pipeline, it is configured like any other pipeline. For example, the Publish action may be used to send error notifications to other services, the Assign action may be used to modify the context variables, and so on. To learn more about the type of action you want to add, see the appropriate procedure in Adding an Action. There is no restriction on what actions may be chained together.
In addition, three commonly-used error actions are Raise Error, Reply, and Resume. To learn more about these actions, see Error Handler Actions in Error Messages and Handling.
When you have finished adding actions, continue to the next step.
Table 14-50 Adding Pipeline Error Handling
Click the Stage icon, click Edit, then click Name and Description. |
|
Select the Error Handler or Stage icon, then click Add Stage. |
|
Note: When you click Save, the Message Flow is updated in the current session. When you have finished making changes to this configuration, from the left navigation pane, click Activate under Change Center. The session ends and the core configuration is updated. Alternatively, click Discard at any time during the session to delete the changes you have made so far in the current session.
Adding Error Handling for the Proxy Service
Adding Error Handling for the Route Node
Viewing and Changing Message Flow
The Edit Message Flow page enables you to add error handling for a stage. You can configure error handling at the Message Flow, pipeline, route node, and stage level. To learn more, see Error Messages and Handling.
Note: You must create a stage before you can add a stage error handler. To learn more, see Adding a Stage.
Since an error handler is another pipeline, it is configured like any other pipeline. For example, the Publish action may be used to send error notifications to other services, the Assign action may be used to modify the context variables, and so on. To learn more about the type of action you want to add, see the appropriate procedure in Adding an Action. There is no restriction on what actions may be chained together.
In addition, three commonly-used error actions are Raise Error, Reply, and Resume. To learn more about these actions, see Error Handler Actions in Error Messages and Handling.
When you have finished adding actions, continue to the next step.
Table 14-51 Adding Stage Error Handling
Click the Stage icon, click Edit, then click Name and Description. |
|
Select the Error Handler or Stage icon, then click Add Stage. |
|
Note: When you click Save, the Message Flow is updated in the current session. When you have finished making changes to this configuration, from the left navigation pane, click Activate under Change Center. The session ends and the core configuration is updated. Alternatively, click Discard at any time during the session to delete the changes you have made so far in the current session.
Adding Error Handling for the Proxy Service
Adding Pipeline Error Handling
Adding Error Handling for the Route Node
Viewing and Changing Message Flow
The Edit Message Flow page enables you to add error handling for a route node. You can configure error handling at the Message Flow, pipeline, route node, and stage level. To learn more, see Error Messages and Handling.
Note: You must create a route node before you can add a route node error handler. To learn more, see Adding a Route Node.
Since an error handler is another pipeline, it is configured like any other pipeline. For example, the Publish action may be used to send error notifications to other services, the Assign action may be used to modify the context variables, and so on. To learn more about the type of action you want to add, see the appropriate procedure in Adding an Action. There is no restriction on what actions may be chained together.
In addition, three commonly-used error actions are Raise Error, Reply, and Resume. To learn more about these actions, see Error Handler Actions in Error Messages and Handling.
When you have finished adding actions, continue to the next step.
Table 14-52 Adding Route Node Error Handling
Click the Stage icon, click Edit, then click Name and Description. |
|
Select the Error Handler or Stage icon, then click Add Stage. |
|
Note: When you click Save, the Message Flow is updated in the current session. When you have finished making changes to this configuration, from the left navigation pane, click Activate under Change Center. The session ends and the core configuration is updated. Alternatively, click Discard at any time during the session to delete the changes you have made so far in the current session.
Adding Error Handling for the Proxy Service
Adding Pipeline Error Handling
Viewing and Changing Message Flow
The Edit Message Flow page enables you to view and change error handlers. You can configure error handling at the Message Flow, pipeline, route node, and stage level. To learn more, see Error Messages and Handling.
Table 14-53 Viewing and Changing the Error Handler
Click the Start Node icon, then click Edit Service Error Handler. The Edit Error Handler page is displayed. To learn more, see Adding Error Handling for the Proxy Service. |
|
Click the appropriate Pipeline Pair icon, then click Edit Pipeline Error Handler. The Edit Error Handler page is displayed. To learn more, see Adding Pipeline Error Handling. |
|
Click the Route Node icon, click Edit, then click Error Handler. The Edit Error Handler page is displayed. To learn more, see Adding Error Handling for the Route Node. |
|
Click the appropriate Stage icon, click Edit, then Stage Error Handler. The Edit Error Handler page is displayed. To learn more, see Adding Stage Error Handling. |
Viewing and Changing Message Flow
The Edit Message Flow page enables you to delete existing error handlers. You can configure error handling at the Message Flow, pipeline, route node, and stage level. To learn more, see Error Messages and Handling.
Table 14-54 Deleting the Error Handler
Note: When you click Delete, the Message Flow is updated in the current session. When you have finished making changes to this configuration, from the left navigation pane, click Activate under Change Center. The session ends and the core configuration is updated. Alternatively, click Discard at any time during the session to delete the changes you have made so far in the current session.
Viewing and Changing Message Flow
Adding Error Handling for the Proxy Service
Adding Pipeline Error Handling
Adding Error Handling for the Route Node
![]() ![]() |
![]() |
![]() |