How to use ChemSpider webservices when programming with java
Posted by: Aileen Day in How ChemSpider Runs, Search, UncategorizedRecently I have been programming a java plug-in from which I needed to call the ChemSpider webservices, and I found that this wasn’t as straightforward as I was expecting, so I thought I would post how to do it in case it’s useful for anyone else who wants to do likewise.
The basic method I used was to use Apache Axis2 to generate java code for the WSDL’s of the main ChemSpider webservices. This java code is available here: chemspider_webservices_javasourcecode.zip and I have also made the compiled jar file available here: chemspider_webservices.jar. The ChemSpider webservices can be called from other java code by referencing this jar file (and the other axis library files).
This blog post describes how I generated and used this jar file. I was using the Eclipse IDE, so some of what I describe will be specific to that.
There is a similar jar file of some ChemSpider webservices which is available by downloading MZMine (the file chemspider-api.jar in the lib directory) and an example of its use can be seen by downloading the source code and looking at the file src\net\sf\mzmine\modules\peaklistmethods\identification\dbsearch\databases\ChemSpiderGateway.java). That jar file was generated using the previous version of Axis (just plain Axis, rather than Axis2) compared to this one. The example here may be easier to use as a start point since the full range of ChemSpider webservices are included in the jar file, there is a full description of how it was generated, the code used to generate the jar file is available and there are more examples of its use.
Generating the chemspider_webservices.jar file
To generate the java code from the WSDL of the ChemSpider webservices I used the WSDL2Java functionality of Apache Axis2. This is available in different forms, including an Eclipse plug-in which will directly import the java code generated into a project, but I found various bugs when trying to use the latest version of that, so just used the command line version.
I started off with generating the java code from the WSDL of the ChemSpider MassSpecAPI webservice:
- I downloaded and unzipped the latest version of the Apache Axis2 binary distribution from their download page. I used version 1.6.1 of Axis2.
- In the “bin” directory of this download there should be a file called java2wsdl.bat. Running this batch file from a command line saves a lot of time trying to set up the class paths correctly to run Java2WSDL. Before using it you should set up the following two environment variables:
- AXIS2_HOME: Must point to the top level of the AXIS2 files which you just downloaded
- JAVA_HOME: Must point at your Java Development Kit installation direcotry (e.g. C:\Program Files\Java\jre6)
- To see a full list of the options available when running WSDL2Java simply open a command prompt and run the batch file with no options to obtain the Usage options – more information about these can be found in the Apache Axis2 user guide:
> axis2-1.6.1\bin\wsdl2java.bat
- I ran it with options to specify to use the SOAP 1.2 port of the ChemSpider MassSpecAPI webservice (most ChemSpider webservices have the option of SOAP 1.1, SOAP 1.2, HTTP GET or HTTP POST), to generate synchronous code only (not asynchronous), and to use adb databinding (this is the default anyway):
> axis2-1.6.1\bin\wsdl2java.bat -uri http://www.chemspider.com/MassSpecAPI.asmx?WSDL -pn MassSpecAPISoap12 -s -d adb
- This then generated the file MassSpecAPIStub.java which it automatically put in the package com.chemspider.www (so was the appropriate folder structure was created above it accordingly)
- I repeated this processes with the other 4 main ChemSpider webservices:
> axis2-1.6.1\bin\wsdl2java.bat -uri http://www.chemspider.com/Search.asmx?WSDL -pn SearchSoap12 -s -d adb> axis2-1.6.1\bin\wsdl2java.bat -uri http://www.chemspider.com/InChI.asmx?WSDL -pn InChISoap12 -s -d adb> axis2-1.6.1\bin\wsdl2java.bat -uri http://www.chemspider.com/Spectra.asmx?WSDL -pn SpectraSoap12 -s -d adb> axis2-1.6.1\bin\wsdl2java.bat -uri http://www.chemspider.com/OpenBabel.asmx?WSDL -pn OpenBabelWebServiceSoap12 -s -d adb
- The folders and java class files generated by Java2WSDL (MassSpecAPIStub.java, SearchStub.java, InChIStub.java, SpectraStub.java and OpenBabelWebServiceStub.java) that were generated are available in the zip file chemspider_webservices_javasourcecode.zip for further reference
- I then started a new Eclipse project, imported this generated File system into it
- The generated classes rely on the Axis2 library files so these need to be added to the build path – in Eclipse this is done by right-clicking on the project in the Package Explorer, choosing Properties > Java Build Path > Libraries > Add External Jars and selecting all of the lib files in the lib folder of the Axis2 folder.
- This project was exported as the jar file chemspider_webservices.jar
Using the chemspider_webservices.jar file as an external library jar file
The chemspider_webservices.jar file and all of the Apache Axis2 library jar files need adding to a java project as referenced libraries before it can be called. To do this in Eclipse right-click on the project in the Package Explorer, choose Properties > Java Build Path > Libraries > Add External Jars and select:
- the chemspider_webservices.jar file (download it from chemspider_webservices.jar and save it locally)
- all of the lib files in the lib folder of the Axis2 folder.
Once this has been done then the ChemSpider webservices can be called from the project. An example is shown below, and is also downloadable in text format from here. This has been structured into (pretty well self-contained) functions which can be easily called to retrieve the results of a particular operation of a webservice. In the main function these functions are called and the output written out.
Please note that you should put your obtains your own ChemSpider token from ChemSpider to set as the ChemSpiderToken value – to obtain this, register for a ChemSpider account, and look up your token from your user Profile page after logging in. Some tokens require your user account to be associated with the “Service Subscriber” role, which you can request from your user profile page.
package com.chemspider.www.examples;
import java.util.HashMap;
import java.util.Map;
import javax.swing.JOptionPane;
import org.apache.log4j.BasicConfigurator;
import org.apache.log4j.Level;
import org.apache.log4j.Logger;
import com.chemspider.www.*;
import com.chemspider.www.InChIStub.InChIToCSIDResponse;
import com.chemspider.www.SearchStub.GetAsyncSearchResultResponse;
import com.chemspider.www.SearchStub.GetAsyncSearchStatusResponse;
import com.chemspider.www.SearchStub.SimpleSearchResponse;
import com.chemspider.www.MassSpecAPIStub.ArrayOfInt;
import com.chemspider.www.MassSpecAPIStub.ArrayOfString;
import com.chemspider.www.MassSpecAPIStub.ExtendedCompoundInfo;
import com.chemspider.www.MassSpecAPIStub.GetDatabasesResponse;
import com.chemspider.www.MassSpecAPIStub.GetExtendedCompoundInfoArrayResponse;
import com.chemspider.www.MassSpecAPIStub.SearchByMassAsyncResponse;
public class WebServiceExamples {
/**
* @param args
*/
private static final Logger LOG = Logger.getLogger(WebServiceExamples.class.getName());
private static String ChemSpiderToken = "YOU NEED TO INSERT YOUR OWN TOKEN IN HERE";
public static void main(String[] args) {
BasicConfigurator.configure();
JOptionPane.showMessageDialog(null, "The compound with InChI InChI=1S/C6H6/c1-2-4-6-5-3-1/h1-6H has CSID:"+get_InChI_InChIToCSID_Results("InChI=1S/C6H6/c1-2-4-6-5-3-1/h1-6H"));
int[] SimpleSearchResults = get_Search_SimpleSearch_Results("taxol", ChemSpiderToken);
JOptionPane.showMessageDialog(null, "The first of "+SimpleSearchResults.length+" ChemSpider compound(s) returned by a search for Taxol has CSID:"+SimpleSearchResults[0]);
int[] inputCSIDs = new int[2];
inputCSIDs[0] = 236;
inputCSIDs[1] = 238;
Map
Map
JOptionPane.showMessageDialog(null, "The Average Mass of the compound with CSID 238 is: "+thisCompoundInfo.get("AverageMass"));
String[] GetDatabaseResults = get_MassSpecAPI_GetDatabases_Results();
JOptionPane.showMessageDialog(null, "The first of "+GetDatabaseResults.length+" datasources in ChemSpider is:"+GetDatabaseResults[0]);
String SearchByMassAsyncResults = get_MassSpecAPI_SearchByMassAsync_Results(1100.0, 0.1,GetDatabaseResults, ChemSpiderToken);
JOptionPane.showMessageDialog(null, "Transaction ID for search on compounds with mass = 1100+/- 0.1 from any data source is" + SearchByMassAsyncResults);
JOptionPane.showMessageDialog(null, "The operation status of the search with this transaction ID is" + get_Search_GetAsyncSearchStatus_Results(SearchByMassAsyncResults, ChemSpiderToken));
int[] GetAsyncSearchResultResults = get_Search_GetAsyncSearchResult_Results(SearchByMassAsyncResults, ChemSpiderToken);
JOptionPane.showMessageDialog(null, "And the first of "+GetAsyncSearchResultResults.length+" ChemSpider compound(s) returned by the search has CSID:"+GetAsyncSearchResultResults[0]);
}
/**
* Function to call the InChIToCSID operation of ChemSpider's InChI SOAP 1.2 webservice (http://www.chemspider.com/InChI.asmx?op=InChIToCSID)
* Convert InChI to ChemSpider ID.
*
* @param inchi: string representing inchi to search ChemSpider for
* @return: string representing CSID returned
*/
public static String get_InChI_InChIToCSID_Results(String inchi) {
String Output = null;
try {
final InChIStub thisInChIstub = new InChIStub();
com.chemspider.www.InChIStub.InChIToCSID InChIToCSIDInput = new com.chemspider.www.InChIStub.InChIToCSID();
InChIToCSIDInput.setInchi(inchi);
final InChIToCSIDResponse thisInChIToCSIDResponse = thisInChIstub.inChIToCSID(InChIToCSIDInput);
Output = thisInChIToCSIDResponse.getInChIToCSIDResult();
} catch (Exception e) {
LOG.log(Level.ERROR, "Problem retrieving ChemSpider webservices", e);
}
return Output;
}
/**
* Function to call the SimpleSearch operation of ChemSpider's Search SOAP 1.2 webservice (http://www.chemspider.com/search.asmx?op=SimpleSearch)
* Search by Name, SMILES, InChI, InChIKey, etc. Returns a list of found CSIDs (first 100 - please use AsyncSimpleSearch instead if you like to get the full list). Security token is required.
*
* @param query: String representing search term (can be Name, SMILES, InChI, InChIKey)
* @param token: string containing your user token (listed at your http://www.chemspider.com/UserProfile.aspx page)
* @return: int[] array containing the ChemSpider IDs. If more than 100 are found then only the first 100 are returned.
*/
public static int[] get_Search_SimpleSearch_Results(String query, String token) {
int[] Output = null;
try {
final SearchStub thisSearchStub = new SearchStub();
com.chemspider.www.SearchStub.SimpleSearch SimpleSearchInput = new com.chemspider.www.SearchStub.SimpleSearch();
SimpleSearchInput.setQuery(query);
SimpleSearchInput.setToken(token);
final SimpleSearchResponse thisSimpleSearchResponse = thisSearchStub.simpleSearch(SimpleSearchInput);
Output = thisSimpleSearchResponse.getSimpleSearchResult().get_int();
} catch (Exception e) {
LOG.log(Level.ERROR, "Problem retrieving ChemSpider webservices", e);
}
return Output;
}
/**
* Function to call the GetDatabases operation of ChemSpider's MassSpecAPI SOAP 1.2 webservice (http://www.chemspider.com/massspecapi.asmx?op=GetDatabases)
* Get the list of datasources in ChemSpider.
*
* @return: the list of datasources in ChemSpider as a String Array
*/
public static String[] get_MassSpecAPI_GetDatabases_Results() {
String[] Output = null;
try {
final MassSpecAPIStub thisMassSpecAPIStub = new MassSpecAPIStub();
com.chemspider.www.MassSpecAPIStub.GetDatabases getDatabaseInput = new com.chemspider.www.MassSpecAPIStub.GetDatabases();
final GetDatabasesResponse thisGetDatabasesResponse = thisMassSpecAPIStub.getDatabases(getDatabaseInput);
Output = thisGetDatabasesResponse.getGetDatabasesResult().getString();
} catch (Exception e) {
LOG.log(Level.ERROR, "Problem retrieving ChemSpider webservices", e);
}
return Output;
}
/**
* Function to call the GetExtendedCompoundInfoArray operation of ChemSpider's MassSpecAPI SOAP 1.2 webservice (http://www.chemspider.com/massspecapi.asmx?op=GetExtendedCompoundInfoArray)
* Get array of extended record details by an array of CSIDs. Security token is required.
*
* @param CSIDs: integer array containing the CSIDs of compounds for which information will be returned
* @param token: string containing your user token (listed at your http://www.chemspider.com/UserProfile.aspx page)
* @return: a Map
*/
public static Map
Map
try {
final MassSpecAPIStub thisMassSpecAPIStub = new MassSpecAPIStub();
ArrayOfInt inputCSIDsArrayofInt = new ArrayOfInt();
inputCSIDsArrayofInt.set_int(CSIDs);
com.chemspider.www.MassSpecAPIStub.GetExtendedCompoundInfoArray getGetExtendedCompoundInfoArrayInput = new com.chemspider.www.MassSpecAPIStub.GetExtendedCompoundInfoArray();
getGetExtendedCompoundInfoArrayInput.setCSIDs(inputCSIDsArrayofInt);
getGetExtendedCompoundInfoArrayInput.setToken(token);
final GetExtendedCompoundInfoArrayResponse thisGetExtendedCompoundInfoArrayResponse = thisMassSpecAPIStub.getExtendedCompoundInfoArray(getGetExtendedCompoundInfoArrayInput);
ExtendedCompoundInfo[] thisExtendedCompoundInfo = thisGetExtendedCompoundInfoArrayResponse.getGetExtendedCompoundInfoArrayResult().getExtendedCompoundInfo();
for (int i=0; i
thisCompoundExtendedCompoundInfoArrayOutput.put("CSID", Integer.toString(thisExtendedCompoundInfo[i].getCSID()));
thisCompoundExtendedCompoundInfoArrayOutput.put("MF", thisExtendedCompoundInfo[i].getMF());
thisCompoundExtendedCompoundInfoArrayOutput.put("SMILES", thisExtendedCompoundInfo[i].getSMILES());
thisCompoundExtendedCompoundInfoArrayOutput.put("InChI", thisExtendedCompoundInfo[i].getInChI());
thisCompoundExtendedCompoundInfoArrayOutput.put("InChIKey", thisExtendedCompoundInfo[i].getInChIKey());
thisCompoundExtendedCompoundInfoArrayOutput.put("AverageMass", Double.toString(thisExtendedCompoundInfo[i].getAverageMass()));
thisCompoundExtendedCompoundInfoArrayOutput.put("MolecularWeight", Double.toString(thisExtendedCompoundInfo[i].getMolecularWeight()));
thisCompoundExtendedCompoundInfoArrayOutput.put("MonoisotopicMass", Double.toString(thisExtendedCompoundInfo[i].getMonoisotopicMass()));
thisCompoundExtendedCompoundInfoArrayOutput.put("NominalMass", Double.toString(thisExtendedCompoundInfo[i].getNominalMass()));
thisCompoundExtendedCompoundInfoArrayOutput.put("ALogP", Double.toString(thisExtendedCompoundInfo[i].getALogP()));
thisCompoundExtendedCompoundInfoArrayOutput.put("XLogP", Double.toString(thisExtendedCompoundInfo[i].getXLogP()));
thisCompoundExtendedCompoundInfoArrayOutput.put("CommonName", thisExtendedCompoundInfo[i].getCommonName());
Output.put(thisExtendedCompoundInfo[i].getCSID(), thisCompoundExtendedCompoundInfoArrayOutput);
}
} catch (Exception e) {
LOG.log(Level.ERROR, "Problem retrieving ChemSpider webservices", e);
}
return Output;
}
/**
* Function to call the SearchByMass2 operation of ChemSpider's MassSpecAPI SOAP 1.2 webservice (http://www.chemspider.com/massspecapi.asmx?op=SearchByMass2)
* Search ChemSpider by mass +/- range.
*
* @param Mass: The compounds returned have a mass (Double) within the range Mass +/- Range
* @param Range: The compounds returned have a mass (Double) within the range Mass +/- Range
* @return: the ChemSpider IDs of compounds returned (as a String Array)
*/
public static String get_MassSpecAPI_SearchByMassAsync_Results(Double mass, Double range, String[] dbs, String token) {
String Output = null;
try {
final MassSpecAPIStub thisMassSpecAPIStub = new MassSpecAPIStub();
com.chemspider.www.MassSpecAPIStub.SearchByMassAsync getSearchByMassAsyncInput = new com.chemspider.www.MassSpecAPIStub.SearchByMassAsync();
getSearchByMassAsyncInput.setMass(mass);
getSearchByMassAsyncInput.setRange(range);
ArrayOfString inputDBsArrayofString = new ArrayOfString();
inputDBsArrayofString.setString(dbs);
getSearchByMassAsyncInput.setDbs(inputDBsArrayofString);
getSearchByMassAsyncInput.setToken(token);
final SearchByMassAsyncResponse thisSearchByMassAsyncResponse = thisMassSpecAPIStub.searchByMassAsync(getSearchByMassAsyncInput);
Output = thisSearchByMassAsyncResponse.getSearchByMassAsyncResult();
} catch (Exception e) {
LOG.log(Level.ERROR, "Problem retrieving ChemSpider webservices", e);
}
return Output;
}
/**
* Function to call the GetAsyncSearchStatus operation of ChemSpider's Search SOAP 1.2 webservice (http://www.chemspider.com/search.asmx?op=GetAsyncSearchStatus)
* Query asynchronous operation status. Requires transaction ID returned by AsynchSearch operation. Security token is required.
*
* @param rid: String representing transaction ID returned from a previous search
* @param token: string containing your user token (listed at your http://www.chemspider.com/UserProfile.aspx page)
* @return: String describing status of this search - can have values Unknown or Created or Scheduled or Processing or Suspended or PartialResultReady or ResultReady or Failed or TooManyRecords
*/
public static String get_Search_GetAsyncSearchStatus_Results(String rid, String token) {
String Output = null;
try {
final SearchStub thisSearchStub = new SearchStub();
com.chemspider.www.SearchStub.GetAsyncSearchStatus GetAsyncSearchStatusInput = new com.chemspider.www.SearchStub.GetAsyncSearchStatus();
GetAsyncSearchStatusInput.setRid(rid);
GetAsyncSearchStatusInput.setToken(token);
final GetAsyncSearchStatusResponse thisGetAsyncSearchStatusResponse = thisSearchStub.getAsyncSearchStatus(GetAsyncSearchStatusInput);
Output = thisGetAsyncSearchStatusResponse.getGetAsyncSearchStatusResult().toString();
} catch (Exception e) {
LOG.log(Level.ERROR, "Problem retrieving ChemSpider webservices", e);
}
return Output;
}
/**
* Function to call the GetAsyncSearchResult operation of ChemSpider's Search SOAP 1.2 webservice (http://www.chemspider.com/search.asmx?op=GetAsyncSearchResult)
* Returns the list of CSIDs found by AsynchSearch operation. Security token is required.
*
* @param rid: String representing transaction ID returned from a previous search
* @param token: string containing your user token (listed at your http://www.chemspider.com/UserProfile.aspx page)
* @return: int[] array containing the ChemSpider IDs.
*/
public static int[] get_Search_GetAsyncSearchResult_Results(String rid, String token) {
int[] Output = null;
try {
final SearchStub thisSearchStub = new SearchStub();
com.chemspider.www.SearchStub.GetAsyncSearchResult GetAsyncSearchResultInput = new com.chemspider.www.SearchStub.GetAsyncSearchResult();
GetAsyncSearchResultInput.setRid(rid);
GetAsyncSearchResultInput.setToken(token);
final GetAsyncSearchResultResponse thisGetAsyncSearchResultResponse = thisSearchStub.getAsyncSearchResult(GetAsyncSearchResultInput);
Output = thisGetAsyncSearchResultResponse.getGetAsyncSearchResultResult().get_int();
} catch (Exception e) {
LOG.log(Level.ERROR, "Problem retrieving ChemSpider webservices", e);
}
return Output;
}
}
Disclaimer: I’m new to Java programming, so please excuse me if you are a java expert and I’ve said something obvious, offended you with my code or used the wrong terminology anywhere.
Entries (RSS)
