SOAPclientForOpenCalais

A SOAP Client for Open Calais

This document shows you how to write a simple, console-based Java SOAP client to access the Open Calais web service. The concepts presented in this tutorial are also useful when you write a SOAP client for any other web service.

By: Amit Kumar Saha


Contents


Introduction- The Calais Web Service

According to http://opencalais.mashery.com/Overview "The Calais web service automatically attaches rich semantic metadata to the content you submit – in well under a second. Using natural language processing, machine learning and other methods, Calais categorizes and links your document with entities (people, places, organizations, etc.), facts (person ‘x’ works for company ‘y’), and events (person ‘z’ was appointed chairman of company ‘y’ on date ‘x’). The metadata results are stored centrally and returned to you as industry-standard RDF constructs accompanied by a Globally Unique Identifier (GUID). Using the Calais GUID, any downstream consumer is able to retrieve this metadata via a simple call to Calais.

This metadata gives you the ability to build maps (or graphs or networks) linking documents to people to companies to places to products to events to geographies to … whatever. You can use those maps to improve site navigation, provide contextual syndication, tag and organize your content, create structured folksonomies, filter and de-duplicate news feeds or analyze content to see if it contains what you care about. And, you can share those maps with anyone else in the content ecosystem. "

How does it work?

From a programmer's point of view, you construct a SOAP request and send it to the web service remote endpoint. The web service replies with the output in Resource Description Framework.

Prerequisites

  • NetBeans IDE (preferably 6.0 + ), Web and Java EE installation
  • JDK 1.6.0 +
  • Cursory Knowledge of RDF
  • Cursory knowledge of the Semantic web
  • Cursory knowledge of Web Services

Creating the SOAP Client for Open Calais

Create a Java application project. In this project, create a web service client that consumes the Open Calais enlighten service.

  1. In the New Project wizard, create a Java application project. Name it contextualizer. Accept all default settings--it should create a Main class.Image:pic-1_SOAPclientForOpenCalais.png
  2. Right-click on the project node. The context menu opens.
  3. Select New->Web Service Client.
  4. Add the URL of the enlighten WSDL, http://api.opencalais.com/enlighten/?wsdl.

Image:pic-2_SOAPclientForOpenCalais.png

Your code will now start fetching information about the web-service you mentioned via WSDL: Image:pic-3_SOAPclientForOpenCalais.png

After the fetch is over, expand the "Web Service References" node in the project explorer. It will show the SOAP functions made available by the web-service:

Image:pic-4_SOAPclientForOpenCalais.png

Framing and Sending the SOAP Request Using the Open Calais API

The Open Calais API provides both a SOAP 1.1 and a SOAP 1.2 function named "enlighten". We are going to use the SOAP 1.1 function in our client.

Simply click on the "enlighten" node on the left and drag it onto your "contextualiser.Main" class. You should see the following code is added to the existing class in the main function:

try { // Call Web Service Operation
            contextualiser.Calais service = new contextualiser.Calais();
            contextualiser.CalaisSoap port = service.getCalaisSoap();
            // TODO initialize WS operation arguments here
            java.lang.String licenseID = "";
            java.lang.String content = "";
            java.lang.String paramsXML = "";
            // TODO process result here
            java.lang.String result = port.enlighten(licenseID, content, paramsXML);
            System.out.println("Result = "+result);
        } catch (Exception ex) {
            // TODO handle custom exceptions here
        }

To understand the various parameters used to make the API call, please refer to the Open Calais API guide.

Specifically, we have to send the following information with a SOAP request:

  • A License ID, or a Developer key (obtained on registration at the Open Calais website)
  • The text about which you want to obtain the semantic metadata
  • ParamsXML-a string in a pre-defined XML format

Use the word "water" for the text. The ParamsXML is the one mentioned in the Open Calais API documentation. Your source code should now look like:

/*
 * To change this template, choose Tools | Templates
 * and open the template in the editor.
 */

package contextualiser;

import java.io.BufferedReader;
import java.io.FileReader;
import java.io.IOException;


/**
 *
 * @author amit
 */
public class Main {

    /**
     * @param args the command line arguments
     */
    public static void main(String[] args) {
        // TODO code application logic here
        
try { // Call Web Service Operation
            contextualiser.Calais service = new contextualiser.Calais();
            contextualiser.CalaisSoap port = service.getCalaisSoap();

            // TODO initialize WS operation arguments here
            java.lang.String licenseID = "1234567890134"; //replace this with your own license key
            java.lang.String content = "water";
            java.lang.String paramsXML="";
            
            String line;
            try{
            FileReader input = new FileReader("paramsXML.xml");
            BufferedReader bufRead = new BufferedReader(input);
            
            while((line=bufRead.readLine())!=null){
                paramsXML+= line;
                System.out.println(line);
                
            }
            

            }catch(IOException e){
                System.out.println(e);
            }
                        
            // TODO process result here
            
            java.lang.String result = port.enlighten(licenseID, content, paramsXML);
            System.out.println("Result = "+result);
        } catch (Exception ex) {
            // TODO handle custom exceptions here
        }
        
        
        
    }

}

Obtaining and Displaying the Result in RDF

Run the application. You should see the following output, which is the result returned in RDF:

Result = <?xml version="1.0" encoding="UTF-8"?>
<!--Use of the Calais Web Service is governed by the Terms of Service located at
http://www.opencalais.com. By using this service or the results of the service you agree to these terms of service.-->
<!--Relations: -->
<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:c="http://s.opencalais.com/1/pred/">
  <rdf:Description c:allowDistribution="true" c:allowSearch="true" c:externalID="17cabs901" 
        c:id="http://id.opencalais.com/bUbfFuD236B*1cQ0HYI6oQ" 
        rdf:about="http://d.opencalais.com/dochash-1/39398136-d4d6-3982-8f21-485fb471eeb8">
    <rdf:type rdf:resource="http://s.opencalais.com/1/type/sys/DocInfo"/>
    <c:document>
        <![CDATA[<Document><Title>1202964573347-746EE973-4572
          </Title><Date>2008-02-13</Date><Body>water
          </Body></Document>]]>
    </c:document>
    <c:externalMetadata></c:externalMetadata>
    <c:submitter>ABC</c:submitter>
  </rdf:Description>

  <rdf:Description c:contentType="text/txt" c:emVer="UnifiedIM-DJ" 
        c:langIdVer="DefaultLangId" c:language="English" c:processingVer="CalaisJob01" 
        c:submitionDate="2008-02-13 23:49:33.347" 
        rdf:about="http://d.opencalais.com/dochash-1/39398136-d4d6-3982-8f21-485fb471eeb8/meta">
    <rdf:type rdf:resource="http://s.opencalais.com/1/type/sys/DocInfoMeta"/>
    <c:docId rdf:resource="http://d.opencalais.com/dochash-1/39398136-d4d6-3982-8f21-485fb471eeb8"/>
    <c:submitterCode>954dedfb-e5af-ff67-5cc1-9599f94aeacf</c:submitterCode>
    <c:signature>
      digestalg-1|Rv3gMjGYbJzloiKbo24xZwaUCNs=|NxxctMO/y2jIkIcVC1AI8WYUd+OTqz2cdzZWTrqqkiIhOjPXI7FAGA==
    </c:signature>
  </rdf:Description>

  <rdf:Description rdf:about="http://d.opencalais.com/dochash-1/39398136-d4d6-3982-8f21-485fb471eeb8/lid/DefaultLangId">
    <rdf:type rdf:resource="http://s.opencalais.com/1/type/lid/DefaultLangId"/>
    <c:docId rdf:resource="http://d.opencalais.com/dochash-1/39398136-d4d6-3982-8f21-485fb471eeb8"/>
    <c:lang rdf:resource="http://d.opencalais.com/lid/DefaultLangId/English"/>
  </rdf:Description>
</rdf:RDF>

More Exercises

What we obtained is RDF and not human readable. It does not show the amazing things that can be done with the power of Open Calais. However, we have now done the "back office" job. Next, you can try to:

  1. Use this RDF to obtain the returned information in a useful format.
  2. Build an application called "contextualiser" (hence I chose this name for the Java application here) which returns contextual information about the query text.

Knowledge about RDF is necessary to draw relevant information from the RDF output. The following tools/libraries can be helpful:

Endnotes

The main objective of this tutorial was to show how you could create a JAX-WS client that interacts with the Open Calais Web Service. However, the concepts can also be used to write a client to interact with any other Web-Service instead.

References

Not logged in. Log in, Register

By use of this website, you agree to the NetBeans Policies and Terms of Use. © 2012, Oracle Corporation and/or its affiliates. Sponsored by Oracle logo