XDS.b Implementation
This page is a placeholder for future XDS.b Implementation Notes
Rruggeri 15:49, 26 July 2007 (CDT)
If the Profile Implementation Template is useful feel free to use it. If not, feel free to improve it. :-))
kevino 12:26, 27 July 2007 (PDT)
Generating Proxies using SOAP Tools
There are some general guidelines to follow when generating proxies, especially for complex WSDL/schemas such as the ones included in XDS.b, that will make your life much, much easier.
The first one is use generic, non-strongly typed WSDL for development purposes, that is for the purpose of generating the proxy.
Strongly typed WSDL will force the infrastructure to go through all the xml type definitions and generate classes for them. The mapping between XSD and object oriented constructs is not always straightforward and you might run into some problems even with valid instances.
This approach works well for your average weather web service, but not for more complex scenarios like the ones we have to deal with.
Furthermore, generating classes through proxies will force turning the XML in the SOAP message to objects where most likely you will have to deal with the XML anyways. This step can also be somewhat resource intensive as it forces a validation of the whole message which is usually avoided in production environments with high transaction volume.
Generic WSDL for development replace the types of the input/output SOAP messages with generic xs:any types. By generating the proxy from that modified WSDL you get a method signature that basically only deals with raw XML documents for input and output. Yes, you lose "automatic" XSD validation, but you can always put that step back in if you want and make it optional when you go to production.
Transition from MTOM to MTOM/XOP
The XDS.b supplement, as published, documents the use of the MTOM [standard]. Now that the testing season has started, we have found that this choice of standards is not appropriate. This section documents the reason for the change and the necessary updates to the XDS.b supplement. This material will be formatted as a formal Change Proposal to the XDS.b profile later this season. These change will be in effect for January 2008 North American Connectathon.
Choice of Standards
In many ways XDS.b is a technology update to the original XDS (now called XDS.a). The move from SOAP with Attachments to MTOM is part of this update. In selecting MTOM as the replacement we thought we were tracking the industry correctly. The real situation is slightly more complicated. There are two relevant standards here, [MTOM] and [XOP] ([XOP FAQ]). As originally published, XDS.b references MTOM without XOP. This update changes that to be MTOM with XOP. This change is being made for the following reasons:
- In common/casual usage, from my own informal survey, the term MTOM is used to mean MTOM with XOP
- It is pretty hard to find discussion of MTOM without XOP.
- The following packages are known to support MTOM/XOP: Apache Axis2, .NET. My informal survey of web-available material indicates the same for JBOSS and Oracle.
- Several sites document performance issues when using MTOM without XOP when used with large attachments. From and XDS point of view this means large documents. I believe this comes from using XML parsers that are not optimized for dealing with such large text nodes within the XML. More on this below where I discuss technology issues.
- .NET ([documentation]) uses a strategy of using MTOM for small documents and MTOM/XOP for large documents.
Change Proposal
The following changes are proposed for the Provide and Register Document Set-b transaction:
- The Document Source actor may send either MTOM or MTOM/XOP formats.
- The Document Repository actor shall accept both MTOM and MTOM/XOP formats.
The following changes are proposed for the Retrieve Document Set transaction:
- The Document Repository actor may send either MTOM or MTOM/XOP formats.
- The Document Consumer actor shall accept both MTOM and MTOM/XOP formats.
Discussion of Standards
To understand this change one needs to understand parts of MTOM, XOP, and SOAP with Attachments standards.
Soap with Attachments (SwA) uses mime/multipart structure. The top level wrapper for this standard looks like:
MIME-Version: 1.0 Content-Type: Multipart/Related; boundary=MIME_boundary; type=text/xml Content-Description: XDS.a example using SOAP with Attachments --MIME_boundary Content-Type: text/xml; charset=UTF-8 Content-Transfer-Encoding: 8bit <?xml version='1.0' ?> <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Body> <!-- Metadata Goes Here --> ... <ExtrinsicObject id="mydocument" /> ... </SOAP-ENV:Body> </SOAP-ENV:Envelope> --MIME_boundary Content-Type: text/xml Content-ID: <mydocument> document contents --MIME_boundary--
This is how XDS.a works. The id attribute of each ExtrinsicObject element is available as a multipart Part. The id attribute corresponds with the Content-ID value (angle brackets required). If the document is base64 encoded then additional headers in the mydocument part header assert that.
MTOM takes a radically different approach. This is what is documented in the XDS.b profile as it stands now. The same example looks like:
MIME-Version: 1.0 Content-Type: type=text/xml Content-Description: XDS.b example using MTOM <?xml version='1.0' ?> <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Body> <!-- Metadata Goes Here --> ... <ExtrinsicObject id="mydocument" /> ... <Document id="mydocument">base64 encoded document contents</Document> ... </SOAP-ENV:Body> </SOAP-ENV:Envelope>
This encoding does not use a multipart. The base64 encoded bits of the document are transmitted as a text node which is a child of the <Document/> element.
MTOM/XOP looks a little like both of the above.
MIME-Version: 1.0
Content-Type: Multipart/Related; boundary=MIME_boundary; type=text/xml
Content-Description: MTOM/XOP example
--MIME_boundary
Content-Type: text/xml; charset=UTF-8
Content-Transfer-Encoding: 8bit
Content-ID: <claim061400a.xml@claiming-it.com>
<?xml version='1.0' ?>
<SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Body>
<!-- Metadata Goes Here -->
...
<ExtrinsicObject id="mydocument" />
...
<Document id="mydocument">
<Include href="cid:1.urn:uuid:BC47538ED684E0A2D41194546709563@apache.org"
xmlns="http://www.w3.org/2004/08/xop/include" />
</Document>
...
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
--MIME_boundary
Content-Type: text/xml
Content-Transfer-Encoding: binary
Content-ID: <cid:1.urn:uuid:BC47538ED684E0A2D41194546709563@apache.org>
binary encoding of document contents
--MIME_boundary--
The id attribute of the ExtrinsicObject metadata element matches the id attribute of a Document element also in metadata. That Document element has a child element <Include> whose href attribute names the mime Part that contains the document contents. To the best of my understanding, here is were XOP offers a benefit. Instead of requiring base64 encoding, these attachment can be binary encoded. Much better for large documents.
Example Retrieve Document Set transaction
Below is an example request and response from a Retrieve Document Set transaction taken from a trace of the Public Registry. The original was chunk encoded (included header Transfer-Encoding: chunked). This encoding has been removed for readability. To make this a valid transaction either the chunked encoding would have to be redone or a Content-Length header would have to be added.
Request
POST /axis2/services/xdsrepositoryb HTTP/1.1
Content-Type: application/soap+xml; charset=UTF-8; action="urn:ihe:iti:2007:RetrieveDocumentSet"
User-Agent: Axis2
Host: localhost:9087
<?xml version='1.0' encoding='UTF-8'?>
<soapenv:Envelope xmlns:soapenv="http://www.w3.org/2003/05/soap-envelope"
xmlns:wsa="http://www.w3.org/2005/08/addressing">
<soapenv:Header>
<wsa:To>http://localhost:9087/axis2/services/xdsrepositoryb</wsa:To>
<wsa:MessageID>urn:uuid:D565D5833AE3D90AFD1198851327915</wsa:MessageID>
<wsa:Action>urn:ihe:iti:2007:RetrieveDocumentSet</wsa:Action>
</soapenv:Header>
<soapenv:Body>
<RetrieveDocumentSetRequest xmlns="urn:ihe:iti:xds-b:2007"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="urn:ihe:iti:xds-b:2007 file:/Users/bill/ihe/Frameworks/ITI-4/XDS.b/schema/IHE/XDS.b_DocumentRepository.xsd">
<DocumentRequest>
<RepositoryUniqueId>1.19.6.24.109.42.1</RepositoryUniqueId>
<DocumentUniqueId>129.6.58.91.13297</DocumentUniqueId>
</DocumentRequest>
<DocumentRequest>
<RepositoryUniqueId>1.19.6.24.109.42.1</RepositoryUniqueId>
<DocumentUniqueId>129.6.58.91.13298</DocumentUniqueId>
</DocumentRequest>
</RetrieveDocumentSetRequest>
</soapenv:Body>
</soapenv:Envelope>
Response
The documents included in the response are MTOM encoded (see <xdsb:Document/> element).
HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Content-Type: application/soap+xml; action="urn:ihe:iti:2007:RetrieveDocumentSetResponse";charset=UTF-8
Date: Fri, 28 Dec 2007 14:15:28 GMT
<?xml version='1.0' encoding='UTF-8'?>
<soapenv:Envelope xmlns:soapenv="http://www.w3.org/2003/05/soap-envelope"
xmlns:wsa="http://www.w3.org/2005/08/addressing">
<soapenv:Header>
<wsa:Action>urn:ihe:iti:2007:RetrieveDocumentSetResponse</wsa:Action>
<wsa:RelatesTo>urn:uuid:D565D5833AE3D90AFD1198851327915</wsa:RelatesTo>
</soapenv:Header>
<soapenv:Body>
<xdsb:RetrieveDocumentSetResponse xmlns:xdsb="urn:ihe:iti:xds-b:2007">
<rs:RegistryResponse xmlns:rs="urn:oasis:names:tc:ebxml-regrep:xsd:rs:3.0"
status="urn:oasis:names:tc:ebxml-regrep:ResponseStatusType:Success"/>
<xdsb:DocumentResponse>
<xdsb:Document>VGhpcyBpcyBteSBkb2N1bWVudC4KCkl0IGlzIGdyZWF0IQoK</xdsb:Document>
<xdsb:RepositoryUniqueId>1.19.6.24.109.42.1</xdsb:RepositoryUniqueId>
<xdsb:DocumentUniqueId>129.6.58.91.13297</xdsb:DocumentUniqueId>
<xdsb:mimeType>text/plain</xdsb:mimeType>
</xdsb:DocumentResponse>
<xdsb:DocumentResponse>
<xdsb:Document>VGhpcyBpcyBteSBzZWNvbmQgZG9jdW1lbnQuCgpJdCBpcyBncmVhdCEKCg==</xdsb:Document>
<xdsb:RepositoryUniqueId>1.19.6.24.109.42.1</xdsb:RepositoryUniqueId>
<xdsb:DocumentUniqueId>129.6.58.91.13298</xdsb:DocumentUniqueId>
<xdsb:mimeType>text/plain</xdsb:mimeType>
</xdsb:DocumentResponse>
</xdsb:RetrieveDocumentSetResponse>
</soapenv:Body>
</soapenv:Envelope>
See Also
Cross Enterprise Document Sharing