Java API for WordNet Searching (JAWS)

As its name implies, the Java API for WordNet Searching (JAWS) is an API that provides Java applications with the ability to retrieve data from the WordNet database. It is a simple and fast API that is compatible with both the 2.1 and 3.0 versions of the WordNet database files and can be used with Java 1.4 and later.

JAWS was created and is maintained by Brett Spell, who is currently an adjunct member of the faculty in the Computer Science and Engineering (CSE) department at Southern Methodist University.

On this page you'll find the following information:

Using JAWS With Your Application

To use JAWS in your application you must do the following:
  1. Obtain a copy of the WordNet database files, which can be accomplished by downloading and installing WordNet (you must download the full version of WordNet and not just the database files).
  2. Download the Java Archive (JAR) file containing the compiled JAWS code (available here).
  3. When starting your application you must:
    • Include in your Java Virtual Machine's class path the JAR file you downloaded.
    • Use the wordnet.database.dir system property to specify where the WordNet database files are located (see below).

Specifying the Database Directory

The WordNet database files are found in the dict subdirectory below your WordNet installation directory. For example, if you installed WordNet in C:\WordNet-3.0\ the database files will be located in the C:\WordNet-3.0\dict\ directory.

You can either set the wordnet.database.dir property within your code or it can be done externally. To set it from within your code you must use the setProperty() method in the System class as in the following example:

System.setProperty("wordnet.database.dir", "C:\WordNet-3.0\dict\");

The technique for setting the wordnet.database.dir property externally (outside your code) depends on how you're executing your application. If you're running your code from within an Integrated Development Environment (IDE) such as Eclipse you'll need to use that IDE's support for setting system properties. For example, Eclipse allows you to specify "VM Arguments" and you would need to include an entry like the following in the list of arguments to use when running your code:

-Dwordnet.database.dir=C:\WordNet-3.0\dict\

Alternatively, if you're running your application from the command line you would need to use the -D option as shown in the next section of these instructions.

Starting Your Application

Let's assume the following:
  • You've downloaded the JAR file containing the JAWS executable code to a Windows machine and saved it as jaws-bin.jar in your C:\mywork\code directory.
  • You installed WordNet to a directory named C:\WordNet-3.0\ which in turn would mean that the database files are located in C:\WordNet-3.0\dict\.
In this case, you could start a Java Virtual Machine from the command line like the one shown below, which assumes that you also have defined a class called MyApp that contains a main() method:

java -classpath .;C:\mywork\code\jaws-bin.jar -Dwordnet.database.dir=C:\WordNet-3.0\dict MyApp
 

Getting Started With the API

From within the application you started you can use JAWS by first obtaining an instance of WordNetDatabase with code like the following, which assumes that you've performed an import of the classes in the edu.smu.tspell.wordnet package:

WordNetDatabase database = WordNetDatabase.getFileInstance();

Once you've done so, you can begin to retrieve synsets from the database as shown in the example below. This code retrieves all noun synsets for "fly" and loops through each one printing its first word form, its description, and the number of hyponyms associated with that noun synset:


NounSynset nounSynset;
NounSynset[] hyponyms;

WordNetDatabase database = WordNetDatabase.getFileInstance();
Synset[] synsets = database.getSynsets("fly", SynsetType.NOUN);
for (int i = 0; i < synsets.length; i++) {
    nounSynset = (NounSynset)(synsets[i]);
    hyponyms = nounSynset.getHyponyms();
    System.err.println(nounSynset.getWordForms()[0] +
            ": " + nounSynset.getDefinition() + ") has " + hyponyms.length + " hyponyms");
}

For more information on how to use JAWS you can browse the API documentation, although in most cases your application should only need to refer to the types defined in the edu.smu.tspell.wordnet package.

Downloads

The following files are available for download:

Version 1.3 (Latest)
Name Description Links
jaws-bin.jar Runtime library Download
jaws-src.zip Source code Download
jaws-doc.zip API documentation Download -or- browse online
Version 1.2
Name Description Links
jaws-bin-1.2.jar Runtime library Download
jaws-src-1.2.jar Source code Download
jaws-doc-1.2.zip API documentation Download -or- browse online
 

Example Program

A small sample program is available for download here that demonstrates how to use the API. It displays some of the attributes of the synset(s), if any, that contain the word form specified as the first argument specified when the program is executed.
 

Changes

  • December 24, 2009 -- Updated example to show how to retrieve hyponyms.
  • June 20, 2009 -- Bug fix and new convenience methods for head and satellite synsets.
  • July 21, 2008 -- Support derivational form retrieval for all synset types.
  • February 13, 2008 -- Removed unused code