Service-oriented architecture (SOA) applications often require application-related data associated with the Extensible Markup Language (XML) files used in the application. For example, a picture of an employee could be associated with an employee’s resume or financial data files could be associated with an application that analyzes financial records. One effective way to pass that associated data is through a Simple Object Access Protocol (SOAP) attachment. From a development perspective, attachments add adaptability and better performance to your applications, which translates into more usable applications.
Attachments let your applications request types of files your users might associate with your application by adapting your application to their particular environment. Since the setup and handling of attachments is done through IBM® WebSphere Integration Developer Version V7.0 tools, you add a significant value to your own application with a minimum development cost to you. There is also a performance benefit to using attachments. The binary data that forms the attachment itself is separate from the SOAP message body so it is not parsed as part of a message, eliminating an expensive processing overhead.
In this article, three types of attachments are defined: explicitly bound attachments, referenced attachments using swaRef-typed elements, and unreferenced attachments. The following sections show how to set up interfaces and bindings that use attachments through tools in WebSphere Integration Developer V7.0 (hereafter called Integration Developer). You are also shown how to test applications that use attachments in a test environment.
Types of attachments
An attachment is data that is associated with an application; that is, it is “attached” to a message used by the application. Three types of attachments are supported in Integration Developer:
- Explicitly bound attachment: An explicitly bound attachment is an attachment that is modeled as a Web Services Description Language (WSDL) part and that is bound as a Multipurpose Internet Mail Extension (MIME) part in a WSDL SOAP binding. In the SOAP envelope, there is no element to provide a reference to the attachment, which is outside of the SOAP envelope. Therefore, there is no part element in the SOAP body. Explicitly bound attachments are defined in the WS-I Usage Scenarios for the WS-I Attachments Profile 1.0. The World Wide Web Consortium (W3C) describes how to refer to an attachment from a SOAP message in detail in its SOAP Messages with Attachments specification.
- Referenced attachment using swaRef-typed elements: A
referenced attachment using an swaRef (SOAP with
attachments Reference) element is an attachment that uses the
attachment type (
wsi:swaRef) defined by WS-I. There is a reference in the SOAP body to the attachment. The attachment is outside the SOAP body, though modeled within the WSDL file. Referenced attachments are defined in the WS-I Usage Scenarios for the WS-I Attachments Profile 1.0. WS-I describes a swaRef element in its Attachments Profile specification.
- Unreferenced attachment: An unreferenced attachment does not have a reference in the SOAP body to the attachment. It is your responsibility to ensure the client sends the format that the server expects and vice-versa. An unreferenced attachment is a special case and requires you to code and maintain the code rather than the tools in Integration Developer.
WSDL binding styles and bindings used with attachments
A binding style determines how a service is bound to a messaging protocol like SOAP. It is also called a WSDL style and an encoding style. For more information about this subject, see Which WSDL style should I use? The binding style is set at the operation level of an interface in Integration Developer.
You must use a document literal non-wrapped binding style or Remote Procedure Call (RPC) literal binding style with the operation that will pass an attachment if you are using an explicitly bound attachment. However, you can use either a document literal non-wrapped or document literal wrapped binding style with the referenced attachment with a swaRef-typed element. Document literal wrapped is the default binding style in Integration Developer.
A binding takes data from a format in one environment and converts it into the format used in another environment. In SOA applications using attachments, this means converting between the data format used by a Web service to the data format used by an SOA application and vice versa. For attachments, you must use the Java™ API for XML Web Services (JAX-WS) binding with either a SOAP 1.2/HTTP or SOAP 1.1/HTTP protocol.
At runtime, an attachment enters an application with a message through either an import or export with a Web services binding. This message and attachment are typically from a Web service or client. The attachment is separate from the SOAP envelope as shown in Figure 1.
Figure 1. Relationship of services, modules, and attachments
A mediation flow may be used to process the attachment, as shown in Figure 1. For example, a mediation flow can reduce the size of a photo before the photo is sent on to the application.
Developing applications using attachments
In this article, we will focus on explicitly bound attachments and referenced attachments using the swaRef-typed element. You will add support in your application for either of these kinds of attachments by following this process:
- First, create an interface that will use attachments. The interface we will create is for a security application. We will send the name of an employee with a photo, which will be an attachment, and receive a response that verifies that the name and photo are correct. The response will also include the photo as a response.
- Next, add an operation to the interface and specify the correct binding style to support an attachment to an application.
- Create the input and output parameters for the operation. These inputs and outputs include binary types (base64Binary or hexBinary) or the swaRef type that represent attachments. In our case, an input and an output parameter will be used for the photo, which is an attachment.
- Finally, add the interface to an export or import. Exports and imports are the components used to exchange data between external applications, such as Web services and SCA applications. Then, you will add the binding to the export or import. In our application, we will use an export.
Create an interface for an application using an explicitly bound attachment
The following steps show you how to create an interface with an operation that will pass an attachment when invoked:
- In the Business Integration view of your module, right-click
Interfaces and select New > Interface from
the menu. Name the interface
EmployeeCheckand click Finish.
- In the interface editor, beside Operations, select the Add
Request Response Operation icon. Note that when you make the
selection, you can now change the binding style as shown in Figure 2.
Figure 2. Changing the binding style
- Change the binding style to document literal non-wrapped.
Rename the operation to
verifyRecord. Rename the input to
namewith a type of string. Rename the output to
nameVerifiedwith a type of string. Note that if you had already created this operation and inputs and outputs, you would use a refactor function. Refactoring in Integration Developer changes the elements specified and all their references.
- Add another input by using the Add Input icon. This will be
for the attachment. Note that the editor assumes that you are adding
an attachment and selects a type of base64Binary. Change the
photo. You could also have selected a hexBinary type. Add another output by using the Add Output icon. This will also be for an attachment. Change the name to
photoVerifiedas shown in Figure 3. Save your work.
Figure 3. Interface with explicitly bound attachment
- Select photo and open the Properties view. Click
Add beside the Binary content type field. From the
dialog box, select image/gif from the menu. Click OK.
Click Add again and add image/jpeg (Figure 4), as you
might send a photo in either format.
Figure 4. Selecting binary content type
- Repeat the previous step for the photoVerified parameter. Save your work and close the interface editor.
Add the interface and binding to an export
The following steps show you how to add the interface and binding to an export:
- Integration Developer V7.0 has made creating exports and imports
easy. You simply drag an export or import from a palette and drop it
onto the assembly editor canvas. Under Inbound Exports, select
Web Service and drag it onto the canvas of the assembly
editor as shown in Figure 5.
Figure 5. Selecting the Web service binding
- In the Select an Interface dialog box, choose the EmployeeCheck interface. In the Select a Transport Protocol dialog box, select SOAP1.2/HTTP. You could also have selected SOAP1.1/HTTP. Click Finish. The export is created and placed on the canvas. Rename the export EmployeeCheck. Save your work.
To test if your attachments are working at runtime, echo the attachments passed in as input in the output, which can be done through a mediation flow component. In the sample code that is available with this article, look at the mediation flow that we created. It includes a mediation flow and a business process. You can now create a similar mediation flow to test your own applications with the attachments.
Working with the sample code
To work with the sample code, download it to a directory and follow these steps:
- Start WebSphere Integration Developer Version 7.0.
- Select File > Import from the menu.
- In the Import window, select Other > Project Interchange. Click Next.
- Click Browse beside the From zip file field and navigate to the sample code (attachments.zip). Select it and click Open.
- Click Select All and Finish.
- The code for the testing section of this article is added to the Business Integration view.
Using the sample code, test your referenced attachments as follows:
- Start the server by right-clicking WebSphere Process Server and selecting Start.
- Right-click the running server and select Add and Remove Projects. Click Add All > Finish.
- Open the assembly diagram in the EmployeeInformation module.
- Right-click the EmployeeCheck export and select Test Component.
- In the Value editor under Body, open the string field in the Value column and add Donna Dedicated.
- In the base64Binary field, open the Browse for File dialog box. Since only a JPG data type image was added in the sample, change the Files of type field to *.jpg. In the EmployeeInformation > employeephotos path, select DonnaDedicated.jpg and click Finish. Note that the attachment must be in your current workspace.
- Click the Continue icon as shown in Figure 6.
Figure 6. Selecing the Continue icon
- The test environment uses the endpoint URL in the binding WSDL code. The default endpoint has a port number of 9080. If your runtime is installed on another port number, you will receive a runtime exception. If you do, check the port number by expanding Web Service Ports in your module and opening the code in the WSDL editor.
- Accept the default server (WebSphere Process Server v7.0) and click Finish. Accept the default userid and password in the login dialog box and click OK. If you have changed these settings, use your own userid and password.
- In the Return parameters section, Donna Dedicated appears in the NameVerified field. In the PhotoVerified field, you will see many random characters representing binary data when you hover over the field. If you have an image viewer such as Microsoft® Office Picture Manager, right-click the Value field, select View Source > View Raw Data, and select your image viewer to see the image. Alternately, you can select the returned Binding element in the Events pane and then click View SOAP Attachment in the Value editor.
- In the Events pane, note the attachment to inline element in the request and the inline to attachment element in the response. They are part of a mediation flow that is described later in this article. Figure 7 shows the result of the test.
- When finished with testing, close the test you ran. Remove the
projects from the server in a similar manner by adding them with
Removal All and stop the server.
Figure 7. Test client with explicitly bound attachment
Under the covers
Looking under the covers at the interface, which you can do in Integration Developer by opening the interface with the WSDL editor, you will notice some code that may seem surprising. Listing 1 shows multiple elements for each type. Listing 2 shows that each WSDL message has two WSDL parts and each part refers to a global element. Examining the message element, you will notice that the attachment corresponds to a part, not an element, and there are multiple parts although a correct WSDL has only one part per message. A Multipurpose Internet Mail Extension (MIME) content tag identifies the image attachment.
Because we are using the document literal non-wrapped binding style instead
of the document literal wrapped binding style typically used in
Integration Developer, we see this unexpected code. In the case of an
export, the interface editor will refer to the attachment parameter as
photo, but the test editor will refer to it as
VerifyRecordInputParameter1, as shown in
Listing 1. Multiple elements for each type
Listing 2. Multiple parts in a message
Though an explicitly bound attachment will work, it appears unconventional. For example, the attachment field has to be represented as a WSDL part even though in many cases the attachment field cannot be modeled as a WSDL part. The attachment is nested as an XML Schema Definition (XSD) element. However, a referenced attachment cannot find it if it were nested there. The following section addresses how the swaRef-typed element created by the WS-I organization can use an attachment more properly.
Creating a referenced attachment with a swaRef-typed element
The swaRef-typed attachment is used when an attachment conforms to the swaRef-typed element WS-I specification. In a large corporation, where this WS-I specification on attachments is a corporate standard or in an application spanning several corporations, use of the swaRef-typed element might be a requirement.
swaRef is an XML type for attachments. Because it is an XML type, you can use it with complexTypes like business objects and used with the document literal wrapped binding style, which is the most common binding style for WSDL files. In a nutshell, with a swaRef-typed element, attachments become another standard WS-I element in the schema.
The steps to create an application that uses a referenced attachment with the swaRef-typed element are:
- Integration Developer has provided a predefined resource that will
help you get up and running with this WS-I specification. To use this
predefined resource, open the Dependencies section of your
module and expand Predefined Resources. Select WS-I
attachment profile 1.0: swaRef schema file as shown in Figure
8. Save your work and close the dependency editor.
Figure 8. Selecting the swaRef schema file
- Once you add this predefined resource, a swaRef type is created for
use in your application. Create an interface as before, but leave the
binding style as document literal wrapped. Create the same
operation and inputs and outputs, but select swaRef as the type
for the photo and photoVerified inputs and outputs as
shown in Figure 9. You do not need to define a binary content
Figure 9. Interface with a referenced attachment using a swaRef-typed element
- Add the interface and binding to an export as before.
Testing your attachments at runtime is similar to the previous test. However, when you make the file selection for the swaRef field, the test client will let you select any type of file as it cannot determine the field type. After running, the content identifier (cid) is shown as the returned value. Since the test client cannot determine the type, it cannot view it in an image viewer.
However, you can show or save the image as a JPG by selecting the response Binding event, and in the Value editor by selecting icons for viewing or saving the attachment (Figure 10). Hover help tells you that you can View SOAP Attachment or Save SOAP Attachment.
Figure 10. Test client with a referenced attachment using a swaRef-typed element
Under the covers
Let's look at the schema using a swaRef-type element for your attachments. Unlike explicitly bound attachments, there are complexType elements, which include the swaRef type as that you expect in the WSDL code (Listing 3).
Listing 3. complexTypes contain swaRef types
Unlike an explicitly bound attachment, it has a document literal wrapped style. Only one part is present in a WSDL message as shown in Listing 4.
Listing 4. WSDL message contains only one part
Using a swaRef-type element for an attachment results in WSDL XML code that conforms to the WS-I open standard specification. For example, your attachment content is not divided into multiple parts as in explicitly bound attachments. The differences between explicitly bound attachments and referenced attachments using the swaRef-type element are explained in Web programming tips and tricks: Attachments using the wsi:swaRef XML type from WSI.
Using mediation flows to manipulate attachments
A mediation flow is used to transform messages and helpful when some additional processing is needed related to attachments. In the sample code, you will notice that we have included a mediation flow with the EmployeeInformation and EmployeeInformationswaRef modules. In these modules, an attachment is sent to a business process.
However, a business process will actually only receive the reference to the attachment in the WSDL code, not the attachment itself. We needed to be certain that the attachment was sent to the business process in the request and the processed attachment was returned to the application. Therefore, we used a mediation flow to make the attachment an inline schema for the business process.
Look in the EmployeeInformation module under the Integration Logic > Mediation Flows folders, and double-click the TestHarness mediation flow to open it. Under the Request tab, double-click attachment to inline to see the mapping we created for a request. We mapped the operation1Parameters0 and verifyRecordInputParameter1 elements to the id and image elements in the Service Message Object (SMO) passed to the business process. Mapping is done by dragging a visual handle from an element on one side to another element on the other side as shown in Figure 11.
Figure 11. Mediation flow request
In the Response tab of the mediation flow, you can see how the attachment that has been verified by the application is now passed back in a similar way. In this case, verified_id and verified_image are returned as the operation1Parameters0 and verifyRecordInputParameter1 elements to the calling service. Note that you do not map verified_id and verified_image to the elements under attachments, as you might expect. Instead, you must use assign activities. In particular, you must assign a value as shown in Figure 12 for the bodyPath element to have your attachment returned in the response as expected.
Figure 12. Mediation flow response
We have focused on the mediation flow for explicitly bound attachments. A mediation flow for a referenced attachment with a swaRef element is different. To see the custom mediation created for the EmployeeInformationswaRef module, open the mediation flow. In the Request section, select attachment to inline. Then select the Properties tab and the Details tab within the Properties view. Browse the Java code to see how the mediation flow was handled for the case with a swaRef element.
Testing applications with attachments in test suites
Serious testing of SOA applications means building many test cases over time and dividing them into sets of logically-related test suites that are run continuously. As more of your applications make use of attachments to pass data, you can incorporate these applications into the mix of test suites run by the test suite editor, where attachments are also supported.
The attachment test suite example shown in Figure 13 is included with the sample code in this article. To run this test yourself, expand the SwAComponentTest component test project. Under Test Suites > TestSuite > AttachmentTests, use the Ctrl button and select all tests. Right-click the selected tests you created and select Run Test. Using the continue function as before, run the suite of tests.
As discussed earlier in the testing of referenced attachments, check the port number of your runtime for each test case if you receive an exception stating that the endpoint URL is incorrect.
Figure 13. Attachments in test suite
Unreferenced attachments and security
Unreferenced attachments, that is, ones with no reference in the SOAP body to an attachment, are permitted in Integration Developer. However, it is your responsibility to create, test, and maintain them manually. Since unreferenced attachments are not modeled in the WSDL or WSDL binding, it is your responsibility to ensure that the client and server send and receive documents in the agreed format. Your application must determine which WSDL files contain attachments and you must have a way to remove and process them.
Though a Web Services Security (WS-Security) policy set can be applied when using attachments, privacy or integrity settings will not apply to the attachment data. To secure the entire message when working with attachments, use the transport level security using HTTPS instead of HTTP. Then the entire HTTP message, including attachments, will be secure.
An attachment is usually a large file so a good programming practice is to not use it in your application until it is needed; instead, use a token to represent it.
At the time this article was written, there were some limitations when using attachments in Integration Developer V7.0.
Explicitly bound attachments:
- The Message Transmission Optimization Mechanism (MTOM) message feature is currently not supported.
- An export with a JAX-WS binding and either a SOAP 1.2/HTTP or a SOAP 1.1/HTTP transport cannot be used in the same module as an export with a JAX-RPC binding with a SOAP 1.1/HTTP transport.
- Mixed type of WSDL is not supported.
- Create a mediation flow similar to the one shown in this article when an attachment is used with a business process. This technical note explains one consequence if a mediation flow is not used.
- Even if you define binary parts in a WSDL message and bind them to MIME parts in the WSDL definition, the corresponding attachments are not automatically created when messages are sent by an import or export in the response. You need to map attachments into the header explicitly using a mediation flow. This technical note explains this unexpected problem when using binary message parts.
A referenced attachment with a swaRef-typed element has similar restrictions with these differences:
- An interface operation is not restricted to only a document literal non-wrapped or RPC literal binding style.
- Input and or output type is swaRef.
Using attachments in your SOA applications can add adaptability to them while also improving performance. In this article, we have discussed the different types of attachments you can use and the open-source specifications these attachments are based on. The article also described the tools in WebSphere Integration Developer V7.0 to help you quicky and simply develop and test an application with attachments. We provided some sample applications for you to try out yourself. If you have been considering adding attachments to your applications, but waiting for the tools to help you out, today is the time to start your implementation.
- WebSphere Business Process Management V7 Information Center
- WS-I Usage Scenarios for the WS-I Attachments Profile 1.0
- Web Services Interoperability (WS-I) Organization SOAP Messages with Attachments
- Web Services Interoperability (WS-I) Organization Attachments Profile specifications
- Which WSDL style should I use?
- Attachments using the wsi:swaRef XML type from WSI