SOA 11g - SOAP WebServices with Attachments (SwA) Tutorial
Developer Summary
Expertise level - medium
Familiarity needed - development exposure on oracle Fusion Middleware tools like like SOA Suite 11g, OSB 11g, Weblogic Server, etc. Good exposure to WebService standards, WebServices styles and uses needed. Some familiarity with XML and XSD schemas.
Technologies / Tools used
- Weblogic Server 10.3.6
- SOA Suite 11.1.1.6
- JDeveloper 11.1.1.6
Detailed steps
This tutorial goes about creating two 11g SCA composites
SwA-Provider - a SCA composite that exposes a WS interface, which when called returns a payload and an attachment. This composite is to illustrate 'how to develop a WS with attachments'.
SwA-Receiver - a SCA composite that calls SwA-Provider composite and receives an attachment. This composite is to illustrate 'how to develop a WS that consumes a WS with attachments'. Well, as part of its function this composite returns that attachment to the caller, and hence this also illustrates developing a SwA WS, but thats not the focus for this composite.
Functionally, both these services receives an EmployeeId as input, and returns an employee details that contains just the EmployeeId and EmployeeName (and even this is hardcoded). This is kept trivial to focus the tutorial on SwA part.
Developing SwA-Provider
1. Develop a schema SwA-Provider.xsd that contains an EmployeeType complex type that contains EmployeeId and EmployeeName as their elements.
2. Create a JDeveloper project using this schema, take the EmployeeId as input and return some hardcoded EmployeeName. Or, stuff more non-trivial functional code if you wish to.
3. Quickly test and make sure that this part is good. Below is a snapshot indicate the Req/Resp message structure that we are talking about:
3. Now lets make this a SwA WS. Edit the WSDL to add another part to the Response message. Accordingly modify the "Binding" definition to include multipart MIME.
Note that, the new part added is defined as 'element' and not as 'type' -and define this element attachmentElement as xsd:base64Binary with in the same WSDL with in 'wsdl:types'.
Note - Technically, it is feasible to define this part as 'type' also. But if we do, the WS 'may be' identified by the runtime as 'RPC' styled web service, which is not widely used. In our tutorial, we are developing these WebServices as 'Doc' style and 'literal' use which is the most widely used variant.
Define/Update the binding info: In line with the Response message modification, define/update the binding info to indicate multipart MIME, as shown in the figure.
(When the BPEL is created, binding info may not have been generated in the WSDL, and if so, need to add all the binding info. If it already exists then wsdl:output to be modified to reflect multipart MIME)
Now, this WSDL reflects as SwA WebService.
4. Lets add a .doc file in the project in the same directory as composite.xml. This doc subsequently used to send [hard-coded] attachment to the caller as part of response message.
5. Read this doc content with ora:readBinaryFromFile() and assign it to the attachment part.
Now this reads the doc as binary and assigns it to the attachment part of response message.
6. Test this service to make sure we are getting the attachment in the response:
Double click should open the doc.
However there was some issue with passing the doc as MIME type 'application/octet-stream', and finally it seems reaching the soapUI as text/plain, hence its trying to open the attachment in text editor. Save the attachment in .doc file and open it in MSWord, then it it looks as follows (or depending on content that you have placed it in the doc)
and, the composite trace should look something like below (only 'href' can be seen, not the content of the attachment):
Developing SwA-Receiver
Now that we have developed the provider service, lets walk through the details of consuming such a SwA WebService. For this, lets develop SwA-Receiver, a 11g SCA composite that calls the SwA-Provider composite developed above, and gets the returned attachment, and returns the same attachment to its caller.
1. Develop a new JDeveloper SOA project 'SwA-Receiver', with trivial functionality of getting Employee info as explained above.
2. For getting the Employee Info, we call SwA-provider from this composite (unlike hard coding in the SwA-Provider composite), and assigns the values we receive from the SwA-Provider to the output of SwA-Receiver output.
Up to here its like normal SCA composite development.
Test up to here to ensure that the connectivity to the SwA-Provider composite is fine.
3. Now, lets modify the WSDL of SwA-Receiver BPEL in a similar way explain above for SwA-Provider composite, so that we have
- Additional part created in response message which defined as 'element' of type base64Binary defined in the same WSDL
- Create/Modify the binding to add multipart MIME, where attachment part content is defined with type as 'application/octet-stream'.
4. Along with assigning the payload of SwA-Provider output to the SwA-Receiver output, assign the attachment part also.
5. Test this from soapUI to get the attachment:
As explained in the development of SwA-Provider, here too, somehow 'Content type' is coming as 'text/plain' though it is set explicitly as 'application/octet-stream'. I will debug this later. For now, we need to save this attachment as .doc file and open with MSWord, instead of double clicking on the attachment line in soapUI.
Source Code
Source code of 11g SCA composite can be downloaded from here
Hi Srinivas,
ReplyDeleteI am trying to send document from multipart which is part of input i am not able to get any response. when i checked with multipart in soap tool. it is recognizing multipart in soap header but not in the body.
That was awesome, thanks for the details explanation
ReplyDeletecan we create SOA web service which transfer pdf as attachment to the caller service
ReplyDeleteYes, it is feasible.
DeleteThere are good Enterprise 'Use cases' for this pattern of exposing a document as a WebService, instead of sharing a file location and asking the caller to read from there.