April 25, 2003

Calling Google's Web Service

Google's Web service gives you access to their vast database. Here are some simple steps to get you up and running using Java and Apache AXIS.

In order to use Google Web APIs you first must register with Google to receive an authentication key. You can do this online at http://www.google.com/apis/.

Google also offers a developer's kit that has documentation, examples, and a custom Java library that provides a convenience wrapper for Java programmers.

There are two common ways to call Google's Web service in Java:

  1. Use their custom Java library found in googleapi.jar

  2. Use files generated from the WSDL file to call the service

Since the first method is Google-specific, we will focus on the second method so that you can apply what you learn to any Web service.

Let's briefly explain the Web service process before we continue:

  1. A Web service exposes its methods in a Web Services Description Language (WSDL) file

  2. A WSDL file contains the datatypes that you should pass to the service as well as the ones that you will get back. The WSDL file also contains the bindings that the Web service supports and the location of the Web service

  3. A Web service's client uses a WSDL file to generate the stubs to access the Web service

Google's WSDL file says that the Google service binds to the HTTP protocol. It also defines 3 methods:

  1. doGetCachedPage – Given a URL, it returns the contents of the URL in base64 encoded text

  2. doSpellingSuggestion – Given a misspelled phrase, it returns a string with the correct spelling

  3. doGoogleSearch – Given a query string and a set of parameters, it returns a set of search results

For more detailed information about these methods, read the documentation that comes with the developer's kit.



Using Apache AXIS to Call Google's Web Service

Apache AXIS is an implementation of SOAP in Java. The AXIS package is around 10MB in size so if you have a slow connection, you can download the jar libraries by themselves from my website (http://www.myspotter.com/downloads/lib.zip). AXIS has a tool called WSDL2Java that takes a WSDL file and generates the client-side stubs for connecting to the Web service specified in the WSDL file. Once you have downloaded AXIS and put the jar files located in the lib directory in your classpath, you can use the tool by issuing the following command:

java org.apache.axis.wsdl.WSDL2Java http://api.google.com/GoogleSearch.wsdl

This will generate Java classes in a directory named after the namespace defined in the WSDL file. In this case, the directory is GoogleSearch.

For you command line junkies, here are the exact steps you take to generate the stubs:

  1. Create some directory to place your jar files in (e.g. C:\google)

  2. You should put the following files in this directory: axis-ant.jar, commons-discovery.jar, commons-logging.jar, jaxrpc.jar, log4j-1.2.4.jar, saaj.jar, wsdl4j.jar, axis.jar

  3. Enter the following command (NOTE: In Windows, the class path file separator is a semicolon whereas in Linux it is a colon. If you are using Linux, you will need to change all of the ; to : ):

    C:\google>java -classpath "axis-ant.jar;commons-discovery.jar;commons-logging.jar;jaxrpc.jar;log4j-1.2.4.jar;saaj.jar;wsdl4j.jar;axis.jar" org.apache.axis.wsdl.WSDL2Java http://api.google.com/GoogleSearch.wsdl

  4. The previous command should have generated the stubs and put them in the GoogleSearch folder (i.e. C:\google\GoogleSearch). Now, go into this directory, create a file named GoogleClient.java, and copy and paste this code into it (Don't forget to change the key!):

    package GoogleSearch;
    
    public class GoogleClient {
    
            public static void main(String[] args) throws Exception {
                    // Make a service
                    GoogleSearchService service = new GoogleSearchServiceLocator();
    
                    // Now use the service to get a stub to the Service Definition Interface (SDI)
                    GoogleSearchPort google = service.getGoogleSearchPort();
    
                    // Make the actual call
                    String key = "PUT YOUR KEY HERE";
                    String phrase = "missspell";
                    String result = google.doSpellingSuggestion(key, phrase);
                    System.out.println("Did you mean: " + result);
            }
    }
  5. Now compile everything with this command:

    C:\google>javac -classpath "axis-ant.jar;commons-discovery.jar;commons-logging.jar;jaxrpc.jar;log4j-1.2.4.jar;saaj.jar;wsdl4j.jar;axis.jar" GoogleSearch\*.java

  6. Run the program with this command:

    C:\google>java -classpath ".;axis-ant.jar;commons-discovery.jar;commons-logging.jar;jaxrpc.jar;log4j-1.2.4.jar;saaj.jar;wsdl4j.jar;axis.jar" GoogleSearch.GoogleClient

  7. You should have received the following output: “Did you mean: misspell”

If you noticed, all of the commands were executed from the C:\google directory. If you are having class path problems, you really should think about using an IDE. On a serious note, here are links to detailed documentation on setting the class path for Windows and Linux. To avoid confusion, I dumped the entire directory listing into the class path in the examples above. Optimally, you would want to set the CLASSPATH environment variable to prevent all the extra typing. This is done using the following commands:

  • Windows: set CLASSPATH=classpath1;classpath2...

  • Linux: setenv CLASSPATH classpath1:classpath2...

For example, on Windows you could have done this:

  1. set CLASSPATH="axis-ant.jar;commons-discovery.jar;commons-logging.jar;jaxrpc.jar;log4j-1.2.4.jar;saaj.jar;wsdl4j.jar;axis.jar"

  2. java org.apache.axis.wsdl.WSDL2Java http://api.google.com/GoogleSearch.wsdl

  3. javac -classpath %CLASSPATH% GoogleSearch\*.java

  4. java -classpath .;%CLASSPATH% GoogleSearch.GoogleClient



Using the doGoogleSearch Method

We started off with with doSpellingSuggestion method because of its simplicity, but we can't talk about Google without mentioning their search method. The next example shows how to use the doGoogleSearch method. Create a file named GoogleSearchClient.java and copy and paste the following into it:

package GoogleSearch;

public class GoogleSearchClient {

        public static void main(String[] args) throws Exception {
                // Make a service
                GoogleSearchService service = new GoogleSearchServiceLocator();

                // Now use the service to get a stub to the Service Definition Interface (SDI)
                GoogleSearchPort google = service.getGoogleSearchPort();

                // Make the actual call
                String key = "PUT YOUR KEY HERE";
                String query = "xml";
                int start = 0;
                int maxResults = 10;
                boolean filter = true;
                String restrict = "";
                boolean safeSearch = true;
                String languageRestrict = "lang_en";
                String inputEncoding = "UTF-8";
                String outputEncoding = "UTF-8";

                GoogleSearchResult gsr =
                        google.doGoogleSearch(
                                key,
                                query,
                                start,
                                maxResults,
                                filter,
                                restrict,
                                safeSearch,
                                languageRestrict,
                                inputEncoding,
                                outputEncoding);

                ResultElement[] re = gsr.getResultElements();

                for (int i = 0; i < re.length; i++) {
                        System.out.println(re[i].getURL());
                }
        }
}

If you ran the program successfully, a list of 10 URLs should have been printed to the screen. To use the search method to its full potential, you really should download the Google developer's kit and read the documentation.



Conclusion

You might have not thought about it, but you have just called methods that appear to be local but are really remote. In the history of distributed programming, it has never been easier to call remote methods without having to learn an entire list of new technologies. You can try your newfound skills with Amazon's Web service. There is also a website called XMethods that keeps a list of Web services that you can play with. Enjoy.

You can download the generated stubs, the two examples, and class path intructions from here. If you have any questions feel free to email me at nelkarra@myspotter.com.

Posted by Nasseam Elkarra at April 25, 2003 04:46 AM