Apelon Distributed Terminology System (DTS)
DTS 4.0 Web Services Quick Start Guide
Apelon Distributed Terminology System (DTS) – DTS 4.0 Web Services Quick Start Guide
Table of Contents
Introduction ..................................................................................................................................... 3
The WSDL ...................................................................................................................................... 3
Generating Java client classes (JAX-WS) ...................................................................................... 3
Create a DTS web service client ..................................................................................................... 3
Troubleshooting .............................................................................................................................. 6
Invocation on method is not allowed .......................................................................................... 6
wsimport hangs ........................................................................................................................... 6
Appendix ......................................................................................................................................... 7
Manually correcting the EAR files for the ‘invocation not allowed’ issue ................................ 7
©1999-2014 Apelon, Inc. All Rights Reserved.
2
Apelon Distributed Terminology System (DTS) – DTS 4.0 Web Services Quick Start Guide
Introduction
This is a quick reference guide on how to connect to an installed DTS4 server using web
services. It assumes you have set up DTS4 according to the “dts_InstallationGuide.pdf”. In a
client specific production environment, the WSDL URL and the usernames and passwords
shown in this document would likely be different.
The WSDL
Start the DTS4 server. You should be able to see the WSDL at this URL:

http://localhost:8080/soap/DtsQueryDaoWS?wsdl
Generating Java client classes (JAX-WS)
Follow these steps to generate a Java client from the WSDL.
1. Open a terminal, change to your desired working directory.
2. Use the wsimport tool (which you can find in the bin directory of your java installation)
to generate the JAX-WS portable artifacts:
wsimport -keep -Xnocompile http://localhost:8080/soap/DtsQueryDaoWS?wsdl
The command generates the .java files that comprise the client.
3. Copy the generated .java files into your IDE.
4. Ignore the .class files. .
Create a DTS web service client
To create a functioning web service client you will need a project with the classes generated in
the previous step and classes from the “dtscore” module.
.
1. If you’re using Maven project, and have built the DTS projects locally, add the following
dependency to your POM:
<dependencies>
<dependency>
<groupId>apelon-dts</groupId>
<artifactId>dtscore</artifactId>
<!-- ensure the version is correct -->
<version>4.0.1.367</version>
</dependency>
</dependencies>
If you’re not using Maven you will have to gather the .jar file created by the “dtscore”
project as well as all of the jar files of the transitive dependencies. It might be easiest I
©1999-2014 Apelon, Inc. All Rights Reserved.
3
Apelon Distributed Terminology System (DTS) – DTS 4.0 Web Services Quick Start Guide
this case to just include all of the .jar files of DTS in your classpath.
2. Create a class called Example like this:
import java.util.List;
import java.util.Map;
import javax.xml.ws.BindingProvider;
import
import
import
import
com.apelon.common.log4j.LogConfigLoader;
com.apelon.dtsserver.types.TConceptAttributeSetDescriptor;
com.apelon.dtsserver.types.TOntylogConcept;
com.apelon.dtsserver.types.TProperty;
/**
* Sample code using a JAX-WS client.
*/
public class Example {
public static void main(String[] args) {
try {
// setup Log4j appender for DTS Client logging.
(new LogConfigLoader(".", "src/main/resources/log4jconfig.xml",
Example.class)).loadDefault();
// Instantiate client
DtsQueryDaoService service = new DtsQueryDaoService();
System.out.println("Retrieving the port from the following service: "
+ service);
DtsQueryDaoWS port = service.getDtsQueryDaoPort();
// Set credentials for JAX-WS.
Map<String, Object> requestContext =
((BindingProvider) port).getRequestContext();
requestContext.put(BindingProvider.USERNAME_PROPERTY, "dtsadmin");
requestContext.put(BindingProvider.PASSWORD_PROPERTY, "password");
// This assumes LOINC is loaded into the DTS instance
String conceptCode = "13506-1"; // Urea nitrogen renal clearance
int namespaceId = 5102; // LOINC
// Configure the service to read all property types
TConceptAttributeSetDescriptor attributeSetDescriptor =
new TConceptAttributeSetDescriptor();
attributeSetDescriptor.setAllPropertyTypes(true);
// Get concept
System.out
.println("Invoking the findConceptByCode operation on the port.");
TOntylogConcept concept =
port.findConceptByCode(conceptCode, namespaceId,
attributeSetDescriptor);
// Print some concept info
©1999-2014 Apelon, Inc. All Rights Reserved.
4
Apelon Distributed Terminology System (DTS) – DTS 4.0 Web Services Quick Start Guide
String conceptName = concept.getName();
System.out.println("Concept Name: " + conceptName);
System.out.println();
// Print concept properties
List<TProperty> props = concept.getProperties();
System.out.println("Properties\n==========");
for (TProperty prop : props) {
System.out.println(prop.getPropertyType().getName() + ": "
+ prop.getValue());
}
} catch (Exception ex) {
ex.printStackTrace();
}
}
}
3. Run the class as a Java application.
a. Make sure DTS is properly deployed to JBoss and running.
b. If the web services are available, you should be able to see the raw WSDL at the
URL at the beginning of this document.
c. Make sure the username and password in the “main” method are correct for your
deployment
d. You should see output like the following.
Retrieving the port from the following service:
com.apelon.dtsserver.ws.dtsquery.DtsQueryDaoService@4af8d139
Invoking the findConceptByCode operation on the port.
Concept Name: Urea nitrogen renal clearance
Properties
==========
Component: Urea nitrogen renal clearance
Property: Volume Rate
Time Aspect: Point in time
System: Urine+Ser/Plas
ScaleType: Quantitative
Short Name: UUN Cl Ur+SerPl-vRate
Code in Source: 13506-1
Change Type: MAJ
Date Last Changed: 20070612
Units Required: Y
Order/Observation: Both
Source: LCA
Long Common Name: Urea nitrogen renal clearance
UMLS CUI: C0550556
UMLS Semantic Type: Clinical Attribute
Status: ACTIVE
Class: CHEM
Classtype: 1
Example Unit: mL/min
Example UCUM Units: mL/min
©1999-2014 Apelon, Inc. All Rights Reserved.
5
Apelon Distributed Terminology System (DTS) – DTS 4.0 Web Services Quick Start Guide
Common SI Test Rank: 0
Synthesized LOINC Name: Urea nitrogen renal clearance:VRat:Pt:Urine+Ser/Plas:Qn:
Related Names: ; Urea nit; UN; Blood urea nitrogen; N2; Nit; N; vRate; Volume rate;
Flow; Point in time; Random; Ur+SerPl; Ur+SerPl; UR; Urn; UA; SerPl; SerPlas; SerP;
Serum; SR; Plasma; Pl; Plsm; Quantitative; QNT; Quant; Quan; Cl; Kidney; Clear;
Clearanc; Clearances; Clr; Chemistry; BUN; UUN
Multiaxial Path To Root: 2 | LP31388-9.LP31398-8.LP14492-0.LP131080-6
Troubleshooting
Invocation on method is not allowed
The stock DTS deployment EAR files (dtsjboss.ear or dtsgf.ear) were found to have issues with
authentication of webservice calls in some situations. This will be fixed in the next release of
DTS. In the meantime, you may contact Apelon support for a patched EAR file if you see an
error like this:
Retrieving the port from the following service:
com.apelon.dtsserver.ws.dtsquery.DtsQueryDaoService@37d638ad
Invoking the findConceptByCode operation on the port.
Client received SOAP Fault from server: JBAS014502: Invocation on method: public
com.apelon.dtsserver.types.TOntylogConcept
com.apelon.dtsserver.ejb.DtsQueryDaoBean.findConceptByCode(java.lang.String,int,com.apelon.dts
server.types.TConceptAttributeSetDescriptor) of bean: DtsQueryDaoBean is not allowed Please
see the server log to find more detail regarding exact cuase of the failure.
com.sun.xml.ws.fault.ServerSOAPFaultException: Client received SOAP Fault from server:
JBAS014502: Invocation on method: public com.apelon.dtsserver.types.TOntylogConcept
com.apelon.dtsserver.ejb.DtsQueryDaoBean.findConceptByCode(java.lang.String,int,com.apelon.dts
server.types.TConceptAttributeSetDescriptor) of bean: DtsQueryDaoBean is not allowed Please
see the server log to find more detail regarding exact cuase of the failure.
at com.sun.xml.ws.fault.SOAP11Fault.getProtocolException(SOAP11Fault.java:193)
at com.sun.xml.ws.fault.SOAPFaultBuilder.createException(SOAPFaultBuilder.java:126)
at com.sun.xml.ws.client.sei.StubHandler.readResponse(StubHandler.java:247)
at com.sun.xml.ws.db.DatabindingImpl.deserializeResponse(DatabindingImpl.java:177)
at com.sun.xml.ws.db.DatabindingImpl.deserializeResponse(DatabindingImpl.java:256)
at com.sun.xml.ws.client.sei.SyncMethodHandler.invoke(SyncMethodHandler.java:128)
at com.sun.xml.ws.client.sei.SyncMethodHandler.invoke(SyncMethodHandler.java:102)
at com.sun.xml.ws.client.sei.SEIStub.invoke(SEIStub.java:151)
at $Proxy41.findConceptByCode(Unknown Source)
at com.apelon.dtsserver.ws.dtsquery.Example.run(Example.java:46)
at com.apelon.dtsserver.ws.dtsquery.Example.main(Example.java:67)
Replacing the stock EAR file with the one provided by Apelon support will correct the issue.
Alternatively, see the Appendix below for instructions on manually fixing the stock EAR file.
wsimport hangs
Some uses reported a problem running wsimport where it hangs and never successfully connects
to the service URL. The source of the hang is still under investigation.
©1999-2014 Apelon, Inc. All Rights Reserved.
6
Apelon Distributed Terminology System (DTS) – DTS 4.0 Web Services Quick Start Guide
If this happens you can work around the issue by downloading the wsdl using another
mechanism – examples:
with wget:
wget http://localhost:8080/soap/DtsQueryDaoWS?wsdl -O dts.wsdl
wsimport -keep -Xnocompile dts.wsdl
with curl:
curl http://localhost:8080/soap/DtsQueryDaoWS?wsdl -o dts.wsdl
wsimport -keep -Xnocompile dts.wsdl
Or you can view the page in a web browser, then ‘view source’ then save the source document as
a wsdl file, then run wsimport on that file.
Appendix
Manually correcting the EAR files for the ‘invocation not allowed’ issue
This problem is related to the way security was configured within the EAR file. The server
(JBoss or GlassFish) was not requesting authorization when webservice calls were made – and if
authorization was provided – the server was ignoring it. Internally, when it reached the EJB
code which required authorization, no credentials were available, so the call failed.
The deployment EAR needs a couple of configuration changes to correct the issue. You only
need to correct the EAR file that you are using – either the dtsjboss.ear or dtsgf.ear file.
For JBoss, we will be adding a new configuration file to the META-INF directory of the
dtsserverejb.jar file that is within the dtsjboss.ear file. For Glassfish, we will be modifying an
existing configuration file within the META-INF directory of the dtsserverejb.jar file that is
within the dtsgf.ear file.
First, create a new file named ‘jboss-webservices.xml’ with the following contents
<?xml version="1.0"?>
<webservices xmlns="http://www.jboss.com/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="1.0"
xsi:schemaLocation="http://www.jboss.com/xml/ns/javaee
http://www.jboss.org/j2ee/schema/jboss_webservices_1_0.xsd">
<context-root>soap/DtsQueryDaoWS</context-root>
<port-component>
<ejb-name>DtsQueryDaoBean</ejb-name>
<port-component-name>DtsQueryDaoWS</port-component-name>
<port-component-uri>/*</port-component-uri>
<auth-method>BASIC</auth-method>
</port-component>
</webservices>
©1999-2014 Apelon, Inc. All Rights Reserved.
7
Apelon Distributed Terminology System (DTS) – DTS 4.0 Web Services Quick Start Guide
Next, create a ‘glassfish-ejb-jar.xml’ file with the following contents
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE glassfish-ejb-jar PUBLIC "-//GlassFish.org//DTD GlassFish Application Server
3.1 EJB 3.1//EN"
"http://glassfish.org/dtds/glassfish-ejb-jar_3_1-1.dtd">
<glassfish-ejb-jar>
<security-role-mapping>
<role-name>apelondts</role-name>
<group-name>apelondts</group-name>
</security-role-mapping>
<security-role-mapping>
<role-name>apelondtsadmin</role-name>
<group-name>apelondtsadmin</group-name>
</security-role-mapping>
<enterprise-beans>
<ejb>
<ejb-name>DtsQueryDaoBean</ejb-name>
<webservice-endpoint>
<port-component-name>DtsQueryDaoWS</port-component-name>
<endpoint-address-uri>soap/DtsQueryDaoWS</endpoint-address-uri>
<login-config>
<auth-method>BASIC</auth-method>
</login-config>
</webservice-endpoint>
</ejb>
</enterprise-beans>
</glassfish-ejb-jar>
To enact the fix you will need to get these two files into the EAR file, in the correct location.
Following is the code for fixing it in a Unix/Linux/Cygwin style environment
 Assume jboss-webservices.xml is in /tmp
 Assume glassfish-ejb-jar.xml is in /tmp
 Assume dtsjboss.ear OR dtsgf.ear is in /tmp (this shows dtsjboss as the example, but the
procedure is identical for dtsgf.ear – just replace ‘dtsjboss’ with ‘dtsgf’ anywhere it is
present.
# Unpack dtsjboss.ear
cd /tmp
mkdir dtsjboss
cd dtsjboss
"$JAVA_HOME/bin/jar" xvf ../dtsjboss.ear
# Unpack dtsserverejb.jar
mkdir dtsserverejb
cd dtsserverejb
"$JAVA_HOME/bin/jar" xvf ../dtsserverejb.jar
# Add/Copy the new config files
cp /tmp/jboss-webservices.xml META-INF
cp /tmp/glassfish-ejb-jar.xml META-INF
©1999-2014 Apelon, Inc. All Rights Reserved.
8
Apelon Distributed Terminology System (DTS) – DTS 4.0 Web Services Quick Start Guide
# Repack dtsserverejb.jar with the new files
cd ..
rm -f dtsserverejb.jar
"$JAVA_HOME/bin/jar" cvf dtsserverejb.jar -C dtsserverejb .
rm -rf dtsserverejb
# Repack dtsjboss.ear
# This yields a “dtsjboss.ear” file within the “dtsjboss” directory
# thus avoiding overwriting the original file.
"$JAVA_HOME/bin/jar" cvf dtsjboss.ear .
# deploy this dtsjboss.ear file and then remove the “dtsjboss” directory
If you’re working in a pure Windows environment without access to a Unix-style shell, then you
can do this alternatively in a cmd style shell.
REM Unpack dtsjboss.ear
set JAVA_HOME="C:\Program Files\Java\jdk1.7.0_07"
mkdir dtsjboss
cd dtsjboss
%JAVA_HOME%\bin\jar xvf ..\dtsjboss.ear
REM Unpack dtsserverejb.jar
mkdir dtsserverejb
cd dtsserverejb
%JAVA_HOME%\bin\jar xvf ..\dtsserverejb.jar
REM Add/Copy the new config files
copy C:\temp\jboss-webservices.xml META-INF
copy C:\temp\glassfish-ejb-jar.xml META-INF
REM Repack dtsserverejb.jar with the new files
cd ..
del dtsserverejb.jar
%JAVA_HOME%\bin\jar cvf dtsserverejb.jar -C dtsserverejb .
rmdir /Q /S dtsserverejb
REM Repack dtsjboss.ear
REM This yields a “dtsjboss.ear” file within the “dtsjboss” directory
REM thus avoiding overwriting the original file.
%JAVA_HOME%\bin\jar cvf dtsjboss.ear .
REM deploy this dtsjboss.ear file and then remove the “dtsjboss” directory
©1999-2014 Apelon, Inc. All Rights Reserved.
9