OHF Using XDS.b

From Eclipsepedia

Jump to: navigation, search

Back to: OHF IHE FAQ

Back to: OHF Bridge FAQ

Back to: OHF IHE MAIN BRANCH

Contents

About XDS.b

XDS.b is a profile proposed and accepted for trial implementation in the 2007-2008 IHE profile cycle. The primary purpose of the profile is to take the existing XDS specification and make it more consistent with existing and emerging Web service standards.

To read the trial implementation of the XDS.b profile, please see the IHE XDS.b Supplement

The previous XDS profile has been renamed to XDS.a.

XDS.b and OHF

The version of OHF for use at the 2007-2008 IHE Connectathon supports the XDS.b Document Consumer and the XDS.b Document Source in addition to the existing support for XDS.a Document Consumer and Source.

OHF XDS.b Document Consumer

The OHF XDS.b Document Consumer implements two transactions: Registry Stored Query and Retrieve Document Set. The Stored Query transaction is semantically identical to the XDS.a Registry Stored Query transaction. The Retrieve Document Set transaction is new.

Consumer API

The XDS.b Document Consumer API is controlled by the class org.eclipse.ohf.ihe.xds.consumer.B_Consumer(java.net.URI, java.net.URI, java.util.Map).

  • Registry URI

The first parameter to the constructor is the URI of the Web service target endpoint for the Registry Stored Query listener on the XDS.b registry.

  • Initiating Gateway URI

If you are working in an Affinity Domain that contains an XCA Initiating Gateway, specify the URL to the Gateway as the second parameter to the constructor. This will allow for proper routing of requests (queries and retrieve document) that may contain a homeCommunityId value.

  • RepositoryUniqueId Mapping

In XDS.a, query response metadata pointed explicitly to the URL in which to retrieve a document. For XDS.b, this is not the case. An XDS.b Repository reports itself to the registry with a unique value called the repositoryUniqueId. The XDS.b query metadata will contain this value. To retrieve a document from an XDS.b repository, the consumer (you) must be able to associate that repositoryUniqueId with the designated Web service target endpoint for that repository.

To allow for this, the OHF XDS.b Consumer API accepts a new parameter, the RepositoryUniqueId Map. The Consumer expects a Map<String,java.net.URI> with the repositoryUniqueId string (an OID: "10.1.2") mapping to a URI of the Web service target endpoint for the Retrieve Document Set listener on that repository. See below for an example.

Sample Code

// URI for the XDS Registry
java.net.URI registryURI = new java.net.URI("http://somesite.com/XdsBRegistry/Registry");

// Set the mapping of repositoryUniqueId => Repository Web service endpoint
Map repositoryUriMap = new HashMap();
repositoryUriMap.put("10.1.2", new java.net.URI("http://somesite.com/XdsBRepository/RetrieveDocumentListener"));
repositoryUriMap.put("10.1.3", new java.net.URI("http://anothersite.com/AnotherXDSBRepository/RetrieveDocumentListener"));

// Optional:  URI for the XCA Initiating Gateway
java.net.URI initiatingGatewayUrl = new java.net.URI("http://somesite.com/XCAGateway/Gateway");

B_Consumer consumer = new B_Consumer(registryURI, initiatingGatewayUrl, repositoryUriMap);

Registry Stored Query

The Registry Stored Query transaction is semantically identical to the XDS.a Registry Stored Query transaction. More details coming soon.

Retrieve Document Set

Due to the nature of the XDS.b profile, a new transaction Retrieve Document Set has been created. The API is as follows:

XDSResponseType org.eclipse.ohf.ihe.xds.consumer.B_Consumer.retrieveDocumentSet(RetrieveDocumentSetRequestType,List);
  • Parameter 1: RetrieveDocumentSetRequestType

The RetrieveDocumentSetRequestType is an EMF-generated structure that represents a request for a document set in XDS.b. It contains a list of requests with each request containing minimally a repositoryUniqueId and a documentUniqueId.

Optionally, each request can contain a homeCommunityId - the identifier for use with cross-community requests (XCA). Per the XDS specification any XDS query result that contains a homeCommunityId, all subsequent queries or requests related to the result must contain the homeCommunityId. Please see the section about using XCA for more information.

  • Parameter 2: List<org.eclipse.ohf.ihe.xds.document.Document>

The second parameter, a List, is a pre-instantiated list that will contain the documents in response. These results will be of type org.eclipse.ohf.ihe.xds.document.Document and contains a byte array, MIME type, documentUniqueId, repositoryUniqueId, and (optionally) homeCommunityId.

Sample Code

RetrieveDocumentSetRequestType retrieveDocumentSetRequest = org.eclipse.ohf.ihe.xds.consumer.retrieve.RetrieveFactory.eINSTANCE.createRetrieveDocumentSetRequestType();
DocumentRequestType documentRequest;

// Create Document Request 1
documentRequest = org.eclipse.ohf.ihe.xds.consumer.retrieve.RetrieveFactory.eINSTANCE.createDocumentRequestType();

documentRequest.setRepositoryUniqueId("10.1.2");
documentRequest.setDocumentUniqueId("10.9.3.120.4.10.10220.10002221");

retrieveDocumentSetRequest.getDocumentRequest().add(documentRequest);

// Create Document Request 2
documentRequest = org.eclipse.ohf.ihe.xds.consumer.retrieve.RetrieveFactory.eINSTANCE.createDocumentRequestType();
       
documentRequest.setRepositoryUniqueId("10.1.2");
documentRequest.setDocumentUniqueId("10.9.3.120.4.10.10220.932133221");
// Optionally set a homeCommunityId
documentRequest.setHomeCommunityId("someHomeCommunityId");

retrieveDocumentSetRequest.getDocumentRequest().add(documentRequest);

// Create container for response documents
List documents = new ArrayList();

// Retrieve Documents
XDSResponseType response = consumer.retrieveDocumentSet(retrieveDocumentSetRequest, documents);

OHF XDS.b Document Source

The OHF XDS.b Document Source plug-in is largely the same as the XDS.a Document Source plug-in. The key difference is the class name.

Source API

The XDS.b Document Source API is controlled by the class org.eclipse.ohf.ihe.xds.source.B_Source(java.net.URI).

  • Repository URI

The only parameter to the XDS.b Source is the Web service target endpoint for the Provide and Register Document Set listener on the XDS.b Repository.

Sample Code

java.net.URI repositoryURI = new java.net.URI("http://somesite.com/XdsBRepository/ProvideRegisterListener");
B_Source source = new B_Source(repositoryURI);

Provide and Register Document Set

The Provide and Register transaction for XDS.b in the OHF API is identical to the XDS.a Provide and Register transaction. More details coming soon.

XCA and XUA Support

XDS.b and the OHF Bridge

The OHF Bridge provides nearly seamless support for the XDS.b Document Consumer and Document Support through the use of RHIO Configuration. However, some application modifications will need to be made.

RHIO Configuration

The OHF Bridge relies on the RHIO Configuration file to handle centralized configuration of affinity domains, including URLs for XDS registries and repositories and PIX managers. This allows Bridge users to identify the system(s) they want to talk to by name rather than having to specify numerous URLs.

For XDS.b, the RHIO Configuration file format was modified slightly so that each registry or repository machine configured is identified as supporting XDS.a or an XDS.b. The Bridge will then select the appropriate class to use when sending requests.

Additionally, XDS.b repositories will define their repositoryUniqueId and a <retrieveDocumentUrl>, the URL to the Web service listener for the Retrieve Document Set transaction. This is essential for associating responses from XDS queries with appropriate repository to retrieve from.

Example

<!-- Registries -->
<registry xdsVersion="a">
    <id>lswin10</id>
    <storedQueryUrl>
        <unsecured>http://lswin10.dfw.ibm.com:9080/XDSRegistryWS/services/XDSRegistry</unsecured>
        <secured>http://lswin10.dfw.ibm.com:9044/XDSRegistryWS/services/XDSRegistry</secured>
    </storedQueryUrl>
    <mllp>
        <unsecured>mllp://lswin10.dfw.ibm.com:3777</unsecured>
        <secured>mllps://lswin10.dfw.ibm.com:3778</secured>
    </mllp>
</registry>

<registry xdsVersion="b">
    <id>XDS-B-Facade</id>
    <storedQueryUrl>
        <unsecured>http://localhost:8090/axis2/services/XDSRegistryFacade</unsecured>
    </storedQueryUrl>
</registry>

<!-- Repositories -->
<repository xdsVersion="a">
    <id>lswin10</id>
    <provideRegisterUrl>
        <unsecured>http://lswin10.dfw.ibm.com:9080/IHIIRepository/SubmissionSetReceiver</unsecured>
        <secured>https://lswin10.dfw.ibm.com:9044/IHIIRepository/SubmissionSetReceiver</secured>
    </provideRegisterUrl>
</repository>

<repository xdsVersion="b">
    <id>XDS-B-Facade</id>
    <repositoryUniqueId>asdf1234</repositoryUniqueId>
    <provideRegisterUrl>
        <unsecured>http://localhost:8090/axis2/services/XDSRepositoryFacade</unsecured>
    </provideRegisterUrl>
    <retrieveDocumentUrl>
        <unsecured>http://localhost:8090/axis2/services/XDSRepositoryFacade</unsecured>
    </retrieveDocumentUrl>
</repository>