Using E-Utilities Web Service with Apache Axis 1.3 for Java
Updated: January 19, 2006
Axis 1.3 WSDL2Java generates wrong source code for some complex types, see bug AXIS-2391.
It's recommended to use Axis 1.2 until the issue resolved.
Creating an NCBI Web Service Client Application
The following walkthrough describes the process for accessing the NCBI E-Utilities Web service from an application
created with Apache Axis (version 1.3).
Preinstalled Software
You should have Apache Axis for Java installed on your computer, for example, in C:\Axis directory. Also, you
need JDK (Java Development Kit, installed, for example, in C:\JDK) to compile java files generated by Axis.
Create directory to place your files, for example, C:\EUtils and create generate.bat file there:
echo off
set AXIS_LIB=C:\AXIS\lib
set AXISCP=.;%AXIS_LIB%\axis.jar;%AXIS_LIB%\commons-discovery-0.2.jar;%AXIS_LIB%\commons-logging-1.0.4.jar
set AXISCP=%AXISCP%;%AXIS_LIB%\jaxrpc.jar;%AXIS_LIB%\saaj.jar;%AXIS_LIB%\log4j-1.2.8.jar;%AXIS_LIB%\wsdl4j-1.5.1.jar
echo on
java -cp %AXISCP% org.apache.axis.wsdl.WSDL2Java --wrapArrays --timeout -1 %*
|
Note: If you connect to Internet through a proxy, the last command line should include proxy settings and should look like, for example:
java -DproxySet=true -Dhttp.proxyHost=myproxy.mycompany.com -proxyPort=80 -cp %AXISCP% ...
Also, you need to supply proxyUser and proxyPassword if the proxy server requires authentification. Then the command line could look like
java -DproxySet=true -Dhttp.proxyHost=myproxy.mycompany.com -DproxyPort=80 -DproxyUser=user -DproxyPassword=password -cp %AXISCP% ...
Create compile.bat file:
echo off
set JDK_HOME=C:\JDK
set AXIS_LIB=C:\AXIS\lib
set AXISCP=.;%JDK_HOME%\jre\lib\rt.jar;%AXIS_LIB%\axis.jar;%AXIS_LIB%\commons-discovery-0.2.jar
set AXISCP=%AXISCP%;%AXIS_LIB%\commons-logging-1.0.4.jar;%AXIS_LIB%\jaxrpc.jar;%AXIS_LIB%\saaj.jar
set AXISCP=%AXISCP%;%AXIS_LIB%\log4j-1.2.8.jar;%AXIS_LIB%\wsdl4j-1.5.1.jar
echo on
javac -J-ms20m -J-mx1000m -classpath %AXISCP% gov\nih\nlm\ncbi\www\soap\eutils\*.java
|
Note: There are new parameters in the command line -J-ms20m -J-mx1000m which increase the heap memory for compiling a
source code.
Create run.bat file:
echo off
set JDK_HOME=C:\JDK
set AXIS_LIB=C:\AXIS\lib
set AXISCP=.;%JDK_HOME%\jre\lib\rt.jar;%AXIS_LIB%\axis.jar;%AXIS_LIB%\commons-discovery-0.2.jar
set AXISCP=%AXISCP%;%AXIS_LIB%\commons-logging-1.0.4.jar;%AXIS_LIB%\jaxrpc.jar;%AXIS_LIB%\saaj.jar
set AXISCP=%AXISCP%;%AXIS_LIB%\log4j-1.2.8.jar;%AXIS_LIB%\wsdl4j-1.5.1.jar
echo on
java -classpath %AXISCP% gov.nih.nlm.ncbi.www.soap.eutils.Client
|
Note: You may need to change AXIS_LIB and JDK_HOME values to actual directories where Axis and Java Development Kit are installed.
Note: java.exe and javac.exe files from JDK should be in the directory listed in the PATH environment variable on your computer.
Note: If you connect to Internet through a proxy, the last command line should include proxy settings and should look like, for example:
java -DproxySet=true -Dhttp.proxyHost=myproxy.mycompany.com -proxyPort=80 -cp %AXISCP% ...
Also, you need to supply proxyUser and proxyPassword if the proxy server requires authentification. Then the command line could look like
java -DproxySet=true -Dhttp.proxyHost=myproxy.mycompany.com -DproxyPort=80 -DproxyUser=user -DproxyPassword=password -cp %AXISCP% ...
Generating Java source files
Run the following command:C:\EUtils> generate.bat http://eutils.ncbi.nlm.nih.gov/entrez/eutils/soap/eutils.wsdl
It should generate the stubs and put them in the gov\nih\nlm\ncbi\www\soap\eutils directory.
Client Application Example
The example demonstrates how to make a remote call of the EInfo utility.
Create file Client.java in the gov\nih\nlm\ncbi\www\soap\eutils directory:
package gov.nih.nlm.ncbi.www.soap.eutils;
import gov.nih.nlm.ncbi.www.soap.eutils.einfo.*;
public class Client {
public static void main(String[] args) throws Exception
{
// eInfo utility returns a list of available databases
try
{
EUtilsServiceLocator service = new EUtilsServiceLocator();
EUtilsServiceSoap utils = service.geteUtilsServiceSoap();
// call NCBI EInfo utility
EInfoResult res = utils.run_eInfo(new EInfoRequest());
// results output
for(int i=0; i<res.getDbList().getDbName().length; i++)
{
System.out.println(res.getDbList().getDbName(i));
}
}
catch(Exception e) { System.out.println(e.toString()); }
}
}
|
Compiling the source code
Run compile.bat
Run Example
Run run.bat
SOAP E-Utilities API
Below is a list of methods we recommend for use with Axis for Java.
SOAP interface provides user with two functionally identical sets of methods.
Methods which name ends with _MS are designed for use with Microsoft Visual Studio and SOAP Toolkit 3.0
Click on parameter to get its description.
Click on method name to see the example of use.
- public egquery.Result run_eGquery(egquery.EGqueryRequest parameters) throws java.rmi.RemoteException;
EGqueryRequest class properties:
- String term
- String tool
- String email
- public einfo.EInfoResult run_eInfo(einfo.EInfoRequest parameters) throws java.rmi.RemoteException;
EInfoRequest class properties:
- String db
- String tool
- String email
- public elink.ELinkResult run_eLink(elink.ELinkRequest parameters) throws java.rmi.RemoteException;
ELinkRequest class properties:
- String db
- String id()
- String reldate
- String mindate
- String maxdate
- String datetype
- String term
- String dbfrom
- String WebEnv
- String query_key
- String cmd
- String tool
- String email
- public esearch.ESearchResult run_eSearch(esearch.ESearchRequest parameters) throws java.rmi.RemoteException;
ESearchRequest class properties:
- String db
- String term
- String WebEnv
- String query_key
- String usehistory
- String tool
- String email
- String field
- String reldate
- String mindate
- String maxdate
- String datetype
- String retstart
- String retmax
- String rettype
- String sort
- public espell.ESpellResult run_eSpell(espell.ESpellRequest parameters) throws java.rmi.RemoteException;
ESpellRequest class properties:
- String db
- String term
- String tool
- String email
- public esummary.ESummaryResult run_eSummary(esummary.ESummaryRequest parameters) throws java.rmi.RemoteException;
ESummaryRequest class properties:
- String db
- String id
- String WebEnv
- String query_key
- String retstart
- String retmax
- String tool
- String email
- public efetch.EFetchResult run_eFetch(efetch.EFetchRequest parameters) throws java.rmi.RemoteException;
EFetchRequest class properties:
- String db
- String id
- String WebEnv
- String query_key
- String tool
- String email
- String retstart
- String retmax
- String rettype // *rettype for Molecular Biology Databases
- String strand
- String seq_start
- String seq_stop
- String complexity
- String report
Examples
package gov.nih.nlm.ncbi.www.soap.eutils;
import gov.nih.nlm.ncbi.www.soap.eutils.egquery.*;
public class Client {
public static void main(String[] args) throws Exception
{
// run_eGquery_MS provides Entrez database counts for a single search
try
{
EUtilsServiceLocator service = new EUtilsServiceLocator();
EUtilsServiceSoap utils = service.geteUtilsServiceSoap();
// call NCBI EGQuery utility
Result res = utils.run_eGquery(new EGqueryRequest("mouse", "", ""));
// results output
System.out.println("Search term: " + res.getTerm());
System.out.println("Results: ");
for(int i=0; i<res.getEGQueryResult().getResultItem().length; i++)
{
System.out.println( " " + res.getEGQueryResult().getResultItem()[i].getDbName() +
": " + res.getEGQueryResult().getResultItem()[i].getCount() );
}
}
catch(Exception e) { System.out.println(e.toString()); }
}
}
|
package gov.nih.nlm.ncbi.www.soap.eutils;
import gov.nih.nlm.ncbi.www.soap.eutils.einfo.*;
public class Client {
public static void main(String[] args) throws Exception
{
// eInfo utility returns a list of available databases
try
{
EUtilsServiceLocator service = new EUtilsServiceLocator();
EUtilsServiceSoap utils = service.geteUtilsServiceSoap();
// call NCBI EInfo utility
EInfoResult res = utils.run_eInfo(new EInfoRequest());
// results output
for(int i=0; i<res.getDbList().getDbName().length; i++)
{
System.out.println(res.getDbList().getDbName(i));
}
}
catch(Exception e) { System.out.println(e.toString()); }
}
}
|
package gov.nih.nlm.ncbi.www.soap.eutils;
import gov.nih.nlm.ncbi.www.soap.eutils.elink.*;
public class Client {
public static void main(String[] args) throws Exception
{
// example retrieves IDs from Nucleotide for GI 48819,7140345 to Protein
try
{
EUtilsServiceLocator service = new EUtilsServiceLocator();
EUtilsServiceSoap utils = service.geteUtilsServiceSoap();
// call NCBI ELink utility
ELinkRequest parameters = new ELinkRequest();
parameters.setDb("protein");
parameters.setDbfrom("nucleotide");
parameters.setId(new String[]{"48819,7140345"});
ELinkResult res = utils.run_eLink(parameters);
// results output
for(int i=0; i<res.getLinkSet().length; i++)
{
System.out.print("Links from " + res.getLinkSet()[i].getDbFrom());
System.out.println(" to " + res.getLinkSet()[i].getLinkSetDb()[0].getDbTo());
System.out.print(" " + res.getLinkSet()[i].getDbFrom() + " id(s): ");
for(int k=0; k<res.getLinkSet()[i].getIdList().getId().length; k++)
{
System.out.print(res.getLinkSet()[i].getIdList().getId()[k].get_value() + " ");
}
System.out.println();
System.out.print(" " + res.getLinkSet()[i].getLinkSetDb()[0].getDbTo() + " id(s): ");
for(int k=0; k<res.getLinkSet()[i].getLinkSetDb()[0].getLink().length; k++)
{
System.out.print(res.getLinkSet()[i].getLinkSetDb()[0].getLink()[k].getId().get_value() + " ");
}
System.out.println("\n----------------------");
}
}
catch(Exception e) { System.out.println(e.toString()); }
}
}
|
package gov.nih.nlm.ncbi.www.soap.eutils;
import gov.nih.nlm.ncbi.www.soap.eutils.esearch.*;
public class Client {
public static void main(String[] args) throws Exception
{
// search in PubMed Central for stem cells in free fulltext articles
try
{
EUtilsServiceLocator service = new EUtilsServiceLocator();
EUtilsServiceSoap utils = service.geteUtilsServiceSoap();
// call NCBI ESearch utility
// NOTE: search term should be URL encoded
ESearchRequest parameters = new ESearchRequest();
parameters.setDb("pmc");
parameters.setTerm("stem+cells+AND+free+fulltext[filter]");
parameters.setRetMax("15");
ESearchResult res = utils.run_eSearch(parameters);
// results output
System.out.println("Original query: stem cells AND free fulltext[filter]");
System.out.println("Found ids: " + res.getCount());
System.out.print("First " + res.getRetMax() +" ids: ");
for(int i=0; i<res.getIdList().getId().length; i++)
{
System.out.print(res.getIdList().getId()[i] + " ");
}
System.out.println();
}
catch(Exception e) { System.out.println(e.toString()); }
}
}
|
package gov.nih.nlm.ncbi.www.soap.eutils;
import gov.nih.nlm.ncbi.www.soap.eutils.espell.*;
public class Client {
public static void main(String[] args) throws Exception
{
// retrieves spelling suggestions
try
{
EUtilsServiceLocator service = new EUtilsServiceLocator();
EUtilsServiceSoap utils = service.geteUtilsServiceSoap();
// call NCBI ESpell utility
eSpellResult res = utils.run_eSpell(new ESpellRequest("pubmed", "", "mouss", ""));
// results output
System.out.println("Misspelled word: "+res.Query);
System.out.println("Corrected word: "+res.CorrectedQuery);
}
catch(Exception e) { System.out.println(e.toString()); }
}
}
|
package gov.nih.nlm.ncbi.www.soap.eutils;
import gov.nih.nlm.ncbi.www.soap.eutils.esummary.*;
public class Client {
public static void main(String[] args) throws Exception
{
// retreives document Summaries by list of primary IDs
try
{
EUtilsServiceLocator service = new EUtilsServiceLocator();
EUtilsServiceSoap utils = service.geteUtilsServiceSoap();
// call NCBI ESummary utility
ESummaryRequest params = new ESummaryRequest();
params.setDb("nucleotide");
params.setId("28864546,28800981");
ESummaryResult res = utils.run_eSummary(params);
// results output
for(int i=0; i<res.getDocSum().length; i++)
{
System.out.println("ID: "+res.getDocSum()[i].getId());
for(int k=0; k<res.getDocSum()[i].getItem().length; k++)
{
System.out.println(" "+res.getDocSum()[i].getItem()[k].getName() +
": " +res.getDocSum()[i].getItem()[k].get_any()[0].getValue());
}
System.out.println("-----------------------\n");
}
catch(Exception e) { System.out.println(e.toString()); }
}
}
|
Literature database example
package gov.nih.nlm.ncbi.www.soap.eutils;
import gov.nih.nlm.ncbi.www.soap.eutils.efetch.*;
public class Client {
public static void main(String[] args) throws Exception
{
// fetch article from pubmed and displays its abstract
try
{
EUtilsServiceLocator service = new EUtilsServiceLocator();
EUtilsServiceSoap utils = service.geteUtilsServiceSoap();
// call NCBI EFetch utility
EFetchRequest parameters = new EFetchRequest();
parameters.setDb("pubmed");
parameters.setId("11748933,11700088");
EFetchResult res = utils.run_eFetch(parameters);
// results output
for(int i=0; i<res.getPubmedArticleSet().getPubmedArticle().length; i++)
{
System.out.println("ID: "+res.getPubmedArticleSet().getPubmedArticle()[i].getMedlineCitation().getPMID());
System.out.println("Abstract: "+res.getPubmedArticleSet().getPubmedArticle()[i].getMedlineCitation().getArticle().get_abstract().getAbstractText());
System.out.println("--------------------------\n");
}
}
catch(Exception e) { System.out.println(e.toString()); }
}
}
|
Taxonomy database example
package gov.nih.nlm.ncbi.www.soap.eutils;
import gov.nih.nlm.ncbi.www.soap.eutils.efetch.*;
public class Client {
public static void main(String[] args) throws Exception
{
// fetch a record from Taxonomy database
try
{
EUtilsServiceLocator service = new EUtilsServiceLocator();
EUtilsServiceSoap utils = service.geteUtilsServiceSoap();
// call NCBI EFetch utility
EFetchRequest parameters = new EFetchRequest();
parameters.setDb("taxonomy");
parameters.setId("9685");
EFetchResult res = utils.run_eFetch(parameters);
// results output
System.out.println( res.getTaxaSet().getTaxon()[0].getScientificName() + ": " +
res.getTaxaSet().getTaxon()[0].getDivision() + " (" +
res.getTaxaSet().getTaxon()[0].getRank() + ")" );
}
catch(Exception e) { System.out.println(e.toString()); }
}
}
|
<< Back
