Understanding the basic need of Service Oriented Architecture and getting started with Oracle Service Bus
Download as DOCX, PDF2 likes765 views
The document provides an overview of service-oriented architecture (SOA) and various integration architectures, discussing their features, advantages, and disadvantages. It emphasizes the significance of a well-defined integration architecture for efficient business processes and how SOA improves upon traditional methods by allowing loosely coupled applications to work together seamlessly. Key terms such as XML, WSDL, and hub and spoke architecture are also explained to enhance understanding of the technical aspects of integrating services.
![throws an exception, which in turn causes the pipeline to raise an error. T he fault variable in a user -configured error handler is
bound to a message formatted similarly to that shown in Listing 3-11.
Listing 3-11 Contents of the Oracle Service Bus fault Variable—Transport Error, no Error Response Payload
<con:fault xmlns:con=”http://www.bea.com/wli/sb/context”>
<con:errorC ode>BEA-380000</con:errorCode>
<con:reason>Not Found</con:reason>
<con:details>
…….
</con:details>
<con:location>
<con:node>P ipelinePairNode1</con:node>
<con:P ipeline>P ipelinePairNode1_request</con:Pipeline>
<con:Stage>Stage1</con:Stage>
</con:location>
</con:fault>
In the case that there is a payload associated with the transport error—for example, when an HT TP 500 error code is received
from the business service and there is XML payload in the response —a message context fault is generated with the custom
error code: BEA -382502.
T he following conditions must be met for a BEA -382502 error response code to be triggered as the result of a response from a
service—when that service uses an HT TP or JM S transport:
(HT TP) T he response code must be any code other than 200 or 202.
(JM S) T he response must have a property set to indicate that it is an error response—the transport metadata status code set
to1 indicates an error.
T he content type must be text/xml.
If the service is AnySoap or WSDL -based SOAP, then it must have a SO AP envelope. T he body inside the SOAP envelope must
be XM L format; it cannot be text.
If the service type is AnyXML, or a messaging service of type text returns XML content with a non -successful response code
(any code other than 200 or 202).
If the transport is HTTP, the ErrorResponseDetail element will also conta in the HTTP error code returned with the response.
T he ErrorResponseDetail element in the fault contains error response payload received from the service. Listing 3-12 shows an
example of the ErrorResponseDetail element.
Listing 3-12 Contents of the Oracle Service Bus fault Variable—Transport Error, with Error Response Payload
<ctx:Fault xmlns:ctx=”http://www.bea.com/wli/sb/context”>
<ctx:errorC ode>BEA-382502<ctx:errorCode>
<ctx:reason> Service callout has received an error response from the server</ctx:reason>
<ctx:details>
<alsb:ErrorResponseDetail xmlns:alsb=”http://www.oracle.com/…”>
<alsb:detail> <! [C DATA[
. . .
]]>
</alsb:detail> <alsb:http-response-code>500</alsb:http-response-code>
</alsb:ErrorResponseDetail>
</ctx:details>
<ctx:location>. . .</ctx:location>
</ctx:Fault>
Note: T he XM L schema for the service callout-generated fault is shown in XM L Schema for the Service C allout-Generated
Fault Details.
8.22. SOAP Faults
In case an external service returns a SOAP fault, the O racle Service Bus run time sets up the context variable $fault with a
custom error code and description with the details of the fault. T o do so, the contents of the 3 elements under the <SOAP-
ENV:Fault> element in the SO AP fault are extracted and used to construct an O racle Service Bus fault element.
T ake for example a scenario in which a service returns the following error.
Listing 3-13 SOAP Fault Returned From Service Callout
<SO AP-ENV:Envelope xmlns:SOAP-ENV=”http://schemas.xmlsoap.org/soap/envelope/”>
<SO AP-ENV:Body>
<SO AP-ENV:Fault>
<faultcode>SOAP-ENV:Client</faultcode>
<faultstring>Application Error</faultstring>
<detail>
<message>That’s an Error!</message>
<errorcode>1006</errorcode>
</detail>
</SO A P-ENV:Fault>](https://image.slidesharecdn.com/soawithosbshaan-150603043608-lva1-app6891/85/Understanding-the-basic-need-of-Service-Oriented-Architecture-and-getting-started-with-Oracle-Service-Bus-21-320.jpg)
![ <ctx: route>
<ctx: service isProxy=’false’> {$routingtable/row[logical/text()=$logicalidentifier]/physical/text()}
</ctx: service>
</ctx: route>
In the above code, replace $logicalidentifier by the actual XPath to extract the logical identifier from the mes sage (example
from $body).
C lick on V alidate to validate the Xquery.
Save the Xquery on successful validation.
O n the Edit Stage C onfiguration page, enter the name of the variable (for example, routeresult) in the field.
T his extracts the XM L used by the dynamic route action into this variable.
C lick on the message flow to add a route node to the end of the message flow.
C lick on the Route Node icon and select Edit from the menu.
C lick the A dd Action icon. C hoose Add an A ction item from the menu.
C hoose the Dynamic Route action.
C lick on Expression. T he XQuery Expression Editor is displayed.
Enter the variable from step 22 (for example, $routeresult)
O racle Service Bus provides read-access to databases from proxy services without requiring you to write a custom EJB or
custom Java code and without the need for a separate database product like Oraclce Data Service Integrator. Y ou can use the
execute-sql() function to make a simple JDBC call to a database to perform simple database reads. A ny SQL query is legal,
from a query that gets a single tax rate for the supplied location to a query that does a complex join to obtain an order’s
current status from several underlying database tables.
A database query can be used to get data for message enrichment, for routing decisions, or for customizing the behavior of a
proxy service. T ake for example a scenario in which an O racle Service Bus proxy service receives “request for quote”
messages. T he proxy service can route the requests based on the customer’s priority to one of a number of quotation business
services (say, standard, gold, or platinum level services). T he proxy service can then perform a SQ L-based augmentation of
the results that those services return—for example, based on the selected ship method and the weight of the order, the
shipping cost can be looked up and that cost added to the request for quote message.
fn-bea:execute-sql() describes the syntax for the function and provides examples of its use. T he execute -sql() function returns
typed data and automatically translates values between SQL/JDBC and XQ uery data models.
Y ou can store the returned element in a user-defined variable in an O racle Service Bus message flow.
T he following databases and JDBC drivers are supported using the execute-sql() function:
IBM DB2/NT 8
M icrosoft SQL Server 2000, 2005
O racle 8.1.x
O racle 9.x, 10.x
P ointbase 4.4, 5.x
Sybase 12.5.2 and 12.5.3
WebLogic T ype 4 JDBC drivers
T hird-party drivers supported by WebLogic Server
U se non-XA drivers for datasources you use with the fn-bea:execute-sql() function—the function supports read-only access to
the datasources.
WARNING:
In addition to specifying a non-XA JDBC driver class to use to connect to the database, you must ensure that you disable global
transactions and two-phase commit. (Global transactions are enabled by default in the WebLogic Server console for JDBC data
sources.) T hese specifications can be made for your data source via the WebLogic Server A dministration C onsole. See C reate
JDBC Data Sources in the WebLogic Server Administration Console Online Help.
For complete information about database and JDBC drivers support in O racle Service Bus, see Supported Database
C onfigurations in Supported Configurations for Oracle Service Bus .
Databases other than the core set described in the preceding listing are also supported. However, for the core databases list ed
above, the XQ uery engine does a better recognition and mapping of data types to XQ uery types than it does for the non-core
databases—in some cases, a core database’s proprietary JDBC extensions are used when fetching data. For the non -core
databases, the XQ uery engine relies totally on the standard type codes provided by the JDBC driver and standard JDBC
resultset access methods.
When designing your proxy service, you can enter XQ ueries inline as part of an action definition instead of entering them as
resources. Y ou can also use inline XQueries for conditions in If…T hen… actions in message flows. For information about using
the inline XQ uery editor, seeCreating Variable Structure M appings.
T he message context is a set of variables that hold message context and information about messages as they are routed
through the O racle Service Bus. T ogether, the header, body, and attachments variables, (referenced as $header, $body and
$attachments in XQuery statements) represent the message as it flows through O racle Service Bus. T he canonical form of the
message is SOAP. Even if the service type is not SOAP, the message appears as SOAP in the O racle Service Bus message
context.
In a M essage C ontext, $header contains a SOAP header element and $body contains a SOAP Body element. T he Header and
Body elements are qualified by the SOAP 1.1 or SOAP 1.2 namespace depending on the service type of the proxy service. A lso](https://image.slidesharecdn.com/soawithosbshaan-150603043608-lva1-app6891/85/Understanding-the-basic-need-of-Service-Oriented-Architecture-and-getting-started-with-Oracle-Service-Bus-26-320.jpg)
![in a M essage C ontext, $attachments contains a wrapper element called attachments with one child attachment element per
attachment. T he attachment element has a body element with the actual attachment.
When a message is received by a proxy service, the message contents are used to initialize the header, body, and attachments
variables. For SOAP services, the Header and Body elements are taken directly from the envelope of the received SOAP
message and assigned to $header and $body respectively. For non-SOAP services, the entire content of the message is
typically wrapped in a Body element (qualified by the SOAP 1.1 namespace) and assigned to $body, and an empty Header
element (qualified by the SO AP 1.1 namespace) is assigned to $header.
Binary and M FL messages are initialized differently. For M FL messages, the equivalent XML document is inserted into the Body
element that is assigned to $body. For binary messages, the message data is stored internally and a piece of reference XML is
inserted into the Body element that is assigned to $body. T he reference XML looks like <binary-content ref=”…”/>, where “…”
contains a unique identifier assigned by the proxy service.
T he message context is defined by an XM L schema. Y ou must use XQuery expressions to manipulate the context variables in
the message flow that defines a proxy service.
T he predefined context variables provided by O racle Service Bus can be grouped into the following types:
M essage-related variables
Inbound and outbound variables
O peration variable
Fault variable
For information about the predefined context variables, see P redefined C ontext Variables.
T he $body contains message payload variable. When a message is dispatched from O racle Service Bus you can decide the
variables, whose you want to include in the outgoing message. T hat determination is dependent upon whether the target
endpoint is expecting a SO AP or a non-SOAP message:
For a binary, any text or XM L message content inside the Body element in $body is sent.
For M FL messages, the Body element in $body contains the XM L equivalent of the M FL document.
For text messages, the Body element in $body contains the text. For text attachments, the body element in $attachments
contains the text. If the contents are XM L instead of simple text, the XM L is sent as a text message.
For XM L messages, the Body element in $body contains the XM L. For XM L attachments, the body element in $attachments
contains the XM L.
SO AP messages are constructed by wrapping the contents of the header and body variables inside a <soap:Envelope>
element. (T he SOAP 1.1 namespace is used for SO AP 1.1 services, while the SO AP 1.2 namespace is used for SO AP 1.2
services.) If the body variable contains a piece of reference XML, it is sent.T hat is the referenced content is not substituted in
the message.
For non-SOAP services, if the Body element of $body contains a binary -content element, then the referenced content stored
internally is sent ‘as is’, regardless of the target service type.
For more information, see M essage C ontext.
T he types for the message context variables are defined by the message context schema (M essageContext.xsd). When working
with the message context variables in the O racle XQuery M apper, you need to reference M essageContext.xsd, which is
available in a JA R file, O RACLE_HOME/osb_10.3/lib/sb-schemas.jar, and the transport-specific schemas, which are available at
O RACLE_HOME/osb_10.3/lib/transports/
where O RACLE_HOME represents the directory in which you installed O racle Service Bus.
T o learn about the message context schema and the transport specific schemas, see M essage C ontext Schema.
C onsider the following guidelines when you want to inspect or alter the message context:
In an XQ uery expression, the root element in a variable is not present in the path in a reference to an element in that variable.
For example, the following XQ uery expression obtains the C ontent-Description of the first attachment in a message:
$attachments/ctx:attachment[1]/ctx:content-Description
T o obtain the second attachment
$attachments/ctx:attachment[2]/ctx:body/*
A context variable can be empty or it can contain a single XML element or a string value. However, an XQ uery expression often
returns a sequence. When you use an XQ uery expression to assign a value to a variable, only the first element in the sequence
returned by the expression is stored as the variable value. For example, if you want to assign the value of a WS -A ddressing
M essage ID from a SO AP header (assuming there is one in the header) to a variable named idvar, the assign action
specification is:
assign data($header/wsa:messageID to variable idvar
Note:
In this case, if two WS-A ddressing M essageID headers exist, the idvar variable will be assigned the value of the first one.
T he variables $header, $body, and $attachments are never empty. However, $header can contain an empty SOAP Header
element, $body can contain an empty SOAP Body element, and $attachments can contain an empty attachment element.
In cases in which you use a transformation resource (XSLT or XQuery), the transformation resource is defined to transform the
document in the SO AP body of a message. T o make this transformation case easy and efficient, the input p arameter to the
transformation can be an XQ uery expression. For example, you can use the following XQuery expression to feed the business
document in the Body element of a message ($body) as input to a transformation:
$body/* [1]](https://image.slidesharecdn.com/soawithosbshaan-150603043608-lva1-app6891/85/Understanding-the-basic-need-of-Service-Oriented-Architecture-and-getting-started-with-Oracle-Service-Bus-27-320.jpg)
![T his is the path of the variable structure at run time.
1. T o select the PO element:
1. U nder the T ype field, make sure the appropriate radio button is selected, then select WSDL Element.
2. C lick Browse.
3. In the WSDL Browser, select SampleWSDL, then select PO under Elements in the Select WSDL Definitions pane.
4. C lick Submit.
5. Select the Set as child checkbox to set the PO element as a child of the body element.
6. C lick A dd. T he new variable structure PO attachment is included under XM L Type in the drop-down list of variable structures.
7. If there are multiple attachments, add an index to the reference when you use fields from this structured variable in your
XQ ueries. For example, if you drag the P O field to the XQ uery field, but as P O will be the second attachment, change the
inserted value from
$attachments/ctx:attachment/ctx:body/oracle:PO/oracle:id
to
$attachments/ctx:attachment[2]/ctx:body/oracle:PO/oracle:id
8.51. Quality of Service
T he following sections discuss quality of service features in O racle Service Bus messaging:
Delivery Guarantees
O utbound M essage Retries
8.52. Delivery Guarantees
O racle Service Bus supports reliable messaging. When messages are routed to another service from a route node, the default
quality of service (Q oS) is exactly once if the proxy service transport is defined as JM S/XA; otherwise best effort Q oS is
supported.
Q uality of service is set in the qualityOfService element in the $outbound context variable.
T he following delivery guarantee types are provided in O racle Service Bus, shown in T able 3-9.
Delivery
Reliability
Description
Exactly
once
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. Exactly once means reliability is
optimized.
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.
T he default value of the qualityOfService element is exactly -once for a route node action for the following inbound
transports:
e-mail
FT P
File
JM S/XA
§ SFT P
§ T ransactional T uxedo
Note: Do not retry the outbound transport when the QoS is exactly once
A t least
once
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 time-out, a failure to connect, or a broken communication link. If failover U RLs are specified,at least
once semantics is provided with respect to at least one of the U RLs.
At least once delivery semantics is attempted if exactly once is not possible but the qualityOfService element is
exactly-once.
Best
effort
Best effort means that there is no reliable messaging and there is no elimination of duplicate messages —however,
performance is optimized. It is performed if the qualityOfService element is best-effort. Best effort delivery is also
performed if exactly once and at least once delivery semantics are not possible but the qualityOfService element
is exactly-once.
T he default value of the qualityOfService element for a route node is best-effort for the following inbound
transports:
HT TP
JM S/nonXA
Non-T ransactional Tuxedo](https://image.slidesharecdn.com/soawithosbshaan-150603043608-lva1-app6891/85/Understanding-the-basic-need-of-Service-Oriented-Architecture-and-getting-started-with-Oracle-Service-Bus-34-320.jpg)
Understanding the basic need of Service Oriented Architecture and getting started with Oracle Service Bus
- 1. 1. SERVICEORIENTED ARCHITECTURE What is SOA? Service Oriented Architecture. T his could be the basic definition of SO A. But why is the name SO A? SO A is an architectural approach for building business process with integration of loosely coupled applications/software (Service Orientation). M ost of you might be thinking what the hell does that mean? SO A originated with the concept of Service orientation. Service orientation is listening and understanding the customer (customer can be working on different platforms but they want to access application build on a different environment). T hat seems to be easy with words but I still did not get what does SOA means. Let us start with basic understanding of evolution of SO A. C onsider a so called problem definition with which we will try to: A nalyze and understand problems faced with orthodox implementation of the software. How did evolution of SO A happened How would SO A implementation help business gain revenue? A ssume that you are a businessman which everyone in the IT industry thinks to be one day, planning/dreaming everyday to start a side business. T his is one typical example which is used everywhere, as we can find a lot of help with th is typical example. We have tried to make it a bit simple for beginners to understand with help online. So I being a small middle class IT guy I have a brilliant idea to start a small mortgage business where I lend money at low r ate of interest. I start with an online service where user can login and apply for a loan. With analysis we defined a problem definition for the service. P roblem definition: 1) If the rate of interest for the loan application is less than 5%, then the application for the loan has to go through a special approval from the management. Where the management would analyze the requirement of the applicant his needs and approve. 2) A ll other application can be directly sanctioned by the service, conditioned on having the details of the applicant. T hinking like a business man I start with thinking on how to save money, so what I plan to implementing the software all by yourself as I have the background of software after all my parents have spend so much of money it should be used somewhere. With all my knowledge and IT background I plan to start with the implementation. Basic and the most import thing for software is its architecture. So below is how I plan to implement my software: First page of the screen (assuming will implement login later on) which accepts the user information and details of loan to b e sanctioned. O nce the user enters the details, save the user details in a user details table and route the request to call appropriate methods, say requestWithRateBelowFive() and requestWithRateAboveFive(). C all these methods based on the request type i.e details and background information and capability to pay the EM I. A fter 6 long months of work and rigorous testing of my software, I plan to put my software live. With all the domain registration done my software is live. Now my project is live and is giving me a lot of profit. With the increased profit I want to have mor e functionality to be added in my software. Extension to problem definition: Where I can retrieve the details of the user who are consistent with their EMIs and are loyal customer to the company. A t the same time with millions of dollars in as my liquid cash I have acquired a company which gives special offers to the user with auto loans with low rate of interest. P roblems: With the current implementation of my project I will have to modify the entire implementation to include the new offer and merge the new companies’ software into my software. T his will result in downtime for 2 days which is directly proportional to loss of significant amount of revenue and customers . T his implementation/architecture of project is called as point to point integration.
- 2. T his is one of the oldest and original integration patterns. It derives its name from the direct, tightly bound connections that are made between applications and is the simplest of the integration architectures. T here are advantages with point to point integration: P oint-to-Point solutions are often fast and efficient. T he efficiency that derives from applications being tightly bound is one reason why at least a few P oint -to-Point solutions will continue to be utilized for the foreseeable future. What are the drawbacks with the current implementation/architecture of the product? A s the number of applications increases so does the overall complexity of the environment. High maintenance costs and a lack of flexibility, when it becomes necessary to make chang es. Conclusion: T he basic problem is the A rchitecture of the product, to be specific “Integration architecture”. 2. INTEGRATIONARCHITECTURE So what is Integration architecture and how is it significant for a fast growing business. C onsider an example of a well deigned building where all electrics and plumbing keep working no matter how many appliances are switched on or connected. T his building is capable enough for extension without tearing up the blueprint and start again with new electrical connection. T his is an example of good architecture. T he same applies to software systems. Software architecture is the backbone of any complex computer system. T he architecture encompasses all of the software elements, the relationships between the elemen ts and the user interfaces to those elements. T he performance and reliability of a software system are highly dependent upon the software architecture. Well-designed software architecture can be extended with relative ease to accommodate new applications without requiring extensive infrastructure development. Now question comes down to how can we eliminate this downtime and in future with new acquisitions integration. T here are many other types of INTEGRATION ARCHITECTURE: 3. HUB AND SPOKEINTEGRATIONARCHITECTURE T he earliest formal integration technologies worked on the principle that all information coming from the applications had to be processed within a single machine or server called a “hub”. A cting as a central point of control, the hub dealt with all message processing including routing, splitting and combining of messages, mapping, and so on. Hub and Spoke implementations decouple the sending and receiving applications. U nlike P oint -to-Point, the applications on either side of the hub can be modified independently of each other. Since applications no longer need to perform data mapping, centralized definition and control of business processes could be easily achieved for the first time. Hub and Spoke A rchitecture C entralized Integration P rocessing Hub What are the advantages of Hub and Spoke architecture? With Hub and Spoke, the integration environment becomes less complex. Whereas Point-to-Point becomes impossibly complicated as the number of connections increase, Hub and Spoke remains, in principle, simple since all the connections are to and from the hub. Hub and Spoke is the preferred architecture for achieving an easily controlled and managed environment in a medium sized integration project. What are the disadvantages of Hub and Spoke architecture? With Hub and Spoke, the initial setup of two-way communications can be challenging. T he hub has to coordinate messages flowing between applications, and at the same time applications on both sides of the hub need to work well in a decoupled fashion. Both the source and target applications need some knowledge of each other in order to process messages. T his sometimes makes it difficult to add or remove senders and receivers.
- 3. Since the hub must control all of the integrated processes, it is a viable option only when both sender and receiver agree on which hub to use. T his will not be a problem for companies that are integrating internally, but may become a serious issue fo r Business to Business (B2B) and even cross-departmental integration projects. U nfortunately, with so much processing taking place in the central hub, Hub and Spoke exacts high overheads. P rocesses within the hub often require significant processing power and lots of disk space. A s the number and complexity of proce sses increase, performance can suffer and hubs often become difficult to manage, maintain, and extend. P ure Hub and Spoke implementations do not scale well. O ne solution is to create a Federated architecture, which is an extension of Hub and Spoke that allows for multiple hubs to provide load sharing and back-up in case of failure. 4. DISTRIBUTEDINTEGRATIONARCHITECTURE In distributed architecture: M essage translation, routing, splitting, and combining are performed closer to source and target system by using smaller computers called agents. A gent computers are connected to just one system and reduce the processing load on that system. A gents take information from the application they are connected to, process it, and send it to any target appli cation(s) interested in receiving that information. T his is also known as peer to peer integration architecture. What are the advantages of Distributed architecture? Distributed architecture is governed by centralized rules and the requirements of the bu siness flow. M ost of the processing is performed in agent processors located near the source and target applications. Besides gains in processing efficiency by distributing the workload among dedicated processors, a Distributed A rchitecture is able to grow relatively easily. What are the disadvantages of Distributed architecture? M any organizations have a mix of platforms and operating systems on which their business applications run, a situation that i s often the result of mergers and acquisitions. When it becomes necessary to change or expand the system architecture, it is unfortunately not simply a matter of choosing one of the distributed technologies and implementing it. O pting for one technology may only provide a distributed solution for half of your organization due to the mix of systems that are being used. Beyond these internal problems, there is also the issue of engaging in Business to Business (B2B) exchanges with other companies. T his is another case where an eclectic mix of systems and technolo gies between businesses can impede the use of Distributed Architecture. 5. SERVICEORIENTED ARCHITECTURE (SOA) Service Oriented A rchitecture (SOA) is the latest architectural approach, although it’s not really very new. Service Oriented A rchitecture is essentially an enhanced version of Distributed Architecture that uses loosely coupled software services to support the requirements of business processes and software users. It goes a step further than the previous architectures by providing an integrated environment which spreads out the workload, breaking down the different “silos” of business functionality and opening their processes to other applications. A pplications comprised of loosely bound Web Services. One way to think of SOA is like a Lego set. A Lego set is more than just the individual blocks; specialized bigger pieces for complex creations are also available. Similarly, with SO A, an application can customize and/or change the individual pieces o r “services” that it uses. U sing these concepts, vast and complex component based applications can be developed. T he breakthrough for SO A came with the acceptance of Web Services, where different vendors agree to a common communication a standard which is XML. A fter Web Services came Enterprise Service Bus (ESB) technology. Based on Web Services, and exhibiting all of the characteristics of the M essaging solutions previously supplied by the integration vendors, ESB has become the accepted standard for the creation of an organization’s Service Oriented A rchitecture. Without exception all of the integration vendors now provide an SO A architecture built on the concept of an Enterprise Service Bus (ESB). T o summarize the definition, SOA is an architecture pattern to integrate loosely coupled applications in to one system.
- 4. IT companies have started to realize that the ultimate objective these days for building a system would be to automate business processes i.e. to develop applications that would provide a complete flow of the process from its end to the beginning. T here are many challenges that an IT company building the application would face. T wo of the basic challenges which lay the basic foundation of the developing business process are: 1) Every company does not have the same requirements. 2) C hanges are constantly incorporated in a business process to compete; the enterprise service has to be flexible enough to incorporate the changes. If you are still not clear with the definition you may say that this statement contradict with the basic requirement on which a service is build i.e. stability and availability to process as and when required. Here it goes again with very simple and cle ar words. SOA is aggregation of such stable services. Services are constructed to be stable and efficient while aggregations are designed to be agile or rather accept the changes. Hence these loosely coupled services (Service O riented) aggregations are much more open to changes rather than the orthodox monolithic services that require ages to incorporate even a small change in the service. Now the questions arises how are these independent stable services aggregated to design a loosely coupled system? How do we ensure that the stability of the service will be maintained if it is coupled with another se rvice which is constructed on a different platform? T he answer to the questions is standardization of the platform on which the services are coupled. T hese services remain stable by relying themselves on standard based interfaces and standard/defined messa ges (SOAP/Schemas). I hope the basic question of why SO A is introduced in IT industry and how would it look like in a top view of the system is clear. For a beginner there are millions of questions that needs to be answered with respect to the ingredients to coupling of services, how are these services deployed and on what platform do we couple or rather how do we incorporate the standardization to integrate this system. I hope the next upcoming section of SO A would answer their questions. 6. EXTENSIBLEMARKUPLANGUAGE What is XML? From definitions of W3C : XM L stands for EXtensible M arkup Language. XM L is a markup language much like HTML. XM L was designed to carry and store data, not to display data. XM L tags are not predefined. Y ou must define your own tags. XM L is designed to be self-descriptive. XM L is a W3C Recommendation. Example: <note> <to>T ove</to> <from>Jani</from> <heading>Reminder</heading> <body>Don’t forget me this weekend!</body> </note> Where: T he tags in the example above (like <to> and <from>) are not defined in any XM L standard. T hese tags are “invented” by the author of the XM L document. What is XM L namespace? XM L Namespaces provide a method to avoid element name conflicts. T he XM L namespace is a special type of reserved XM L attribute that you place in an XM L tag. T he reserved attribute is actually more like a prefix that you attach to any namespace you create. T his attribute prefix is “xmlns:”, which stands for XM L NameSpace. T he colon is used to separate the prefix from your names pace that you are creating.
- 5. What is XML Schema? A n XM L Schema describes the structure of an XM L document. T he XM L Schema language is also referred to as XML Schema Definition (XSD). A n XM L Schema: defines elements that can appear in a document defines attributes that can appear in a document defines which elements are child elements defines the order of child elements defines the number of child elements defines whether an element is empty or can include text defines data types for elements and attributes Defines default and fixed values for elements and attributes. 7. WEB SERVICE DESCRIPTIONLANGUAGE What is WSDL? WSDL stands for Web Services Description Language WSDL is written in XM L WSDL is an XM L document WSDL is used to describe Web services WSDL is also used to locate Web services and the operations (or methods) the service exposes. WSDL is a W3C recommendation. T o start with any software we have client requirements. T hese requirements define the input and the output elements of the service. T he data types of the input and output messages in terms if whether the input message will have a U ser ID with a length defined of 8 characters and it shout be of string type. T hese requirements are like a contract between the provider of the service and the user of the service. T he user cannot access the service if it provides the input (U ser ID) with more than 8 characters and the provider of the service needs to th row a fault or make the service unavailable for the user with U s er ID more than 8 characters. T his contact is defined in a document called WSDL on which web service is constructed. Y ou can say that WSDL is the stilt of a web service. WSDL is definition of web service in its language i.e. XM L. It is a contract between the service provider and the user. It is a description of the web service. WSDL can be broken down to 4 critical chunks. 1. Interface information/ Operation information. 2. M essage Information/ Data type information. 3. Binding Information/ T ransport Information. 4. A ddress Information/ Location Information. With respect to constructing a WSDL it can be defined with 6 major elements: 1. definitions 2. types 3. message 4. portT ype 5. binding 6. service Y ou might be thinking why I have written the elements name in lower case. T his would sound a bit stupid but this is how the elements appear in the wsdl definition.
- 6. Let us look at a sample WSDL now. <?xml version=”1.0″ encoding=”U TF-8″ standalone=”no”?> <wsdl:definitions xmlns:soap=”http://schemas.xmlsoap.org/wsdl/soap/” xmlns:tns=”http://www.example.org/NewWSDLFile/” xmlns:wsdl=”http://schemas.xmlsoap.org/wsdl/” xmlns:xsd=”http://www.w3.org/2001/XMLSchema” name=”NewWSDLFile” targetNamespace=”http://www.example.org/NewWSDLFile/”> <wsdl:types> <xsd:schema targetNamespace=”http://www.example.org/NewWSDLFile/”> <xsd:element name=”NewOperation”> <xsd:complexType> <xsd:sequence> <xsd:element name=”in” type=”xsd:string”/> </xsd:sequence> </xsd:complexType> </xsd:element> <xsd:element name=”NewOperationResponse”> <xsd:complexType> <xsd:sequence> <xsd:element name=”out” type=”xsd:string”/> </xsd:sequence> </xsd:complexType> </xsd:element> </xsd:schema> </wsdl:types> <wsdl:message name=”NewOperationRequest”> <wsdl:part element=”tns:NewOperation” name=”parameters”/> </wsdl:message> <wsdl:message name=”NewOperationResponse”> <wsdl:part element=”tns:NewOperationResponse” name=”parameters”/> </wsdl:message> <wsdl:portT ype name=”NewWSDLFile”> <wsdl:operation name=”NewOperation”> <wsdl:input message=”tns:NewOperationRequest”/> <wsdl:output message=”tns:NewOperationResponse”/> </wsdl:operation> </wsdl:portT ype> <wsdl:binding name=”NewWSDLFileSOAP” type=”tns:NewWSDLFile”> <soap:binding style=”document” transport=”http://schemas.xmlsoap.org/soap/http”/> <wsdl:operation name=”NewOperation”> <soap:operation soapAction=”http://www.example.org/NewWSDLFile/NewOperation”/> <wsdl:input> <soap:body use=”literal”/> </wsdl:input> <wsdl:output> <soap:body use=”literal”/>
- 7. </wsdl:output> </wsdl:operation> </wsdl:binding> <wsdl:service name=”NewWSDLFile”> <wsdl:port binding=”tns:NewWSDLFileSOAP” name=”NewWSDLFileSOAP”> <soap:address location=”http://www.example.org/”/> </wsdl:port> </wsdl:service> </wsdl:definitions> In the WSDL described above all the 6 elements are highlighted in black. Y ou would by now have concluded that a WSDL is aggregation of these 6 elements. Let us now see what exactly these 6 elements consists of and why are they included in a WSDL definition. 1) definitions: It is the root element of all the WSDL document. It defines the name of the web service. <wsdl:definitions name=”NewWSDLFile” xmlns:soap=”http://schemas.xmlsoap.org/wsdl/soap/” xmlns:tns=”http://www.example.org/NewWSDLFile/” xmlns:wsdl=”http://schemas.xmlsoap.org/wsdl/” xmlns:xsd=”http://www.w3.org/2001/XMLSchema” targetNamespace=”http://www.example.org/NewWSDLFile/”> </wsdl:definitions> It defines various namespaces that is used through out the document. 2) types: It describes the data type of the message being exchanged. If the message exchange is only in terms of simple data types as string and integer then this types element would not be required. O ne more thing to notice is WSDL does not use any exclusive typing system, but if not declared it uses W3C XML schema specifications as the default choice. <wsdl:types> <xsd:schema targetNamespace=”http://www.example.org/NewWSDLFile/”> <xsd:element name=”NewOperation”> <xsd:complexType> <xsd:sequence> <xsd:element name=”in” type=”xsd:string”/> </xsd:sequence> </xsd:complexType> </xsd:element> <xsd:element name=”NewOperationResponse”> <xsd:complexType> <xsd:sequence> <xsd:element name=”out” type=”xsd:string”/> </xsd:sequence> </xsd:complexType> </xsd:element> </xsd:schema> </wsdl:types> 3) messages: It provides the abstract of the message being transferred in a one-way transmission. It can contain one or more part elements which can refer to message parameters or return values. <wsdl:message name=”NewOperationRequest”> <wsdl:part element=”tns:NewOperation” name=”parameters”/>
- 8. </wsdl:message> <wsdl:message name=”NewOperationResponse”> <wsdl:part element=”tns:NewOperationResponse” name=”parameters”/> </wsdl:message> 4) portType: portT ype combines multiple message elements defined above to complete the round trip of the operation. Each operation to complete its service needs to have a set of request and response message which is described in the message elements. Each portType can have multiple operations element. <wsdl:portT ype name=”NewWSDLFile”> <wsdl:operation name=”NewOperation”> <wsdl:input message=”tns:NewOperationRequest”/> <wsdl:output message=”tns:NewOperationResponse”/> </wsdl:operation> </wsdl:portT ype> Let us link up the 3 elements above and see where we have reached in terms of WSDL description. Starting from the bottom, each web service has an operation or it can have many operations to perform. Each operation during its service takes an input request and delivers an output response. T his operation is defined in portT ype element described above. T his input and output messages has multiple parameters or data types that is described in the element message. T he data type can be defined separately as a combination of many sub data types or elements which is describes under types element. 5) binding: T his element describes the concrete protocol/standard on which the service will be implemented. It describes the data format specification on which the message and operations are defined. WSDL has a build in extension for defining SO AP based services. Hence SOAP specific information goes under this element. <wsdl:binding name=”NewWSDLFileSOAP” type=”tns:NewWSDLFile”> <soap:binding style=”document” transport=”http://schemas.xmlsoap.org/soap/http”/> <wsdl:operation name=”NewOperation”> <soap:operation soapAction=”http://www.example.org/NewWSDLFile/NewOperation”/> <wsdl:input> <soap:body use=”literal”/> </wsdl:input> <wsdl:output> <soap:body use=”literal”/> </wsdl:output> </wsdl:operation> </wsdl:binding> 6) service: T his element describes the location or the address for invoking the service. It is used to aggregate a set of ports to retrieve the location to access the specific service. <wsdl:service name=”NewWSDLFile”> <wsdl:port binding=”tns:NewWSDLFileSOAP” name=”NewWSDLFileSOAP”> <soap:address location=”http://www.example.org/”/> </wsdl:port> </wsdl:service> So there it is we are done with the creation of a WSDL. A ll the elements defined here aggregated will let us define a web service contract. T his WSDL is a very important aspect of a web service. T his contract defines all the elements/parameters needed in the request and response of the operation and which is agreed upon by the provider and user of the web service.
- 9. Based on the requirements from the client the elements are described in the messages. T he input that is received from the user to the operation is validated against the operation elements described in the WSDL. T heir input cannot violate the description of the input message in the WSDL, which is an important aspect of web -services security operations. 8. ORACLE SERVICE BUS A s explained earlier service bus is a solution to problems faced by poor integration architecture. 8.1. Bus, what Bus? T he use of a Service Bus pattern helps to decouple the pieces from each other, messages are passed between the components in the form of asynchronous event topics in a publish/subscribe pattern, that allows every part to be decoupled from the othe r part and we do not need to span transactions or hold connections between the internal components that would ultimately cause a degradation in the performance of the system. T he Service Bus should also perform the routing of messages between the components so no components would have to be dependent on the knowledge of the location of another component. C onnections between the user interface will and should be point to point as this is required for the component to perform its duty within the constraints that are imposed upon it, the same holds true for software architectures. T he reduction of dependency on other parts should be driven as far down into the architecture as is reasonable, as this will lead one down the path of flexibility and testability. Introduction: A proven, lightweight, configuration based, policy driven integration techno logy specifically designed for the task of integrating, virtualizing, scaling service management, and traditional message brokering across heterogeneous IT environments and managing services in a service-oriented architecture (SOA), O racle Service Bus enables you to achieve value more quickly with simple, code-free, configuration based service integration. Y ou will be able to move toward enterprise wide SOA deployments with a high-performance, highly scalable SOA integration backbone. T he O racle Service Bus (O SB) provides service bus capabilities for the entire company, again including standard functionality as transformation, routing, event delivery and payload validation. It’s main function is to decouple intra -application communication from inter-application. Endpoint changes will not affect the internals of composite applications. T he O SB is based on the A qualogic Service Bus, augmented with key features from the O racle ESB, especially JCA adapters, DVM, X -ref and JDev based design-time. A dvantages: Location transparency: Isolate from changes to service location. Backward compatibility: isolate from changes to service contact on the new service added. Service enablement: allow multiple protocols/messages to participate in SOA. Dynamic routing: U se business rules to determine destination service. Message enrichment: update the message using the response from another service. 8.2. Resources in Oracle Service Bus In O racle Service Bus world, all the artifacts are called the O SB resources. In a typical SOA environment, there will be a need to share the different resources across the projects. T he resources can be anything like WSDLs, XSDs, P roxy, Business service etc. We cannot create all kinds of resources in the O SB Configuration P roject. For example creating WSDL or XSD in configuration project will give the error. We can only create the Global Resources like Proxy Server, JNDI Provider and SM TP Server. A ll these resources that can be created in the O SB Configuration P roject can be accessed from different O SB projects present in the C onfiguration Project.
- 10. 8.3. Proxy Services and Business Services O racle Service Bus provides intelligent message brokering between business services (such as enterprise services and databases) and service clients (such as presentation applications or other business services) through proxy services that you can configure using O racle Service Bus Console. P roxy services are O racle Service Bus definitions of intermediary Web services that O racle Service Bus implements locally on WebLogic Server. With O racle Service Bus message brokering, service clients exchange messages with an intermediary proxy service rather than working directly with a business service. O racle Service Bus allows you to implement proxy services independently and configure them dynamically, as driven by your business needs without requiring costly infrastructure development efforts. T he configuration functions are separated from the management functions in O racle Service Bus C onsole. A proxy service can route messages to multiple business services; you can choose to configure a proxy service with an interface that is independent of the business services with which the proxy service communicates. In such cases, you can configure a message flow definition to route a message to the appropriate business service and map the message data into the format required by the business service’s interface. Business services are O racle Service Bus definitions of the enterprise services that exchange messages during business processes. A business service and its interface can be defined and configured using the O racle Service Bus C onsole. T o configure a business service you must specify its interface, type of transport it uses, its security requirements, and other characteristics. A business service definition is similar to that of a proxy service, but it does not have a p ipeline. 8.4. Message Flows and Pipelines In O racle Service Bus, a message flow is the implementation of a proxy service. Y ou configure the logic for the manipulation of messages using proxy service message flow definitions. T his logic includes such activities as transformation, publishing, and reporting, which are implemented as individual actions within the stages of a pipeline. P ipelines are one-way processing paths that include no branching. A pipeline is a named sequence of stages containing actions, representing a non-branching one-way processing path. It is used to specify the message flow for service requests and responses. A stage is a user-configured processing step. M essages fed into the pipelines are accompanied by a set of message context variables that contain the message contents. T hey can be accessed or modified by actions in the pipeline stages. 8.5. Pipeline Pairs P ipeline pairs are request and response pipelines. T he request pipeline definition specifies the actions that O racle Service Bus performs on request messages to the proxy service before invoking a business service or another proxy service. T he response pipeline definition specifies the processing that O racle Service Bus performs on responses from the business or proxy service that the proxy service invokes before returning a response to a client. Each pipeline consists of a sequence of stages, each stage containing actions. However, a single service-level request pipeline might optionally branch out into operational pipelines (you can configure one default operational pipeline at most one per operation). T he determination of the operation is done through user-selected criteria. T he response processing starts with the relevant operation pipeline which then joins into a single service-level response pipeline. 8.6. Message Flow Components A message flow is composed of components that define the logic for routing and manipulating messages as they flow through a proxy service. Nodes are configured to route messages through the message flow, and stages and actions contain rules for processing and transforming messages. M ost of the processing logic in a message flow is handled in pipelines. A pipeline is a named sequence of stages representing a non-branching one-way processing path. P ipelines belong to one of the following categories: Request pipelines process the request path of the message flow. Response pipelines process the response path of the message flow. Error pipelines handle errors for stages and nodes in a message flow as well as errors at the level of the message flow (service). T o implement the processing logic of a proxy service, request and response pipelines are paired together in pipeline pair nodes. T hese pipeline pair nodes can be combined with other nodes into a single-rooted tree structure to control overall flow.
- 11. T able 3-1 describes the components available for defining message flows. Component Type Summary Start node Every message flow begins with a start node. A ll messages enter the message flow through the start node, and all response messages are returned to the client through the start node. T here is nothing to configure in a start node. P ipeline pair node A pipeline pair node combines a single request pipeline and a single response pipeline in one top -level element. A pipeline pair node can have only one direct descendant in the message flow. During request processing, only the request pipeline is executed when O racle Service Bus processes a pipeline pair node. T he execution path is reversed when O racle Service Bus processes the response pipeline. Stage Request pipelines, response pipelines, and error handlers can contain stages, where you configure actions to manipulate messages passing through the pipeline. Error handler A n error handler can be attached to any node or stage, to handle potential errors at that location. Branch node A branch node allows processing to proceed along exactly one of several possible paths. O perational branching is supported for WSDL -based services, where the branching is based on operations defined in the WSDL. C onditional branching is supported for conditions define d in an XP ath-based switch table. Route node A route node performs request/response communication with another service. It represents the boundary between request and response processing for the proxy service. When the route node dispatches a request mess age, the request processing is considered complete. When the route node receives a response message, the response processing begins. T he route node supports conditional routing as well as request and response transformations. Because a route node represents the boundary between request and response processing, it cannot have any descendants in the message flow. 8.7. Building a Message Flow T he only components required in a message flow are a start node and a route node. No restrictions exist on what other components can be chained together in the message flow. Y ou could create a single route node that contained all the logic for the flow. O r, you could link two pipeline pair nodes without a branch node in between. If you use branch nodes, eac h branch node could start with a different element. O ne branch could terminate with a route node, another could be followed by a pipeline pair, and yet another could have no descendant. (When a branch with no descendants is executed at run time, response processing begins immediately.) However, in general, a message flow is likely to be designed in one of the following ways: For non-operational services (services that are not based on WSDLs with operations), the flow consists of a single pipeline pair at the root followed by a route node. For operational services, the flow consists of a single pipeline pair at the root, followed by a branch node based on an operation, with each branch consisting of a pipeline pair followed by a route node. 8.8. Message Execution T able below describes how message are processes in a typical message flow: M essage Flow Node What happens during message processing? Request P rocessing Start node Request processing begins at the start node. P ipeline pair node Executes the request pipeline only. Branch node Evaluates the branch table and proceeds down the relevant branch. Route node P erforms the route along with any request transformations. In the message flow, regardless of whether routing takes place or not, the route node represents the transition from processing a request to processing a response. A t the route node, the direction of the message flow is reversed. If a request path does not have a route node, the response processing is initiated in the reverse direction without waiting for any response. Response P rocessing Skips any branch nodes and continues with the node that preceded the branch Route node Executes any response transformations.
- 12. Branch node Skips any branch nodes and continues with the node that prec eded the branch P ipeline pair node Executes the response pipeline Start node Sends the response back to the client 8.9. Branching in Message Flows T wo kinds of branching are supported in message flows: operational branching, configured in an operational branch node, and conditional branching, configured in a conditional branch node. 8.9.1. Operational Branching When message flows define WSDL-based proxy services, operation-specific processing is required. When you create an operational branch node in a message flow, you can build branching logic based on the operations defined in the WSDL. Y ou must use operational branching when a proxy service is based on a WSDL with multiple operations. Y ou can consider using an operational branch node to handle messages separately for each operation. 8.9.2. Conditional Branching U se conditional branching to branch based on a specified condition, for example the document type of a message. C onditional branching is driven by a lookup table with each branch tagged with simple, unique string values, for example, Q uantityEqualToOrLessThan150 and Q uantityMoreThan150. Y ou can configure a conditional branch to branch based on the value of a variable in the message context (declared, for example, in a stage earlier in the message flow), or you can configure the condition to branch based on the results of an XP a th expression defined in the branch itself. A t run time, the variable or the expression is evaluated, and the resulting value is used to determine which branch to follow. If no branch matches the value, the default branch is followed. A branch node may have several d escendants in the message flow: one for each branch, including the default branch. Y ou should always define a default branch. Y ou should design the proxy service in such a way that the value of a lookup variable is set before reaching the branch node. For example, consider the following case using a lookup variable. A proxy service is of type any SOAP or any XM L, and you need to determine the type of the message so you can perform conditional branching. Y ou can design a stage action to identify the message type and then design a conditional branching node later in the flow to separate processing based on the message type. Now consider the following case using an XP ath expression in the conditional branch node. Y ou want to branch based on the quantity in an order. T hat quantity is passed via a variable that can be retrieved from a known location in $body. Y ou could define the following XP ath expression to retrieve the quantity: declare namespace openuri=”http://www.openuri.org/”; declare namespace com=”oracle.com/demo/orders/cmnCust”; ./openuri:processCust/com:cmnCust/com:Order_Items/com:Item/com:Quantity T he condition (for example, <500) is then evaluated in order down the message flow against the expres sion. Whichever condition is satisfied first determines which branch is followed. If no branch condition is satisfied, then the default branc h is followed. Y ou can use conditional branching to expose the routing alternatives for the message flow at the top level flow view. For example, consider a situation where you want to invoke service A or service B based on a condition known early in the message flow (for example, the message type). Y ou could configure the conditional branching in a routing table in th e route node. However, that makes the branching somewhat more difficult to follow if you are just looking at the top level of the flo w. Instead, you could use a conditional branch node to expose this branching in the message flow itself and use simple rout e nodes as the subflows for each of the branches. C onsider your business scenario before deciding whether you configure branching in the message flow or in a stage or route node. When making your decision, remember that configuring branches in the message flow can be awkward in the design interface if a large number of branches extend from the branch node. 8.10. Configuring Actions in Stages and Route Nodes A ctions provide instructions for handling messages in pipeline stages, error handler stages, and route nodes. T he context determines which actions are available in the O racle Service Bus C onsole or in the O racle Service Bus Plug -ins for Workshop for WebLogic, as described in the following sections: C ommunication A ctions Flow C ontrol Actions
- 13. M essage P rocessing A ctions Reporting A ctions 8.10.1. Communication Actions C ommunication actions control message flow: A ction U se A vailable in Dynamic publish P ublish a message to a service specified by an XQ uery expression P ipeline stage Error handler stage Route node P ublish Identify a statically specified target service for a message and to configure how the message is packaged and sent to that service P ipeline stage Error handler stage P ublish table P ublish a message to zero or more statically specified services. Switch- style condition logic is used to determine at run time which services will be used for the publish P ipeline stage Error handler stage Routing options M odify any or all of the following properties in the outbound request: U RI, Q uality of Service, M ode, Retry parameters, M essage P riority P ipeline stage Service callout C onfigure a synchronous (blocking) callout to an O racle Service Bus- registered proxy or business service. P ipeline stage Error handler stage T ransport headers Set the header values in messages P ipeline stage Error handler stage 8.10.2. Flow Control Actions Flow controls actions implement conditional routing, conditional looping, and error handling. Y ou can also use them to notify the invoker of success or to skip the rest of the actions in the stage: Action Use to. Available in For each Iterate over a sequence of values and execute a block of actions P ipeline stage Error handler stage If… then… P erform an action or set of actions conditionally, based on the Boolean result of an XQ uery expression P ipeline stage Route node Error handler stage Raise error Raise an exception with a specified error code (a string) and description P ipeline stage Error handler stage Reply Specify that an immediate reply be sent to the invoker. T he reply action can be used in the request, response or error pipeline. Y ou can configure it to result in a reply with success or failure. In the case of reply with failure where the inbound transport is HT TP, the reply action specifies that an immediate reply is sent to the invoker P ipeline stage Error handler stage Resume Resume message flow after an error is handled by an error handler. T his action has no parameters and can only be used in error handlers Error handler stage Skip Specify that at run time, the execution P ipeline stage
- 14. of this stage is skipped and the processing proceeds to the next stage in the message flow. T his action has no parameters and can be used in the request, response or error pipelines Error handler stage 8.10.3. Message Processing Actions T he actions in this category process the message flow. T able 3-5 describes the message processing actions. A ction U se Location A ssign A ssign the result of an XQ uery expression to a context variable. P ipeline stage Error handler stage Delete Delete a context variable or a set of nodes specified by an XP ath expression. P ipeline stage Error handler stage Insert Insert the result of an XQ uery expression at an identified place relative to nodes selected by an XP ath expression. P ipeline stage Error handler stage Java callout Invoke a Java method, or EJB business service, from within the message flow. P ipeline stage Error handler stage M FL transform C onvert message content from XM L to non-XML, or vice versa, in the message pipeline. A n M FL is a specialized XML document used to describe the layout of binary data. It is an O racle proprietary language used to define rules to transform formatted binary data into XML data, or vice versa. P ipeline stage Error handler stage Rename Rename elements selected by an XP ath expression without modifying the contents of the element. P ipeline stage Error handler stage Replace Replace a node or the contents of a node specified by an XP ath expression. T he node or its contents are replaced with the value returned by an XQ uery expression. A replace action can be used to replace simple values, elements and even attributes. A n XQuery expression that returns nothing is equivalent to deleting the identified nodes or making them empty, depending upon whether the action is replacing entire nodes or just node contents. T he replace action is one of a set of U pdate actions. P ipeline stage Error handler stage V alidate V alidate elements selected by an XP ath expression against an XM L schema element or a WSDL resource. Y ou can validate global elements only; Oracle Service Bus does not support validation against local elements. P ipeline stage Error handler stage
- 15. 8.10.4. Reporting Actions Y ou use the actions in this category to log or report errors and generate alerts if required in a message flow within a stage. T able 3-4 describes the reporting actions. A ction U se to… A vailable in A lert Generate alerts based on message context in a pipeline, to send to an alert destination. U nlike SLA alerts, notifications generated by the alert action are primarily intended for business purposes, or to report errors, and not for monitoring system health. A lert destination should be configured and chosen with this in mind. If pipeline alerting is not enabled for the service or enabled at the domain level, the configured alert action is bypassed during message processing. P ipeline stage Error handler stage Log C onstruct a message to be logged and to define a s et of attributes with which the message is logged. P ipeline stage Error handler stage Report Enable message reporting for a proxy service. P ipeline stage Error handler stage 8.11. Configuring Transport Headers in Message Flows T he transport header action is a communication type action, and it is available in pipeline stages and error handler stages. 8.11.1. Configuring Global Pass Through and Header-Specific Copy Options for Transport Headers T he following options are available when you configure a transport headers action: T he Pass all Headers through Pipeline option specifies that at run time, the transport headers action passes all headers through from the inbound message to the outbound message or vice versa. Every header in the source set of headers is copied to the target header set, overwriting any existing values in the target header set. T he Copy Header from Inbound Request option and the Copy Header from Outbound Response options specifies that at run time, the transport headers action copies the specific header with which this option is associated from the inbound message to the outbound message or vice versa. U se the options in a way that best suits your scenario. Both options result in the headers in the source header set being copied to the target header set, overwriting any existing value in the target set. Note that the Pass all Headers through Pipeline option is executed before the header-specific Copy Header options. In other words, for a given transport headers action configuration, if you select Pass all Headers through Pipeline, there is no need to select theCopy Header option for given headers. However, you can select Pass all Headers through Pipeline to copy all headers, and subsequently configure the action such that individual headers are deleted by selecting Delete Header for specific headers. WARNING: Because transport headers are specific to the transport types, it is recommended that the pass -through (or copy) options only be used to copy headers between services of the same transport type. P assing (or copying) headers between services of different transport types can result in an error if the header being passed is not accepted by the target transport. For the same reasons, be careful when you specify a header name using the Set Header option. 8.11.1.1. Understanding How the Run Time Uses the Transport Headers Settings A s described above, you can use transport header actions to configure the values of the transport headers for outbound requests (the messages sent out by a proxy service in route, publish, or service callout actions) and inbound responses (the response messages a proxy service sends back to clients). In general, the header values can be: Specified using an XQ uery expression P assed through from the source to the target service Deleted while going from the source to the target service T he transport headers action allows you to set, delete, or pass -through the headers in $inbound or $outbound. If you set or delete these headers and then log $inbound or $outbound, you can see the effects of your changes. However, when the message is sent out, the O racle Service Bus binding layer may modify or remove some headers in $inbound or $outbound and
- 16. the underlying transport may in turn, ignore some of these headers and use its own values. A n important distinction is that any modifications done by the binding layer on a header are done directly to $inbound and $outbound, whereas modifications done by the transport affects only the message’swire format. For example, although you can specify a value for the outbound C ontent-Length header, the binding layer deletes it from $outbound when sending the message. C onsequently, the modification is visible in the response path (for example, you can see the modified value if you log $outbound). If you set t he U ser-Agent header in $outbound, the HT TP transport ignores it and use its own value—however, the value in $outbound is not changed. T able 3-7 describes the transport headers that are ignored or overwritten at run time and other limitations that exist for specific transport headers. T ransport Description of Limitation… T ransport Headers A ffected By Limitation… O utbound Request Inbound Response HT TP O racle Service Bus run time may overwrite these headers in the binding layer when preparing the message for dispatch. If these headers are modified, $inbound and $outbound are updated accordingly. C ontent-Type C ontent-Type T he underlying transport may ignore these headers and use different values when sending the message. A ny changes done by the transport will not be reflected in $inbound or $outbound. A ccept C ontent-Length C onnection Host U ser-Agent C ontent-Length Date T ransfer-Encoding JM S C an only be set when the request is with respect to a one- way service or a request/response service based on JM SMessageID correlation. If sending to a request/response service based on JM SCorrelationID correlation, these headers are overwritten at run time. JM SCorrelationID JM SCorrelationID Should be set to the message time-to-live in milliseconds. T he resulting value in the message received is the sum of the time-to-live value specified by the client and the GM T at the time of the send or publish1. JM SExpiration JM SExpiration T he O racle Service Bus run time sets these headers. In other words, any specifications you make for these headers at design time are overwritten at run time. JM SMessageID JM SRedelivered JM STimestamp JM SXDeliveryCount JM SXUserID JM S_IBM_PutDate2 JM S_IBM_PutTime 2 JM S_IBM_PutApplType 2 JM S_IBM_Encoding 2 JM S_IBM_Character_Set2 JM SMessageID JM SRedelivered JM STimestamp JM SXDeliveryCount JM SXUserID JM S_IBM_PutDate 2 JM S_IBM_PutTime 2 JM S_IBM_PutApplType 2 JM S_IBM_Encoding 2 JM S_IBM_Character_Set 2 Because IBM MQ does not allow certain properties to be set by a client application, if you set these headers with respect to an IBM M Q destination, a run-time exception is raised. JM SXDeliveryCount JM SXUserID JM SXAppID JM SXDeliveryCount JM SXUserID JM SXAppID T hese headers cannot be deleted when the P ass all Headers through P ipeline option is also specified. JM SDeliveryMode JM SExpiration JM SMessageID JM SRedelivered JM STimestamp JM SXDeliveryCount JM SDeliveryMode JM SExpiration JM SMessageID JM SRedelivered § JM STimestamp § JM SXDeliveryCount JM SCorelationID—if the inbound message has the correlation ID se example, if the inbound response c from a registered JMS business se FT P No limitations. In other words you can set or delete the header(s)3for File and FT P transports and your specifications are honored by the O racle Service Bus run time. File E-mail T he O racle Service Bus run time sets these headers. In other C ontent-Type C ontent-Type
- 17. words, any specifications you make for these headers at design time are overwritten at run time. O racle Service Bus does not use these headers for outbound requests. If you set them dynamically (that is, if you set them in the $outbound headers section), O racle Service Bus ignores them. T hese headers are received in $inbound. Date is the time the mail was sent by the sender. From is retrieved from incoming mail headers. From (Name) Date For example, if you set the JM SExpiration header to 1000, and at the time of the send, GM T is 1,000,000 (as a result of System.currentTimeMillis()), the resulting value of the JM SExpiration property in the JM S message is 1,000,1000 Header names with the JM S_IBM prefix are to be used with respect to destinations hosted by an IBM MQ server For FT P and file proxies, there is an transport request header ‘fileName’. T he value of this request head er is the name of the file being polled. Note T he same limitations around setting certain transport headers and metadata are true when you set the inbound and outbound context variables, and when you use the O racle Service Bus T est C onsole to test your proxy or business services. 8.12. Performing Transformations in Message Flows T ransformation maps describe the mapping between two data types. O racle Service Bus supports data mapping that uses the XQ uery and the eXtensible Stylesheet Language T ransformation (XSLT) standards. XSLT maps describe XM L-to-XML mappings. XQ uery maps can describe XML-to-XML, XM L to non-XML, and non-XML to XM L mappings. T he point in a message flow at which you specify a transformation depends on whet her: T he message format relies on target services—that is, the message format must be in a format acceptable by the route destination. T his applies when the transformation is performed in a route node or in one of the publish actions. P ublish actions identify a target service for a message and configure how the message is packaged and sent to that service. O racle Service Bus also provides publish table actions. A publish table action consists of a set of routes wrapped in a switc h- style condition table. It is a shorthand construct that allows different routes to be selected, based upon the results of a single XQ uery expression. Y ou perform the transformation on the response or request message regardless of the route destination. In this case, you can configure the transformations in the request or response pipeline stages. 8.13. Transformations and Publish Actions When transformations are designed in publish actions, the transformations have a local copy of the $outbound variable and message-related variables ($header, $body, and $attachments). A ny changes you make to an outbound message in a publish action affect only the published message. In other words, the changes you make in the publish action are rolled back before the message flow proceeds to any actions that follow the publish action in your message flow. For example, consider a message flow that deals with a large purchase order, and you have to send the summary of the purchase order, through e-mail, to the manager. T he summary of the of the purchase order is created in the SOAP body of the incoming message when you include a publish action in the request pipeline. In the publish action, the purchase order data is transformed into a summary of the purchase order—for example, all the attachments in $attachments can be deleted because they are not required in the summary of the purchase order. 8.14. Transformations and Route Nodes Y ou may need to route messages to one of two destinations, based on a WS -addressing header. In that case, content-based routing and the second destination require the newer version of the document in the SO AP body. In this situation, you can configure the route node to conditionally route to one of the two destinations. Y ou can configure a transformation in the rou te node to transform the document for the second destination. Y ou can also set the control elements in the outbound context variable ($outbound) to influence the behavior of the system fo r the outbound message (for example, you can set the Q uality of Service). See Inbound and O utbound Variables and C onstructing M essages to Dispatch for information about the sub-elements of the inbound and outbound variables and how the content of messages is constructed using the values of the variables in the message context.
- 18. 8.15. Constructing Service Callout Messages When O racle Service Bus makes a call to a service via a service callout action, the content of the message is constructed using the values of variables in the message context. T he message content for outbound messages is handled differently depending upon the type of the target service. How the message content is created depends on the type of the target service and whether you choose to configure the SO AP body or the payload (parameters or document), as described in the following topics: SO AP Document Style Services SO AP RPC Style Services XM L Services M essaging Services 8.16. SOAP Document Style Services M essages for SO AP Document Style services (including EJB document and document-wrapped services), can be constructed as follows: T he variable assigned for the request document contains the SOAP body. T he variable assigned for the SO AP request header contains the SOAP header. T he response must be a single XML document—it is the content of the SO AP body plus the SOAP header (if specified) T o illustrate how messages are constructed during callouts to SOAP Document Style services, consider a service callout action configured as follows: Reques t Document V ariable: myreq Response Document V ariable: myresp SO AP Request Header: reqheader SO AP Response Header: respheader A ssume also that at run time, the request document variable, myreq, is bound to the following XM L. Listing 3-1 Content of Request Variable (myreq) <sayHello xmlns=”http://www.openuri.org/”> <intV al>100</intVal> <string>Hello</string> </sayHello> A t run time, the SO AP request header variable, reqheader, is bound to the following SO AP header. Listing 3-2 Content of SOAP Request Header Variable (reqheader) <soap:Header xmlns:soap=http://schemas.xmlsoap.org/soap/envelope/ xmlns:wsa=”http://schemas.xmlsoap.org/ws/2003/03/addressing”> <wsa:A ction>…</wsa:A ction> <wsa:T o>…</wsa:T o> <wsa:From>…</wsa:From> <wsa:ReplyT o>…</wsa:ReplyTo> <wsa:FaultT o>…</wsa:FaultTo> </soap:Header> In this example scenario, the full body of the message sent to the external service i s shown inListing 3-3 (the contents of the myreq and reqheader variables are shown in bold). Listing 3-3 Message Sent to the Service as a Result of Service Callout Action <?xml version=”1.0″ encoding=”U TF-8″?> <soapenv:Envelope xmlns:soapenv=”http://schemas.xmlsoap.org/soap/envelope/”> <soap:Header xmlns:soap=http://schemas.xmlsoap.org/soap/envelope/ xmlns:wsa=”http://schemas.xmlsoap.org/ws/2003/03/addressing”> ; <wsa:Action>…</wsa:Action> <wsa:To>…</wsa:To> <wsa:From>…</wsa:From> <wsa:ReplyTo>…</wsa:ReplyTo> <wsa:FaultTo>…</wsa:FaultTo> </soap:Header> <soapenv:Body> <sayHello xmlns=”http://www.openuri.org/”> <intVal>100</intVal> <string>Hello</string> </sayHello> </soapenv:Body> </soapenv:Envelope> Based on the configuration of the service callout action described above, the response from the service is assigned to the myresp variable. T he full response from the external service is shown inListing 3-4. Listing 3-4 Response Message From the Service as a Result of Service Callout Action
- 19. <?xml version=”1.0″ encoding=”U TF-8″?> <env:Envelope xmlns:env=”http://schemas.xmlsoap.org/soap/envelope/” xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance” xmlns:soapenc=”http://schemas.xmlsoap. org/soap/encoding/” xmlns:xsd=”http://www.w3.org/2001/XMLSchema”> <env:Header/> <env:Body env:encodingStyle=”http://schemas.xmlsoap.org/soap/encoding/”> <m:sayHelloResponse xmlns:m=”http://www.openuri.org/”> <result xsi:type=”xsd:string”>T his message brought to you by Hello and the number 100 </result> </m:sayHelloResponse> </env:Body> </env:Envelope> In this scenario, the myresp variable is assigned the value shown in Listing 3-5. Listing 3-5 Content of Response Variable (myresp) as a Result of Service Callout Action <m:sayHelloResponse xmlns:m=”http://www.openuri.org/”> <result ns0:type=”xsd:string” xmlns:ns0=”http://www.w3.org/2001/XMLSchema-instance”> T his message brought to you by Hello and the number 100 </result> </m:sayHelloResponse> 8.17. SOAP RPC Style Services M essages for SO AP RPC Style services (including EJB RPC services) can be constructed as follows: Request messages are assembled from message context variables. o T he SO AP body is built based on the SO AP RPC format (operation wrapper, parameter wrappers, and so on). o T he SO AP header is the content of the variable specified for the SO AP request header, if one is specified. o P art as element—the parameter value is the variable content. o P art as simple type—the parameter value is the string representation of the variable content. o P art as complex type—the parameter corresponds to renaming the root of the variable content after the parameter name. Response messages are assembled as follows: T he output content is the content of SOAP header, if a SO AP header is specified. P art as element—the output content is the child element of the parameter; there is at most one child element. P art as simple/complex type—the output content is the parameter itself. T o illustrate how messages are constructed during callouts to SOAP RPC Style services, look at this example with the followin g configuration: A message context variable input1 is bound to a value 100. A message context variable input2 is bound to a string value: Hello. A service callout action configured as follows: o Request Parameter intval: input1 o Request Parameter string: input2 o Response Parameter result: output1 In this scenario, the body of the outbound message to the service is shown in Listing 3-6. Listing 3-6 Content of Outbound Message <?xml version=”1.0″ encoding=”U TF-8″?> <soapenv:Envelope xmlns:soapenv=”http://schemas.xmlsoap.org/soap/envelope/”> <soapenv:Body> <sayHello2 xmlns=”http://www.openuri.org/”> <intV al>100</intVal> <string >Hello</string> </sayHello2> </soapenv:Body> </soapenv:Envelope> T he response returned by the service to which the call was made is shown in Listing 3-7. Listing 3-7 Content of Response Message From the helloWorld Service <?xml version=”1.0″ encoding=”U TF-8″?> <env:Envelope xmlns:env=”http://schemas.xmlsoap.org/soap/envelope/” xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance” xmlns:soapenc=”http://schemas.xmlsoap.org/soap/encoding/” xmlns:xsd=”http://www.w3.org/2001/XMLSchema”> <env:Header/> <env:Body env:encodingStyle=”http://schemas.xmlsoap.org/soap/encoding/”> <m:sayHello2Response xmlns:m=”http://www.openuri.org/”> <result xsi:type=”n1:HelloWorldResult” xmlns:n1=”java:”> <message xsi:type=”xsd:string”>
- 20. T his message brought to you by Hello and the number 100 </message> </result> </m:sayHello2Response> </env:Body> </env:Envelope> T he message context variable output1 is assigned the value shown in Listing 3-8. Listing 3-8 Content of Output Variable (output1) <message ns0:type=”xsd:string” xmlns:ns0=”http://www.w3.org/2001/XMLSchema-intance”> T his message brought to you by Hello and the number 100</message> 8.18. XML Services M essages for XM L services can be constructed as follows: T he request message is the content of the variable assigned for the request document. T he content of the request variable must be a single XML document. T he output document is the response message. T o illustrate how messages are constructed during callouts to XM L services, ta ke for example a service callout action configured as follows: Request Document Variable: myreq Response Document Variable: myresp A ssume also that at run time, the request document variable, myreq, is bound to the following XM L. Listing 3-9 Content of myreq Variable <sayHello xmlns=”http://www.openuri.org/”> <intV al>100</intVal> <string>Hello</string> </sayHello> In this scenario: T he outbound message payload is the value of the myreq variable, as s hown in T able 3-9. T he response and the value assigned to the message context variable, myresp, is shown inListing 3-10. Listing 3-10 Content of myresp Variable <m:sayHelloResponse xmlns:m=”http://www.openuri.org/”> <result xsi:type=”xsd:string”>T his message brought to you by Hello and the number 100 </result> </m:sayHelloResponse> 8.19. Messaging Services In the case of M essaging services: T he request message is the content of the request variable. T he content can be simple text, XM L, or binary data represented by an instance of <binary-content ref=…/> reference XM L. Response messages are treated as binary, so the response variable will contain an instance of <binary -content ref= … /> reference XM L, regardless of the actual content received. For example, if the request message context variable myreq is bound to an XM L document of the following format: <hello>there</hello>, the outbound message contains exactly this payload. T he response message context variable (myresp) is bound to a reference element similar to the following: <binary-content ref=” cid:1850733759955566502-2ca29e5c.1079b180f61.-7fd8″/> 8.20. Handling Errors as the Result of a Service Callout Y ou can configure error handling at the message flow, pipeline, route node, and stage level. T he types of errors that are received from an external service as the result of a service callout include transport errors, SOAP faults, responses that do not conform to an expected response, and so on. T he fault context variable is set differently for each type of error returned. Y ou can build your business and error handling logic based on the content of the fault variable. T o learn more about $fault, see Fault V ariable. 8.21. Transport Errors When a transport error is received from an external service and there is no error response payload returned to O racle Servic e Bus by the transport provider (for example, in the case that an HT TP 403 error code is returned), the service callout action
- 21. throws an exception, which in turn causes the pipeline to raise an error. T he fault variable in a user -configured error handler is bound to a message formatted similarly to that shown in Listing 3-11. Listing 3-11 Contents of the Oracle Service Bus fault Variable—Transport Error, no Error Response Payload <con:fault xmlns:con=”http://www.bea.com/wli/sb/context”> <con:errorC ode>BEA-380000</con:errorCode> <con:reason>Not Found</con:reason> <con:details> ……. </con:details> <con:location> <con:node>P ipelinePairNode1</con:node> <con:P ipeline>P ipelinePairNode1_request</con:Pipeline> <con:Stage>Stage1</con:Stage> </con:location> </con:fault> In the case that there is a payload associated with the transport error—for example, when an HT TP 500 error code is received from the business service and there is XML payload in the response —a message context fault is generated with the custom error code: BEA -382502. T he following conditions must be met for a BEA -382502 error response code to be triggered as the result of a response from a service—when that service uses an HT TP or JM S transport: (HT TP) T he response code must be any code other than 200 or 202. (JM S) T he response must have a property set to indicate that it is an error response—the transport metadata status code set to1 indicates an error. T he content type must be text/xml. If the service is AnySoap or WSDL -based SOAP, then it must have a SO AP envelope. T he body inside the SOAP envelope must be XM L format; it cannot be text. If the service type is AnyXML, or a messaging service of type text returns XML content with a non -successful response code (any code other than 200 or 202). If the transport is HTTP, the ErrorResponseDetail element will also conta in the HTTP error code returned with the response. T he ErrorResponseDetail element in the fault contains error response payload received from the service. Listing 3-12 shows an example of the ErrorResponseDetail element. Listing 3-12 Contents of the Oracle Service Bus fault Variable—Transport Error, with Error Response Payload <ctx:Fault xmlns:ctx=”http://www.bea.com/wli/sb/context”> <ctx:errorC ode>BEA-382502<ctx:errorCode> <ctx:reason> Service callout has received an error response from the server</ctx:reason> <ctx:details> <alsb:ErrorResponseDetail xmlns:alsb=”http://www.oracle.com/…”> <alsb:detail> <! [C DATA[ . . . ]]> </alsb:detail> <alsb:http-response-code>500</alsb:http-response-code> </alsb:ErrorResponseDetail> </ctx:details> <ctx:location>. . .</ctx:location> </ctx:Fault> Note: T he XM L schema for the service callout-generated fault is shown in XM L Schema for the Service C allout-Generated Fault Details. 8.22. SOAP Faults In case an external service returns a SOAP fault, the O racle Service Bus run time sets up the context variable $fault with a custom error code and description with the details of the fault. T o do so, the contents of the 3 elements under the <SOAP- ENV:Fault> element in the SO AP fault are extracted and used to construct an O racle Service Bus fault element. T ake for example a scenario in which a service returns the following error. Listing 3-13 SOAP Fault Returned From Service Callout <SO AP-ENV:Envelope xmlns:SOAP-ENV=”http://schemas.xmlsoap.org/soap/envelope/”> <SO AP-ENV:Body> <SO AP-ENV:Fault> <faultcode>SOAP-ENV:Client</faultcode> <faultstring>Application Error</faultstring> <detail> <message>That’s an Error!</message> <errorcode>1006</errorcode> </detail> </SO A P-ENV:Fault>
- 22. </SO A P-ENV:Body> </SO A P-ENV:Envelope> T he <faultcode>, <faultstring>, and <detail> elements are extracted and wrapped in an<alsb:ReceivedFault> element. Note that the faultcode element in Listing 3-15 contains a Q Name—any related namespace declarations are preserved. If the transport is HTTP, the ReceivedFault element will also contain the HT TP error code returned with the fault response. T he generated <alsb:ReceivedFault> element, along with the custom error code and the error string are used to construct the contents of the fault context variable, which in this example takes a format similar to that shown in Listing 3- 14. Listing 3-14 Contents of the Oracle Service Bus Fault Variable—SOAP Fault <ctx:Fault xmlns:ctx="http://www.bea.com/wli/sb/context"> <ctx:errorCode>BEA-382500<ctx:errorCode> <ctx:reason> service callout received a soap Fault response</ctx:reason> <ctx:details> <alsb:ReceivedFault xmlns:alsb="http://www.oracle.com/..."> <alsb:faultcode xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">SOAP-ENV:Clien </alsb:faultcode> <alsb:faultstring>Application Error</alsb:faultstring> <alsb:detail> <message>That’s an Error! </message> <errorcode>1006</errorcode> </alsb:detail> <alsb:http-response-code>500</alsb:http-response-code> </alsb:ReceivedFault> </ctx:details> <ctx:location> </ctx:location> </ctx:Fault> Note: T he unique error code BEA-382500 is reserved for the case when service callout actions receive SOAP fault responses. 8.23. Unexpected Responses When a service returns a response message that is not what the proxy service run time expects, a message context fault will be generated and initialized with the custom error code BEA -382501. T he details of the fault include the contents of the SO AP- Body element of the response. If the transport is HTTP, the ReceivedFault element will also contain the HTTP error code returned with the fault response. T he XM L schema definition of the service callout-generated fault details is shown in Listing 3-15. Listing 3-15 XML Schema for the Service C allout-Generated Fault Details <xs:complexType name=”ReceivedFaultDetail”> <xs:sequence> <xs:element name=”faultcode” type=”xs:QName”/> <xs:element name=”faultstring” type=”xs:string”/> <xs:element name=”detail” minO ccurs=”0″ > <xs:complexType> <xs:sequence> <xs:any namespace=”##any” minO ccurs=”0″ maxOccurs=”unbounded” processContents=”lax” /> </xs:sequence> <xs:anyAttribute namespace=”##any” processContents=”lax” /> </xs:complexType> </xs:element> <xs:element name=”http-response-code” type=”xs:int” minOccurs=”0″/> type=”xs:int” minO ccurs=”0″/> </xs:sequence> </xs:complexType> <xs:complexType name=”U nrecognizedResponseDetail”> <xs:sequence> <xs:element name=”detail” minOccurs=”0″ type=”xs:string” /> </xs:sequence> </xs:complexType> <xs:complexType name=”ErrorResponseDetail”> <xs:sequence>
- 23. <xs:element name=”detail” minOccurs=”0″ type=”xs:string” /> </xs:sequence> </xs:complexType> 8.24. Handling Errors in Message Flows T he process described in the next paragraph constitutes an error handling pipeline for the stage of an error handler. In addition, an error pipeline can be defined for a pipeline (request or response) or for an entire proxy service. T he error handler at the stage level is invoked for handling an error; If the stage -level error handler is not able to handle a given type of error, the pipeline error handler is invoked. If the pipeline -level error handler also fails to handle the error, the service-level error handler is invoked. If the service-level error handler also fails, the error is handled by the system.The following table summarizes the scope of the error handlers at various levels in the message flow. Level Scope Stage Handles all the errors within a stage. P ipeline Handles all the errors in a pipeline, along with any unhandled errors from any stage in a pipeline. Service Handles all the errors in a proxy service, along with any unhandled errors in any pipeline in a service. Note: All WS-Security errors are handled at this level. System Handles all the errors that are not handled any where else in a pipeline. Note: T here are exceptions to the scope of error handlers. For example, an exception thrown by a non -XM L transformation at the stage level is only caught by the service-level error handler. Suppose a transformation occurs that transforms XM L to M FL for an outgoing proxy service response message, it always occurs in the binding layer. T herefore, for example, if a non-XM L output is missing a mandatory field at the stage level, only a service -level error handler can catch this error. For more information on error messages and error handling, see P roxy Services: Error Handlers inUsing the Oracle Service Bus Console. Y ou can handle errors by configuring a test that checks if an assertion is true and use the reply action configured false. Y ou can repeat this test at various levels. A lso you can have an error without an error handler at a lower level and handle it throug h an error handler at an higher level in message flow. In general, it is easier to handle specific errors at a stage level of the message flow and use error handlers at the higher level for more general default processing of errors that are not handled at the lower levels. It is good practice to explicitly handle anticipated errors in the pipelines and allow the service-level handler to handle unanticipated errors. Note: Y ou can only handle WS-Security related errors at the service level. 8.25. Generating the Error Message, Reporting, and Replying A predefined context variable (the fault variable) is used to hold information about any error that occurs during message processing. When an error occurs, this variable is populated with information be fore the appropriate error handler is invoked. T he fault variable is defined only in error handler pipelines and is not set in request and response pipelines, or in route o r branch nodes. For additional information about $fault, see P redefined C ontext V ariables . In the event of errors for request/response type inbound messages, it is often necessary to send a message back to the originator outlining the reason why an error occurred. Y ou can accomplish this by using a Reply with Failure action after configuring the message context variables with the response you want to send. For example, when an HT TP message fails, Reply with Failuregenerates the HTTP 500 status. When a JM S message fails, Reply with Failure sets the JM S_BEA_Error property to true. T he O racle Service Bus error actions are discussed in P roxy Services: Error Handlers in Using the Oracle Service Bus Console. A n error handling pipeline is invoked if a service invoked by a proxy service returns a SOAP fault or transport error. A ny received SOAP fault is stored in $body, so if a Reply with Failure is executed without modifying $body, the original SOAP fault is returned to the client that invoked the service. If a reply action is not configured, the system error handler generates a new SO AP fault message. T he proxy service recognizes that a SOAP fault is returned because a HT TP error status is set, or the JM S property SERVER_Error is set to true. Some use cases require error reporting. Y ou can use the report action in these situations. For example, consider a scenario i n which the request pipeline reports a message for tracking purposes, but the service invoked by the route node fails after the reporting action. In this case, the reporting system logged the message, but there is no guarantee that the message was processed successfully, only that the message was successfully received. Y ou can use the O racle Service Bus Console to track the message to obtain an accurate picture of the message flow. T his allows you to view the original reported message indicating the message was submitted for processing, and also the subsequent reported error indicating that the message was not processed correctly. T o learn how to configure a report action and use the data reported at run time, see P roxy Services: A ctions in Using the Oracle Service Bus Console.
- 24. 8.26. Example of Action Configuration in Error Handlers T his example shows how you can configure the report and reply actions in error handlers. T he message flow shown in Figure 3- 2 includes an error handler on the validate loan application stage. T he error handler in this case is a simple message flow with a single stage configured—it is represented in the O racle Service Bus C onsole as shown in Figure 3-2. Figure 3-2 Error Handler M essage Flow T he stage is, in turn, configured with actions (replace, report, and reply) as shown in Figure 3-3. Figure 3-3 Actions in Stage Error Handler T he actions control the behavior of the stage in the pipeline error handler as follows: Replace—T he contents of a specified element of the body variable are replaced with the contents of the fault context variable. T he body variable element is specified by an XP ath expression. T he contents are replaced with the value returned by an XQ uery expression—in this case $fault/ctx:reason/text() Report— M essages from the reporting action are written to the O racle Service Bus Reporting Data Stream if the error handler configured with this action is invoked. T he JMS Reporting Provider reports the messages on the O racle Service Bus Dashboard. O racle Service Bus provides the capability to deliver message data to one or more reporting providers. M essage data is captured from the body of the message and from any other variables associated with the message, such as header or inbound variables. Y ou can use the message delivered to the reporting provider for functions such as tracking messages or regulatory auditing. When an error occurs, the contents of the fault context variable are reported. T he key name is errorCode, an d the key value is extracted from the fault variable using the following XP ath expression: ./ctx:errorCode. Key/value pairs are the key identifi ers that identify these messages in the Dashboard at run time. T o configure a report action and use the data reported at run time, see P roxy Services: A ctions in Using the Oracle Service Bus Console. Reply— A t run time, an immediate reply is sent to the invoker of the loanGateway3 proxy service (see Figure 3-3) indicating that the message had a fault T he reply is With Failure. For configuration information, see P roxy Services: Error Handlers in Using the Oracle Service Bus Console. When you do not know the service you need to invoke from the proxy service you are creating, you can use dynamic routing. For any given proxy service, you can use one of the following techniques to dynamically route messages: In a message flow pipeline, design an XQuery expression to dynamically set the fully qualified service name in O racle Service Bus and use the dynamic route or dynamic publish actions. Note: Dynamic Routing can be achieved in a route node, whereas dynamic publishing can achieved in a stage i n a request pipeline or a response pipeline. With this technique, the proxy service dynamically uses the service account of the endpoint business service to send user names and passwords in its outbound requests. For example, if a proxy service is routing a request to Business Service A , then the proxy service uses the service account from Business Service A to send user names and passwords in its outbound request. See Implementing Dynamic Routing. C onfigure a proxy service to route or publish messages to a business service. T hen, in the request actions section for the ro ute action or publish action, add a Routing O ptions action that dynamically specifies the U RI of a service. With this technique, to send user names and passwords in its outbound requests, the proxy service uses the service account of the statically defined business service, regardless of the U RI to which the request is actually sent. For information on how to use this technique, see Implementing Dynamic Routing. Note: T his technique is used when the overview of the interface is fixed. T he overview of the interface includes message types, port types, and binding, and excludes the concrete interface. T he concrete interface is the transport U RL at which the service is located. Implementing Dynamic Routing Y ou can use dynamic routing to determine the destination during the runtime of a proxy service. T o achieve this you can use a routing table in an XM L file to create an XQ uery resource. Note: Instead of using the XQuery resource, you can also directly use the XM L file from which the resource is created. A n XM L file or the Xquery resource can be maintained easily. A t runtime you provide the entry in the routing table that will determine the routing or publishing destination of the proxy service.T he XM L file or the XQ uery resource contains a routing table, which maps a logical identifier to (such as the name of a company) to the physical identifier (the fully qualified nam e of the service in O racle Service Bus). T he logical identifier, which is extracted from the message, maps on to the physical identifier, which is the name of the service you want to invoke. Note: T o use the dynamic route action, you need the fully qualified name of the service in O racle Service Bus. In a pipeline the logical identifier is obtained with an XP ath into the message.You assign the XM L table in the XQ uery resource to a variable. Y ou implement a query against the variable in the routing table to extract the physical identifier based on th e corresponding logical identifier. U sing this variable you will be able to invoke the required service. T he following sections describe how to implement dynamic routing.
- 25. Sample XM L File. C reating an XQuery Resource From the Sample XML C reating and C onfiguring the P roxy Service to Implement Dynamic Routing 8.27. Using Dynamic Routing 8.28. Sample XML File Y ou can create an XQuery resource from the following XM L file. Save this as sampleXquery.xml. Listing 3-16 Sample XML File <routing> <row> <logical>Sample</logical> <physical>default/goldservice</physical> </row> <row> <logical>ABC Corp</logical> <physical>default/silverservice</physical> </row> </routing> 8.29. Creating an XQuery Resource From the Sample XML In an active session, select P roject Explorer from the left navigation panel. T he P roject V iew page is displayed. Select the project to which you want to add the XQ uery resource. In the P roject V iew page, select the XQuery resource from the Select Resource Type drop-down list. T he C reate XQuery page is displayed. In the Resource Name field, enter the name of the resource. T his is a mandatory. In the Resource Description field, provide the a description for the resource. T his is optional. In the XQ uery field, provide the path to the XM L you are using as an XQ uery resource. C lick on Browse to locate the file. O ptionally, you can copy and paste the XML in the XQ uery field. T his is mandatory. Save the XQ uery resource. A ctivate the session. In an active session, select P roject Explorer from the left navigation panel. T he P roject V iew page is displayed. Select the project to which you want to add the proxy service. In the P roject V iew page, select the P roxy Service resource from the Select Resource T ype drop-down list. T he General C onfiguration page is displayed. In the Service Name field of the General C onfiguration page, enter the name of the proxy service. T his is mandatory. Select the type of service by clicking on the button adjacent to various types of services available under Service T ype. For more information on selecting the service type, see P roxy Services: A ctions. C lick Finish. O n the Summary page, click Save to save the proxy service. O n the P roject View page, click the Edit M essage Flow icon against the newly created proxy service in the Resource table. T he Edit M essage Flow page is displayed. C lick on the message flow to add a pipeline pair to the message flow. C lick on Request P ipeline icon select A dd Stage from the menu. C lick on the Stage1 icon to and select Edit Stage from the menu. T he Edit Stage C onfiguration page appears. C lick A dd Action icon. C hoose A dd an A ction item from the menu. C hoose the A ssign action from M essage P rocessing. C lick on Expression. T he XQuery Expression Editor is displayed. C lick on XQ uery Resources. T he browser displays the page where you can import the XQ uery resource. C lick on the Browse to locate the XQuery resource. C lick on V alidate to validate the imported XQuery resource. Save the imported XQ uery resource on successful validation. O n the Edit Stage C onfiguration page, enter the name of the variabl e in the field. T his assigns the XQuery resource to this variable. T he variable now contains the externalized routing table. C lick on the A ssign action icon to add another assign action. Note: T o do this repeat step 11 to step 13 . Enter the following Xquery:
- 26. <ctx: route> <ctx: service isProxy=’false’> {$routingtable/row[logical/text()=$logicalidentifier]/physical/text()} </ctx: service> </ctx: route> In the above code, replace $logicalidentifier by the actual XPath to extract the logical identifier from the mes sage (example from $body). C lick on V alidate to validate the Xquery. Save the Xquery on successful validation. O n the Edit Stage C onfiguration page, enter the name of the variable (for example, routeresult) in the field. T his extracts the XM L used by the dynamic route action into this variable. C lick on the message flow to add a route node to the end of the message flow. C lick on the Route Node icon and select Edit from the menu. C lick the A dd Action icon. C hoose Add an A ction item from the menu. C hoose the Dynamic Route action. C lick on Expression. T he XQuery Expression Editor is displayed. Enter the variable from step 22 (for example, $routeresult) O racle Service Bus provides read-access to databases from proxy services without requiring you to write a custom EJB or custom Java code and without the need for a separate database product like Oraclce Data Service Integrator. Y ou can use the execute-sql() function to make a simple JDBC call to a database to perform simple database reads. A ny SQL query is legal, from a query that gets a single tax rate for the supplied location to a query that does a complex join to obtain an order’s current status from several underlying database tables. A database query can be used to get data for message enrichment, for routing decisions, or for customizing the behavior of a proxy service. T ake for example a scenario in which an O racle Service Bus proxy service receives “request for quote” messages. T he proxy service can route the requests based on the customer’s priority to one of a number of quotation business services (say, standard, gold, or platinum level services). T he proxy service can then perform a SQ L-based augmentation of the results that those services return—for example, based on the selected ship method and the weight of the order, the shipping cost can be looked up and that cost added to the request for quote message. fn-bea:execute-sql() describes the syntax for the function and provides examples of its use. T he execute -sql() function returns typed data and automatically translates values between SQL/JDBC and XQ uery data models. Y ou can store the returned element in a user-defined variable in an O racle Service Bus message flow. T he following databases and JDBC drivers are supported using the execute-sql() function: IBM DB2/NT 8 M icrosoft SQL Server 2000, 2005 O racle 8.1.x O racle 9.x, 10.x P ointbase 4.4, 5.x Sybase 12.5.2 and 12.5.3 WebLogic T ype 4 JDBC drivers T hird-party drivers supported by WebLogic Server U se non-XA drivers for datasources you use with the fn-bea:execute-sql() function—the function supports read-only access to the datasources. WARNING: In addition to specifying a non-XA JDBC driver class to use to connect to the database, you must ensure that you disable global transactions and two-phase commit. (Global transactions are enabled by default in the WebLogic Server console for JDBC data sources.) T hese specifications can be made for your data source via the WebLogic Server A dministration C onsole. See C reate JDBC Data Sources in the WebLogic Server Administration Console Online Help. For complete information about database and JDBC drivers support in O racle Service Bus, see Supported Database C onfigurations in Supported Configurations for Oracle Service Bus . Databases other than the core set described in the preceding listing are also supported. However, for the core databases list ed above, the XQ uery engine does a better recognition and mapping of data types to XQ uery types than it does for the non-core databases—in some cases, a core database’s proprietary JDBC extensions are used when fetching data. For the non -core databases, the XQ uery engine relies totally on the standard type codes provided by the JDBC driver and standard JDBC resultset access methods. When designing your proxy service, you can enter XQ ueries inline as part of an action definition instead of entering them as resources. Y ou can also use inline XQueries for conditions in If…T hen… actions in message flows. For information about using the inline XQ uery editor, seeCreating Variable Structure M appings. T he message context is a set of variables that hold message context and information about messages as they are routed through the O racle Service Bus. T ogether, the header, body, and attachments variables, (referenced as $header, $body and $attachments in XQuery statements) represent the message as it flows through O racle Service Bus. T he canonical form of the message is SOAP. Even if the service type is not SOAP, the message appears as SOAP in the O racle Service Bus message context. In a M essage C ontext, $header contains a SOAP header element and $body contains a SOAP Body element. T he Header and Body elements are qualified by the SOAP 1.1 or SOAP 1.2 namespace depending on the service type of the proxy service. A lso
- 27. in a M essage C ontext, $attachments contains a wrapper element called attachments with one child attachment element per attachment. T he attachment element has a body element with the actual attachment. When a message is received by a proxy service, the message contents are used to initialize the header, body, and attachments variables. For SOAP services, the Header and Body elements are taken directly from the envelope of the received SOAP message and assigned to $header and $body respectively. For non-SOAP services, the entire content of the message is typically wrapped in a Body element (qualified by the SOAP 1.1 namespace) and assigned to $body, and an empty Header element (qualified by the SO AP 1.1 namespace) is assigned to $header. Binary and M FL messages are initialized differently. For M FL messages, the equivalent XML document is inserted into the Body element that is assigned to $body. For binary messages, the message data is stored internally and a piece of reference XML is inserted into the Body element that is assigned to $body. T he reference XML looks like <binary-content ref=”…”/>, where “…” contains a unique identifier assigned by the proxy service. T he message context is defined by an XM L schema. Y ou must use XQuery expressions to manipulate the context variables in the message flow that defines a proxy service. T he predefined context variables provided by O racle Service Bus can be grouped into the following types: M essage-related variables Inbound and outbound variables O peration variable Fault variable For information about the predefined context variables, see P redefined C ontext Variables. T he $body contains message payload variable. When a message is dispatched from O racle Service Bus you can decide the variables, whose you want to include in the outgoing message. T hat determination is dependent upon whether the target endpoint is expecting a SO AP or a non-SOAP message: For a binary, any text or XM L message content inside the Body element in $body is sent. For M FL messages, the Body element in $body contains the XM L equivalent of the M FL document. For text messages, the Body element in $body contains the text. For text attachments, the body element in $attachments contains the text. If the contents are XM L instead of simple text, the XM L is sent as a text message. For XM L messages, the Body element in $body contains the XM L. For XM L attachments, the body element in $attachments contains the XM L. SO AP messages are constructed by wrapping the contents of the header and body variables inside a <soap:Envelope> element. (T he SOAP 1.1 namespace is used for SO AP 1.1 services, while the SO AP 1.2 namespace is used for SO AP 1.2 services.) If the body variable contains a piece of reference XML, it is sent.T hat is the referenced content is not substituted in the message. For non-SOAP services, if the Body element of $body contains a binary -content element, then the referenced content stored internally is sent ‘as is’, regardless of the target service type. For more information, see M essage C ontext. T he types for the message context variables are defined by the message context schema (M essageContext.xsd). When working with the message context variables in the O racle XQuery M apper, you need to reference M essageContext.xsd, which is available in a JA R file, O RACLE_HOME/osb_10.3/lib/sb-schemas.jar, and the transport-specific schemas, which are available at O RACLE_HOME/osb_10.3/lib/transports/ where O RACLE_HOME represents the directory in which you installed O racle Service Bus. T o learn about the message context schema and the transport specific schemas, see M essage C ontext Schema. C onsider the following guidelines when you want to inspect or alter the message context: In an XQ uery expression, the root element in a variable is not present in the path in a reference to an element in that variable. For example, the following XQ uery expression obtains the C ontent-Description of the first attachment in a message: $attachments/ctx:attachment[1]/ctx:content-Description T o obtain the second attachment $attachments/ctx:attachment[2]/ctx:body/* A context variable can be empty or it can contain a single XML element or a string value. However, an XQ uery expression often returns a sequence. When you use an XQ uery expression to assign a value to a variable, only the first element in the sequence returned by the expression is stored as the variable value. For example, if you want to assign the value of a WS -A ddressing M essage ID from a SO AP header (assuming there is one in the header) to a variable named idvar, the assign action specification is: assign data($header/wsa:messageID to variable idvar Note: In this case, if two WS-A ddressing M essageID headers exist, the idvar variable will be assigned the value of the first one. T he variables $header, $body, and $attachments are never empty. However, $header can contain an empty SOAP Header element, $body can contain an empty SOAP Body element, and $attachments can contain an empty attachment element. In cases in which you use a transformation resource (XSLT or XQuery), the transformation resource is defined to transform the document in the SO AP body of a message. T o make this transformation case easy and efficient, the input p arameter to the transformation can be an XQ uery expression. For example, you can use the following XQuery expression to feed the business document in the Body element of a message ($body) as input to a transformation: $body/* [1]
- 28. T he result of the transformation can be put back in $body with a replace action. T hat is replace the content of $body, which is the content of the Body element. For more information, see XQuery Transformations and XSL T ransformations in Using the Oracle Service Bus Console. In addition to inserting or replacing a single element, you can also insert or replace a selected sequence of elements using an insert or replace action. Y ou can configure an XQ uery expression to return a sequence of elements. For example, you can use insert and replace actions to copy a set of transport headers from $inbound to $outbound. For information on adding an action, see “A dding an A ction” in P roxy Services: A ctions in Using the Oracle Service Bus Console. For an example, see C opying JMS P roperties From Inbound to O utbound. C opying JMS P roperties From Inbound to O utbound It is assumed that the interfaces of the proxy services and of the invoked business service may be different. T herefore, O rac le Service Bus does not propagate any information (such as the transport headers and JMS properties) from the inbound vari able to the outbound variable. T he transport headers for the proxy service’s request and response messages are in $inbound and the transport headers for the invoked business service’s request and response are in $outbound. For example, the following XQ uery expression can be used in a case where the user-defined JMS properties for a one-way message (an invocation with no response) need to be copied from inbound message to outbound message: U se the transport headers action to set $inbound/ctx:transport/ctx:request/tp:headers/tp:user-header as the first child of: ./ctx:transport/ctx:request/tp:headers in the outbound variable. T o learn how to configure the transport header action, see: “T ransport Headers” in P roxy Services: Actions in Using the Oracle Service Bus Console. Working with V ariable Structures T he following sections describe U sing the Inline XQuery Expression Editor U sing V ariable Structures C reating Variable Structure Mappings O racle Service Bus allows you to import XQueries that have been created with an external tool such as the Oracle XQuery M apper. Y ou can use these XQueries anywhere in the proxy service message flow by binding the XQ uery resource input to an Inline XQuery, and binding the XQ uery resource output to an action that uses the result as the input; for example, the assign , replace, or insert actions. However, you can enter the XQ uery inline as part of the action definition instead of entering the XQ uery as a resource. Y ou can also use Inline XQueries for the condition in an If…T hen… action. U se the Inline XQuery Expression Editor to enter simple XQueries that consist of the following: Fragments of XM L with embedded XQueries. Simple variable paths along the child axis. Note: For more complex XQueries, it is recommended that you use the XQ uery M apper, especially if you are not familiar with XQ uery. Inline XQueries can be used effectively to: C reate variable structures by using the Inline XQuery Expression Editor. See U sing Variable Structures. Extract or access a business document or RPC parameter from the SO AP envelope elements in $header or $body. Extract or access an attachment document in $attachments. Set up the parameters of a service callout action by extracting it from the SO AP envelope. Insert the result parameter of a service callout action into the SOAP envelope. Extract a sequence from the SO AP envelope to drive a for loop. U pdate an item in the sequence in a for loop with an U pdate action. Note: Y ou can also use the Inline XQuery Expression Editor to create variable structures. For more information, see U sing V ariable Structures. O racle Service Bus allows you to import XQueries that have been created with an external tool such as the Oracle XQuery M apper. Y ou can use these XQueries anywhere in the proxy service message flow by binding the XQ uery resource input to an inline XQ uery, and binding the XQ uery resource output to an action that uses the result as the action input; for example, the assign, replace, or insert actions. However, you can enter the XQuery inline as part of the action definition instead of ente ring the XQ uery as a resource. Y ou can also use inline XQueries for the condition in an If…T hen… action. T he inline XQ uery and XP ath 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. Y ou can also enter the path expressions manually. Y ou 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 XM L 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.
- 29. T o learn more about creating variable structures, s ee C reating V ariable Structure M appings. T o learn more about XQ uery engine support and the relationship with the O racle Data Servic e Integrator functions and operators, see XQuery Implementation. Y ou typically use the Inline XQuery Expression Editor to enter simple XQueries that consist of the following: Fragments of XM L with embedded XQueries. Simple variable paths along the child axis. Note: For more complex XQueries, we recommend that you use the O racle XQuery M apper, an editor with drag -and-drop functionality. See T ransforming Data U sing the XQ uery M apper inTransforming Data Using the XQuery Mapper. Examples of good uses of inline XQ ueries are: Extract or access a business document or RPC parameter from the SO AP envelope elements in $header or $body. Extract or access an attachment document in $attachments. Set up the parameters of a service callout by extracting it from the SO AP envelope. Fold the result parameter of a service callout into the SOAP envelope. Extract a sequence from the SO AP envelope to drive a for loop. U pdate an item in the sequence in a for loop with an U pdate action. Y ou can also use the Inline XQuery Expression Editor to create variable structures. For more information, see U sing V ariable Structures. Y ou can use the Inline XQuery Expression Editor to create variable structures, with which you defin e the structure of a given variable for design purposes. For example, it is easier to browse the XP ath variable in the console rather than viewing the X M L schema of the XP ath variable. Note: It is not necessary to create variable structures for your runtime to work. V ariable structures define the structure of the variable or the variable path but do not create the variable. V ariables are created at runtime as the target of the assign ac tion in the stage. In a typical programming language, the scope of variables is static. T heir names and types are explicitly declared. T he variable can be accessed anywhere within the static scope. In O racle Service Bus, there are some predefined variables, but you can also dynamically create variables and assign value to them using the assign action or using the loop variable in the for-loop. When a value is assigned to a variable, the variable can be accessed anywhere in the proxy service message flow. T he variable type is not declared but the type is essentially the underlying type of the value it contains at any point in time. Note: T he scope of the for-loop variable is limited and cannot be accessed outside the stage. When you use the Inline XQ uery Expression Editor, the XQuery has zero or more inputs and one output. Becaus e you can display the structure of the inputs and the structure of the output visually in the Expression Editor itself, you do not need to open the XM L schema or WSDL resources to see their structure when you create the Inline XQuery. T he graphical structu re display also enables you to drag and drop simple variable paths along the child axis without predicates, into the composed XQ uery. Each variable structure mapping entry has a label and maps a variable or variable path to one or more structures. T he scope of these mappings is the stage or route node. Because variables are not statically typed, a variable can have different structur es at different points (or at the same point) in the stage or route node. T herefore, you can map a variable or a variable path to multiple structures, each with a different label. T o view the structure, select the corresponding label with a drop -down list. Note: Y ou can also create variable structure mappings in the Inline XPath Expression Editor. However, although the variable or a variable path is mapped to a structure, the XP aths generated when you select from the structure are XP aths relative to the variable. A n example of a relative XPath is ./ctx:attachment/ctx:body. T he following sections describe how to create several types of variable structure mappings: Sample WSDL C reating the Resources Y ou Need for the Examples Example 1: Selecting a P redefined Variable Structure Example 2: C reating a V ariable Structure T hat M aps a V ariable to a T ype Example 3: C reating a V ariable Structure that M aps a V ariable to an Element Example 4: C reating a V ariable Structure T hat M aps a V ariable to a C hild Element Example 5: C reating a V ariable Structure that M aps a V ariable to a Business Service Example 6: C reating a V ariable Structure T hat M aps a C hild Element to A nother C hild Element
- 30. 8.39. Creating Variable Structure Mappings 8.39.1. Sample WSDL T his sample WSDL is used in most of the examples in this section. Y ou need to save this WSDL as a resource in your configuration. For more information, see C reating the Resources Y ou Need for the Examples. Listing 3-17 Sample WSDL <definitions name=”samplewsdl” targetNamespace=”http://example.org” xmlns=”http://schemas.xmlsoap.org/wsdl/” xmlns:s0=”http://www.oracle.com” xmlns:s1=”http://example.org” xmlns:soap=”http://schemas.xmlsoap.org/wsdl/soap/”> <types> <xs:schema attributeFormDefault=”unqualified” elementFormDefault=”qualified” targetNamespace=”http://www.oracle.com” xmlns:xs=”http://www.w3.org/2001/XMLSchema”> <xs:element name=”P O” type=”s0:POType”/> <xs:complexType name=”POType”> <xs:all> <xs:element name=”id” type=”xs:string”/> <xs:element name=”name” type=”xs:string”/> </xs:all> </xs:complexType> <xs:element name=”Invoice” type=”s0:InvoiceType”/> <xs:complexType name=”InvoiceType”> <xs:all> <xs:element name=”id” type=”xs:string”/> <xs:element name=”name” type=”xs:string”/> </xs:all> </xs:complexType> </xs:schema> </types> <message name=”POTypeMsg”> <part name=”P O ” type=”s0:POType”/> </message> <message name=”InvoiceTypeMsg”> <part name=”InvReturn” type=”s0:InvoiceType”/> </message> <portT ype name=”P OPortType”> <operation name=”GetInvoiceType”> <input message=”s1:POTypeMsg”/> <output message=”s1:InvoiceTypeMsg”/> </operation> </portT ype> <binding name=”P O Binding” type=”s1:POPortType”> <soap:binding style=”rpc” transport=”http://schemas.xmlsoap.org/soap/http”/> <operation name=”GetInvoiceType”> <soap:operation soapAction=”http://example.com/GetInvoiceType”/> <input> <soap:body use=”literal”/> </input> <output> <soap:body use=”literal”/> </output> </operation> </binding> </definitions> 8.40. Creating the Resources YouNeed for the Examples T o make use of the examples that follow, you save the sample WSDL as a resource in your configuration and create the sample business service and proxy service that use the sample WSDL. T he instructions that follow tell how to accomplish the tasks in the O racle Service Bus Console: Save the WSDL as a Resource
- 31. C reate a P roxy Service T hat Uses the Sample WSDL Build a M essage Flow for the Sample P roxy Service C reate a Business Service T hat U ses the Sample WSDL 8.41. Save the WSDL as a Resource 1. In the left navigation pane in the O racle Service Bus Console, under C hange C enter, click Create to create a new session for making changes to the current configuration. 2. In the left navigation pane, click P roject Explorer. 3. In the P roject V iew page, click the project to which you want to add the WSDL. 4. In the P roject V iew page, in the C reate Resource field, select WSDL under Interface. 5. In the C reate a New WSDL Resource page in the Resource Name field, enter SampleWSDL. T his is a required field. 6. In the WSDL field, copy and paste the text from the sample WSDL into this field. Note: T his is a required field. 1. C lick Save. T he new WSDL SampleWSDL is included in the list of resources and saved in the current session. Y ou must now create a proxy service that uses this WSDL, see C reate a P roxy Service T hat U ses the Sample WSDL. 2. In the left navigation pane, click P roject Explorer. 3. In the P roject V iew page, select the project to which you want to add the proxy service. 4. In the P roject V iew page, in the C reate Resource field, select Proxy Service under Service. 5. In the Edit a P roxy Service – General Configuration page, in the Service Name field, enter P roxywithSampleWSDL. T his is a required field. 6. In the Service T ype field, which defines the types and packaging of the messages exchanged by the service: 1. Select WSDL Web Service from under C reate a New Service. 2. C lick Browse. T he WSDL Browser is displayed. 3. Select SampleWSDL, then select POBinding in the Select WSDL Definitions pane. 4. C lick Submit. 5. Keep the default values for all other fields on the General C onfiguration page, then click Next. 6. Keep the default values for all fields on the T ransport C onfiguration page s, then click Next. 7. In the O peration Selection C onfiguration page, make sure SOAP Body T ype is selected in the Selection Algorithm field, then click Next. 8. Review the configuration data that you have entered for this proxy service, then click Save. T he new proxy service P roxywithSampleWSDL is included in the list of resources and saved in the current session.To build message flow for this proxy service, see Build a M essage Flow for the Sample P roxy Service. 9. In the P roject V iew page, in the A ctions column, click the Edit M essage Flow icon for the P roxywithSampleWSDL proxy service. 10. In the Edit M essage Flow page, click the P roxywithSampleWSDL icon, then click A dd Pipeline P air. P ipelinePairNode1 is displayed, which includes request and response pipelines. 11. C lick the Request P ipeline icon, then click Add Stage. T he Stage Stage1 is displayed. 12. C lick Save. T he basic message flow is created for the P roxywithSampleWSDL proxy service. 13. In the left navigation pane, click P roject Explorer. T he P roject V iew page is displayed. 14. Select the project to which you want to add the business service. 15. From the P roject View page, in the C reate Resource field, select Business Service from under Service. T he Edit a Business Service – General Configuration page is displayed. 16. In the Service Name field, enter BusinesswithSampleWSDL. T his is a required field. 17. In the Service T ype field, which defines the types and packaging of the messages exchanged by the service, do the following: 1. Select WSDL Web Service from under C reate a New Service. 2. C lick Browse. T he WSDL Browser is displayed. 3. Select SampleWSDL, then select POBinding in the Select WSDL Definitions pane. 4. C lick Submit. 5. Keep the default values for all other fields on the General C onfiguration page, then click Next. 6. Enter an endpoint U RI in the Endpoint URI field on the T ransport C onfiguration page. C lick A dd, and then click Next. 7. U se the default values for all fields on the SO AP Binding Configuration page. C lick Next. 8. Review the configuration data that you have entered for this business service, and then click Save. T he new business service BusinesswithSampleWSDL is included in the list of resources and is saved in the current session. 9. From the left navigation pane, click Activate under C hange Center. T he session ends and the configuration is deployed to run time. Y ou are now ready to use the examples—continue in Example 1: Selecting a P redefined V ariable Structure. 8.42. Create a Proxy Service That Uses the Sample WSDL 8.43. Build a Message Flow for the Sample Proxy Service 8.44. Create a Business Service That Uses the Sample WSDL 8.45. Example 1: Selecting a Predefined Variable Structure In this example, you select a predefined variable structure using the proxy service ProxyWithSampleWSDL, which has a service type WSDL Web Service that uses the binding P OBinding from SampleWS DL.
- 32. T he proxy service message flow needs to know the structure of the message in order to manipulate it. T o achieve this, O racle Service Bus automatically provides a predefined structure that maps the body variable to the SOAP body structure as defined by the WSDL of the proxy service for all the messages in the interface. T his predefined structure mapping is labeled body. Note: T his predefined structure is also supported for messaging services with a typed interface. T o select a predefined variable structure: In the V ariable Structures panel on the XQ uery Expression Editor page, select body from the drop -down list of built-in structures. T he variable structure body is displayed in Figure 3-4. Figure 3-4 Variable Structures—body 8.46. Example 2: Creating a Variable Structure That Maps a Variable to a Type Suppose the proxy service ProxyWithSampleWSDL invokes a service callout to the business service BusinessWithSampleWSDL, which also has a service type WSDL Web Service that uses the binding POBinding from SampleWSDL. T he operation GetInvoiceType is invoked. In this example, the message flow needs to know the structure of the response parameter in order to manipulate it. T o achieve this, you can create a new variable structure that maps the response parameter variable to the type InvoiceType. T o map a variable to a type: 1. In the V ariable Structures panel, click Add New Structure. A dditional fields are displayed in Figure 3-5. Figure 3-5 Variable Structures—Add a New Structure 1. Select the XM L T ype. 2. In the Structure Label field, enter InvoiceType as the display name for the variable structure you want to create. T his displ ay name enables you to give a meaningful name to the structure so you can recognize it at design time but it has no impact at run time. 3. In the Structure Path field, enter $InvoiceType as the path of the variable at run time. 4. T o select the type InvoiceType, do the following: 1. U nder the T ype field, select the appropriate radio button, then select WSDL Type from the drop-down list. 2. C lick Browse. T he WSDL Browser is displayed. 3. In the WSDL Browser, select SampleWSDL, then select InvoiceType under T ypes in the Select WSDL Definitions pane. 4. C lick Submit. InvoiceType is displayed under your selection WSDL T ype. 5. C lick A dd. T he new variable structure InvoiceType is included under XM L T ype in the drop -down list of variable structures. T he variable structure InvoiceType is displayed in Figure 3-6. Figure 3-6 Variable Structures—InvoiceType 8.47. Example 3: Creating a Variable Structure that Maps a Variable to an Element Suppose a temporary variable has the element Invoice described in the SampleWSDL WSDL. In this example, the P roxyWithSampleWSDL message flow needs to access this variable. T o achieve this, you can create a new variable structure that maps the variable to the element Invoice. T o map a variable to an element: 1. In the V ariable Structures panel, click Add New Structure. 2. M ake sure you select the XM L T ype. 3. In the Structure Label field, enter Invoice as the meaningful display name for the variable structure you wan t to create. 4. In the Structure Path field, enter $Invoice as the path of the variable structure at run time. 5. T o select the element Invoice, do the following: 1. For the T ype field, make sure you select the appropriate radio button.Then select WSDL Element from the drop-down list. 2. C lick Browse. 3. In the WSDL Browser, select SampleWSDL, then select Invoice under Elements in the Select WSDL Definitions pane. 4. C lick Submit. Invoice is displayed under your selection WSDL Element. 5. C lick A dd. T he new variable structure I nvoice is included under XM L Type in the drop-down list of variable structures. T he variable structure Invoice is displayed in Figure 3-7. Figure 3-7 Variable Structures—Invoice 8.48. Example 4: Creating a Variable Structure That Maps a Variable to a Child Element T he P roxyWithSampleWSDL proxy service routes to the document style Any SOAP business service that returns the P urchase O rder in the SO AP body. In this example, the P roxyWithSampleWSDL proxy service message flow must then manipulate the response. T o achieve this, you can create a new structure that maps the body variable to the P O element, and specify the PO element as a child element of the variable. Y ou need to specify it as a child element because the body variable contains the SO AP Body element and the P O element is a child of the Body element. T o map a variable to a child element:
- 33. 1. In the V ariable Structures panel, click Add New Structure. 2. M ake sure you select the XM L T ype. 3. In the Structure Label field, enter body to P O as the meaningful display name for the variable structure you want to create. 4. In the Structure Path field, enter $body as the path of the variable structure at run time. 5. T o select the PO element: 1. U nder the T ype field, make sure you select the appropriate radio button, and then select WSDL Element from the drop -down list. 2. C lick Browse. 3. In the WSDL Browser, select SampleWSDL, then select PO under Elements in the Select WSDL Definitions pane. 4. C lick Submit. 5. Select the Set as child checkbox to set the PO element as a child of the body to P O variable structure. 6. C lick A dd. T he new variable structure body to P O is included under XM L T ype in the drop -down list of variable structures. T he variable structure body to PO is displayed in Figure 3-8. Figure 3-8 Variable Structures—body to PO 8.49. Example 5: Creating a Variable Structure that Maps a Variable to a Business Service T he P roxyWithSampleWSDL proxy service routes the message to the BusinessWithSampleWSDL business service, which also has a service type WSDL Web Service that uses the binding POBinding from SampleWSDL. In this example, the message flow must then manipulate the response. T o achieve this, you can define a new structure that maps the body variable to the BusinessWithSampleWSDL business service. T his results in a map of the body variable to the SO AP body for all the messages in the WSDL interface of the service. Note: T his mapping is also supported for messaging services with a typed interface. T o map a variable to a business service: 1. In the V ariable Structures panel, click Add New Structure. 2. Select Service Interface. 3. In the Structure Label field, enter BusinessService as the meaningful display name for the variable structure. 4. In the Structure Path field, $body is already set as the default. T his is the path of the variable structure at run time. 5. T o select the business service, do the following: 1. U nder the Service field, click Browse. T he Service Browser is displayed. 2. In the Service Browser, select the BusinessWithSampleWSDL business service, then click Submit. T he business service is displayed under the Service field. 3. In the O peration field, select All. 4. C lick A dd. T he new variable structure BusinessService is included under Service Interface in the drop -down list of variable structures. T he variable structure BusinessService is displayed in Figure 3-9. Figure 3-9 Variable Structures—Business Service 8.50. Example 6: Creating a Variable Structure That Maps a Child Element to Another Child Element M odify the SampleWSDL so that the P roxyWithSampleWSDL proxy service receives a single attachment. T he attachment is a P urchase Order. In this example, the proxy service message flow must then manipulate the P urchase O rder. T o achieve this, you can define a new structure that maps the body element in $attachments to the P O element, which is specified as a child element. T he body element is specified as a variable path of the form: $attachments/ctx:attachment/ctx:body Y ou can select and copy the body element from the predefined attachments structure, paste this element as the variable path to be mapped in the new mapping definition. T o map a child element to another child element: 1. In the V ariable Structures panel, select attachments from the drop-down list of built-in structures. T he variable structure attachments is displayed in Figure 3-10. Figure 3-10 Variable Structures—attachments 1. Select the body child element in the attachments structure. T he variable path of the body element is displayed in the P ropert y Inspector on the right side of the page: $attachments/ctx:attachment/ctx:body 1. C opy the variable path of the body element. 2. In the V ariable Structures panel, click Add New Structure. 3. Select the XM L T ype. 4. In the Structure Label field, enter PO attachment as the meaningful display name for this variable structure. 5. In the Structure Path field, paste the variable path of the body element: $attachments/ctx:attachment/ctx:body
- 34. T his is the path of the variable structure at run time. 1. T o select the PO element: 1. U nder the T ype field, make sure the appropriate radio button is selected, then select WSDL Element. 2. C lick Browse. 3. In the WSDL Browser, select SampleWSDL, then select PO under Elements in the Select WSDL Definitions pane. 4. C lick Submit. 5. Select the Set as child checkbox to set the PO element as a child of the body element. 6. C lick A dd. T he new variable structure PO attachment is included under XM L Type in the drop-down list of variable structures. 7. If there are multiple attachments, add an index to the reference when you use fields from this structured variable in your XQ ueries. For example, if you drag the P O field to the XQ uery field, but as P O will be the second attachment, change the inserted value from $attachments/ctx:attachment/ctx:body/oracle:PO/oracle:id to $attachments/ctx:attachment[2]/ctx:body/oracle:PO/oracle:id 8.51. Quality of Service T he following sections discuss quality of service features in O racle Service Bus messaging: Delivery Guarantees O utbound M essage Retries 8.52. Delivery Guarantees O racle Service Bus supports reliable messaging. When messages are routed to another service from a route node, the default quality of service (Q oS) is exactly once if the proxy service transport is defined as JM S/XA; otherwise best effort Q oS is supported. Q uality of service is set in the qualityOfService element in the $outbound context variable. T he following delivery guarantee types are provided in O racle Service Bus, shown in T able 3-9. Delivery Reliability Description Exactly once 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. Exactly once means reliability is optimized. 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. T he default value of the qualityOfService element is exactly -once for a route node action for the following inbound transports: e-mail FT P File JM S/XA § SFT P § T ransactional T uxedo Note: Do not retry the outbound transport when the QoS is exactly once A t least once 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 time-out, a failure to connect, or a broken communication link. If failover U RLs are specified,at least once semantics is provided with respect to at least one of the U RLs. At least once delivery semantics is attempted if exactly once is not possible but the qualityOfService element is exactly-once. Best effort Best effort means that there is no reliable messaging and there is no elimination of duplicate messages —however, performance is optimized. It is performed if the qualityOfService element is best-effort. Best effort delivery is also performed if exactly once and at least once delivery semantics are not possible but the qualityOfService element is exactly-once. T he default value of the qualityOfService element for a route node is best-effort for the following inbound transports: HT TP JM S/nonXA Non-T ransactional Tuxedo
- 35. T he default value of the qualityOfService element is always best-effort for the following: Service callout action — always best-effort, but can be changed if required. P ublish action — defaults to best-effort, modifiable Note: When the value of the qualityOfService element is best-effort for a publish action, all errors are ignored. However, when the value of the qualityOfService element is best-effort for a route node action or a Service callout action, any error will raise an exception. For more detailed information about quality of service for other transports, see the documentation for the transport, at O racle Service Bus T ransports. 8.53. Overriding the Default Element Attribute T o 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 M essage C ontext Schema. Y ou can override the default qualityOfService element attribute for the following: Route node action P ublish action Service callout T o override the qualityOfService element attribute, you must use the route options action to route or publish, and also select the checkbox for a service callout action. See M essage C ontext Schema. 8.54. Delivery Guarantee Rules T he delivery guarantee supported when a proxy service publishes a message or routes a request to a business service depends on the following conditions: T he value of the qualityOfService element. T he inbound transport (and connection factory, if applicable). T he outbound transport (and connection factory, if applicable). However, if the inbound proxy service is a Local T ransport and is invoked by another proxy service, the inbound transport of the invoking proxy service is responsible for the delivery guarantee. T hat is because a proxy service that invokes another proxy service is optimized into a direct invocation if the transport of the invoked proxy service is a Local T ransport. For m ore information on transport protocols, see P roxy Services and Business Services in Using the Oracle Service Bus Console. Note: No delivery guarantee is provided for responses from a proxy service. T he following rules govern delivery guarantees, shown in T able 3-10. Delivery Guarantee P rovided Rule Exactly once T he proxy service inbound transport is transactional and the value of the qualityOfService element is exactly-once to an outbound JM S/XA transport. At least once T he proxy service inbound transport is file, FTP, or e-mail and the value of the qualityOfService element is exactly-once. At leastonce T he proxy service inbound transport is transactional and the value of the qualityOfService element, where applicable, is exactly-once to an outbound transport that is not transactional. No delivery guarantee A ll other cases, including all response processing cases. Note: T o support at least once and exactly-once delivery guarantees with JM S, you must exploit JMS transactions and configure a retry count and retry interval on the JM S queue to ensure that the message is redelivered in the event of a server crash or a failure that is not handled in an error handler with a Reply or Resume action. File, FT P, and e -mail transports also internally use a JM S/XA queue. T he default retry count for a proxy serv ice with a JM S/XA transport is 1. For a list of the default JM S queues created by O racle Service Bus, see the O racle Service Bus Deployment Guide. T he following are additional delivery guarantee rules: If the transport of the inbound proxy service is File, FTP, e-mail, T ransactional T uxedo, or JM S/XA, the request processing is performed in a transaction. o When the qualityOfService element is set to exactly-once, any route node and publish actions executed in the request flow to a transactional destination are performed in the same transaction. o When the qualityOfService element is set to best-effort for any action in a route node, service callout or publish actions are executed outside of the request flow transaction. Specifically, for JM S, T uxedo, T ransactional T uxedo, or EJB transport, the request flow transaction is s uspended and the T ransactional T uxedo work is done without a transaction or in a separate transaction that is immediately committed. o If an error occurs during request processing, but is caught by a user error handler that manages the error (by using the resume or reply action), the message is considered successfully processed and the transaction commits. A transaction is
- 36. aborted if the system error handler receives the error—that is, if the error is not handled before reaching the system level. T he transaction is also aborted if a server failure occurs during request pipeline processing. If a response is received by a proxy service that uses a JM S/XA transport to business service (and the proxy inbound is not T ransactional T uxedo), the response processing is performed in a single transaction. When the qualityOfService element is set to exactly-once, all route, service callout, and publish actions are performed in the same transaction. When the qualityOfService element is set to best-effort, all publish actions and service callout actions are executed outside of the response flow transaction. Specifically, for JM S, EJB, or transactional Tuxedo types of transports, the response flow transaction is suspended and the service is invoked without a transaction or in a separate transaction that is immediately committed. P roxy service responses executed in the response flow to a JM S/XA destination are always performed in the same transaction, regardless of the qualityOfService element setting. If the proxy service inbound transport is transactional T uxedo, both the request processing and response processing are done in this transaction. Note: Y ou will encounter a run-time error when the inbound transport is transactional Tuxedo and the outbound is an asynchronous transport, for example, JM S/XA. 8.55. Threading Model T he O racle Service Bus threading model works as follows: T he request and response flows in a proxy service execute in different threads. Service callouts are always blocking. A n HTTP route or publish action is non-blocking (for request/response or one-way invocation), if the value of the qualityOfService element is best-effort. JM S route actions or publish actions are always non-blocking, but the response is lost if the server restarts after the request is sent because Oracle Service Bus has no persistent message processing state. Note: In a request or response flow publish action, responses are always discarded because publish actions are inherently a one-way message send. 8.56. Splitting Proxy Services Y ou may want to split a proxy service in the following situations: When HT TP is the inbound and outbound transport for a proxy service, you may want to incorporate enhanced reliability into the middle of the message flow. T o enable enhanced reliability in this way, split the proxy service into a front -end HTTP proxy service and a back-end JMS (one-way or request/response) proxy service with an HT TP outbound transport. In the event of a failure, the first proxy service must quickly place the message in the queue for the second proxy service, in order to avoid loss of messages. T o disable the direct invocation optimization for a non-JM S transport when a proxy service, say loanGateway1 invokes another proxy service, say loanGateway2. Route to the proxy service loanGateway2 from the proxy service loanGateway1 where the proxy service loanGateway2 uses JMS transport. T o have an HT T P proxy service publish to a JM S queue but have the publish action rollback if there is a exception later on in the request processing, split the proxy service into a front-end HTTP proxy service and a back-end JMS proxy service. T he publish action specifies a qualityOfService element of exactly-once and uses an XA connection factory. 8.57. Outbound Message Retries In addition to configuring inbound retries for messages using JMS, you can configure outbound retries and load balancing. Load balancing, failover, and retries work in conjunction to provide performance and high availability. For each message, the list of U RLs you provide as failover U RLs is automatically ordered based on the load balancing algorithm into a failover sequence. If the retry count is N, the entire sequence is retried N time s before stopping. T he system waits for the specified retry interval before commencing subsequent loops through the sequence. A fter completing the retry attempts, if there is still an error, the error handler pipeline for the route node is invoked. For more information on the error handler pipeline, see “A dding P ipeline Error Handling” in P roxy Services in Using the Oracle Service Bus Console. Note: For HT TP transports, any HTTP status other than 200 or 202 is considered an error by O racle Service Bus and must be retried. Because of this algorithm, it is possible that O racle Service Bus retries errors like authentication failure that ma y never be rectified for that U RL within the time period of interest. O n the other hand, if O racle Service Bus also fails over to a different U RL for subsequent attempts to send a given message, the new U RL may not give the error. Note: For quality of service=exactly once failover or retries will not be executed.
- 37. 8.58. Content Types, JMS Type, and Encoding T o support interoperability with heterogeneous endpoints, O racle Service Bus allows you to control the content type, the JM S type, and the encoding used. O racle Service Bus does not make assumptions about what the external client or service needs, but uses the information configured for this purpose in the service definition. O racle Service Bus derives the content type for outbound messages from the service type and interface. C ontent type is a part of the e-mail and HT TP protocols. If the service type is: XM L or SO AP with or without a WSDL, the content type is text/XML. M essaging and the interface is M FL or binary, the content type is binary/octet -stream. M essaging and the interface is text, the content type is text/plain. M essaging and the interface is XML, the content type is text/XML. A dditionally, there is a JM S type, which can be byte or text. Y ou configure the JM S type to use when you define the servi ce in O racle Service Bus C onsole or in the O racle Service Bus P lug-ins for Workshop for WebLogic. Y ou can override the content type in the outbound context variable ($outbound) for proxy services invoking a service, and in the inbound context variable ($inbound) for a proxy service response. For more information on $outbound and $inbound context variables, see Inbound and O utbound V ariables. Encoding is also explicitly configured in the service definition for all outbound messages. For more information on service definitions, see P roxy Services in and Business Service in Using the Oracle Service Bus Console. 8.59. Throttling Pattern In O racle Service Bus, you can restrict the message flow to a business service. T his technique of restricting a message flow to a business service is known as throttling. For information, seeThrottling in O racle Service Bus in the Oracle Service Bus Operations Guide. 8.60. WS-I Compliance O racle Service Bus provides Web Service Interoperability (WS -I) compliance for SOAP 1.1 services in the run-time environment. T he WS-I basic profile has the following goals: Disambiguate the WSDL and SOAP specifications wherever ambiguity exists. Define constraints that can be applied when receiving messages or importing WSDLs so that interoperability is enhanced. When messages are sent, construct the mes sage so that the constraints are satisfied. T he WS-I basic profile is available at the following U RL: http://www.ws -i.org/P rofiles/BasicProfile-1.1.html. When you configure a proxy service or business service based on a WSDL, you can use the O racle Service Bus Console or the O racle Service Bus P lug-ins for Workshop for WebLogic to specify whether you want O racle Service Bus to enforce WS -I compliance for the service. For information on how to do this, see “O peration Selection Configuration page” under P roxy Services in Using the Oracle Service Bus Console “ P roxy Service Operation Selection C onfiguration page” in Using the Oracle Service Bus Plug-ins for Workshop for WebLogic When you configure WS-I compliance for a proxy service, checks are performed on inbound request messages received by that proxy service. When you configure WS-I compliance for an invoked service, checks are performed when any proxy receives a response message from that invoked service. O racle recommends that you create an error handler for these errors, since by default, the proxy service SOAP client receives a system error handler-defined fault. For more information on creating fault handlers, see: P roxy Services: Error Handlers in Using the Oracle Service Bus Console. A dding and C onfiguring Error Handlers in M essage Flows in Using the Oracle Service Bus Plug-ins for Workshop for WebLogic. For messages sent from a proxy service, whether as outbound request or inbound response, WS -I compliance checks are not explicitly performed. T hat is because the pipeline designer is responsible for generati ng most of the message content. However, the parts of the message generated by O racle Service Bus should satisfy all of the supported WS -I compliance checks. T his includes the following content: Service invocation request message. System-generated error messages returned by a proxy service. HT TP status codes generated by a proxy service.
- 38. 8.61. WS-I Compliance Checks Note: WS-I compliance checks require that the system knows what operation is being invoked on a service. For request messages received by a proxy service, that means that the context variable $operation should not be null. T hat depends upon the operation selection algorithm being configured properly. For response messages received from invoked services, the operation should be specified in the action configurations for route, publish, and service callout. When you configure WS-I compliance checking for a proxy service or a business service, O racle Service Bus carries out the following checks, shown in T able 3-11. C heck WS-I Basic Profile Details O racle Service Bus Description 3.1.1 SOAP Envelope Structure R9980 An Envelope must conform to the structure specified in SO AP 1.1, Section 4, “SOAP Envelope” (subject to amendment). T his check applies to request and response messages. If a response message is checked and the message does not possess an outer Envelope tag, a soap:client error is generated. If the message is an Envelope tag but possesses a different namespace, it is handled by the 3.1.2 SOAP Envelope Namespace. 3.1.2 SOAP Envelope Namespace R1015 A Receiver must generate an error if they encounter an envelope whose document element is not soap:Envelope. T his check applies to request and response messages and is related to the 3.1.1 SOAP Envelope Structure. If a request message has a local name of Envelope, but the namespace is not SO AP 1.1, a soap:VersionMismatch error is generated. 3.1.3 SOAP Body Namespace Q ualification R1014 The child elements of the soap:body element in an Envelope must be namespace qualified. T his check applies to request and response messages. A ll request error messages generate a soap:Client error. 3.1.4 Disallowed C onstructs R1008 An Envelope must not contain a Document T ype Declaration. T his check applies to request and response messages. A ll request error messages generate a soap:Client error. 3.1.5 SOAP T railers R1011 An Envelope must not have any child elements of soap:Envelope following the soap:body element. T his check applies to request and response messages. A ll request error messages generate a soap:Client error. 3.1.9 SOAP attributes on SO AP 1.1 elements R1032 The soap:Envelope, soap:header, and soap:body elements in an Envelope must not have attributes in the namespacehttp://schemas.xmlsoap.org/soap/envelope/ T his check applies to request and response messages. A ny request error messages generate a soap:client error. 3.3.2 SOAP Fault Structure R1000 When an Envelope is a fault, the soap:Fault element must not have element children other than faultcode, faultstring, faultactor, and detail. T his check only applies to response messages. 3.3.3 SOAP Fault Namespace Q ualification R1001 When an Envelope is a Fault, the element children of the soap:Fault element must be unqualified. T his check only applies to response messages. 3.4.6 HTTP C lient Error Status C odes R1113 An instance should use a “400 Bad Request” HTTP status code if a HT TP request message is malformed. R1114 An instance should use a “405 M ethod not A llowed” HTTP status code if a HT TP request message is malformed. R1125 An instance must use a 4xx HTTP status code for a response that indicates a problem with the format of a request. O nly applies to responses for a proxy service where you cannot influence the status code returned due to errors in the request. 3.4.7 HTTP Server Error Status C odes R1126 An instance must return a “500 Internal Server Error” HTTP status code if the response envelope is a fault. T his check applies differently to request and response messages. For request messages, any faults generated have a 500 Internal Server Error HT TP status code. For response messages, an error is generated if fault responses are received that do not have a 500 Internal Server Error HT TP status code.
- 39. 4.7.19 Response Wrappers R2729 An envelope described with an rpc -literal binding that is a response must have a wrapper element whose name is the corresponding wsdl:operation name suffixed with the string Response. T his check only applies to response messages. O racle Service Bus never generates a non-fault response from a proxy service. 4.7.20 Part A ccessors R2735 An envelope described with an rpc -literal binding must place the part accessor elements for parameters and return value in no namespace. R2755 The part accessor elements in a message described with an rpc-literal binding must have a local name of the same value as the name attribute of the corresponding wsdl:part element. T his check applies to request and response messages. A ny request error messages generate a soap:client error. 4.7.22 Required Headers R2738 An envelope must include all soapbind:headers specified on a wsdl:input or wsdl:output of a wsdl:operation of a wsdl:binding that describes it. T his check applies to request and response messages. A ny request error messages generate a soap:client error. 4.7.25 Describing SO APAction R2744 A HTTP request message must contain a SOAPAction a HTTP header field with a quoted value equal to the value of the soapAction attribute of soap:operation, if present in the corresponding WSDL description. R2745 A HTTP request message must contain a SOAP action a HT TP header field with a quoted empty string value, if in the corresponding WSDL description, the SO APAction of soapbind:operation is either not present, or present with an empty string as its value. T his check applies to request messages and a soap:client error is returned. References: 1) Oracle docs 2) W3shcools 3) Developmentcookbook