JSpell SDK - Spell Checker for the Java Platform is designed to let you add spell checking capabilities to Java applets and applications.

The JSpell Java SDK Spell Checker is compatible with all versions of Java 2 1.3.1 and higher, including JDK 1.6. This version of JSpell does not support Java 1.02 or Java 1.1. If you require support for Java 1.02 or Java 1.1 please contact our support desk for information on obtaining an earlier release of JSpell.

Contents

The JSpell software is distributed in a file called jspellsdk.zip. This file contains the JSpell Java SDK standalone spell checker components as well as the J2EE web application spell checker components. The contents of the jspellsdk.zip file are shown below.

Files which appear in RED (and their contents) may not be redistributed outside of the purchasing organization unless a JSpell OEM Redistribution License Agreement has been completed. In addition, the file jspellsdk.war is intended for deployment to one server only unless a multiple server (site) license has been obtained for the JSpell software:

Requirements

The JSpell Java SDK software requires a Java 2 compatible operating environment. If you require support for Java 1.02 or Java 1.1 then please contact the JSpell support desk to inquire about obtaining an earlier release of the JSpell software.

Quick Start

Java Application with Local Spell Checking

The JSpell Java SDK application spell checker class files are contained within the jspellsdks.jar file. Inside the directory where you extracted the jspellsdk.zip file execute the following command to run the JSpell Java SDK application test:

java -cp .;jspellsdks.jar com.jspell.demo.JSpellAppTestLocal ./lexicons/

This will launch the JSpell standalone application. All of the dictionaries available in the lexicons folder will be shown in the drop down list. You may choose any available language to test the spell checker.

Java Applet with Servlet Spell Checking

The JSpell Java SDK applet demonstration may be executed by deploying the file jspellsdk.war to your J2EE compatible servlet container. The applet passes spell check requests to the JSpell Servlet. See the appendices for deployment examples using common web servers.

After deploying the .war file to your web server you can access the applet test page with the following URL:

http://localhost/jspellsdk/test.html

If you are testing the HTML page from another machine you will have to substitute the correct host name in the URL. Note: if you have problems loading the applet then you may have to modify the applet CODEBASE and URL parameters inside of the test.html file to match your server deployment configuration.

Java Application with Servlet Spell Checking

JSpell enabled Java applications can pass spell check requests to a JSpell Servlet running on your web server. In order to test the handling of spell check requests inside of a Java application by making calls to the JSpell Servlet you must first deploy the JSpell Servlet to your web server. The JSpell Servlet is contained in the J2EE compatible jspellsdk.war file. See the appendices for deployment examples using common web servers.

After deploying the .war file to your web server, execute the following command from within the directory where you extracted the jspellsdk.zip file:

java -cp .;jspellsdks.jar demo.JSpellAppTestServlet http://localhost/jspellsdk/JSpellServlet

If you are testing the application from a machine other than your web server then you will have to substitute the correct host name for your server.

Using JSpell in Your Applets and Applications

JSpell is designed to be very easy to use in your applets and applications and follows a very simple API to enable spell checking.

SimpleDemo.java - Application (Local Spell Check)

Here is the source for a simple spell checker enabled application which uses the JSpell dictionary file on the local disk. This sample makes use of the JSpellDictionaryLocal and JSpellDictionaryManager classes.

package com.jspell.demo;
 
import java.awt.event.*;
import javax.swing.*;
import com.jspell.domain.*;
import com.jspell.gui.*;
 
public class SimpleDemo extends JFrame {
 
  JSpellParser parser;
  JSpellChecker dialog;
  JSpellDictionaryManager manager;
  JButton check = new JButton("Spell Check");
  JTextArea text = new JTextArea("Type some missspelled text here!");
 
  public SimpleDemo() {
    getContentPane().add("North", check);
    getContentPane().add("Center", text);
    check.addActionListener(new ActionListener() {
      public void actionPerformed(ActionEvent e) {
        {
          manager = JSpellDictionaryManager.getJSpellDictionaryManager();
          manager.setDictionaryDirectory("./lexicons/");
          parser = new JSpellParser(manager.getJSpellDictionaryLocal("English (US)"));
          dialog = new JSpellChecker();
          dialog.setParser(parser);
          dialog.addComponent(text);
          dialog.check();
        }
      }
    });
    setSize(200, 200);
    show();
  }
 
  public static void main(String[] args) {
    new SimpleDemo();
  }
}

You can compile the example with the following command:

javac -classpath jspellsdks.jar SimpleDemo.java

You can execute the example with the following command:

java -cp .;jspellsdks.jar SimpleDemo

As you can see, adding JSpell to an application takes only a few lines of code. Now we will explain each section of the above example so that you can see how JSpell integrates into your application.

First, for a standalone Swing application you must have the following two import statements:

import com.jspell.domain.*;
import com.jspell.gui.*;

The import statements allow you to access the JSpell data and GUI elements and are required for virtually all JSpell applications (the GUI import statement is not required if you are using JSpell in a non-GUI application).

Second, you must declare variables that will be used by the JSpell spell checker. In the above example, the following variables have been declared:

JSpellParser parser;
JSpellChecker dialog;
JSpellDictionaryManager manager;

The JSpellParser class parses the text that is being spell checked. It is also responsible for maintaining an updated copy of the text after replacements have been made. It can notify instances of objects which implement the ParserListener interface when the spell check is complete.

The JSpellDictionaryManager class is implemented as a Singleton (meaning only one instance of the class can exist per Java Virtual Machine). It is designed to maintain an internal collection of JSpellDictionaryLocal objects.

The JSpellChecker class is the JSpell GUI class for the spell checker.

Finally, to perform a spell check you must execute the following code:

manager=JSpellDictionaryManager.getJSpellDictionaryManager();
manager.setDictionaryDirectory("./lexicons/");
parser=new JSpellParser(manager.getJSpellDictionaryLocal("English (US)"));
dialog=new JSpellChecker();
dialog.setParser(parser);
dialog.addComponent(text);
dialog.check();

This code may be executed in response to an event, typically a button press.

The first line,

manager=JSpellDictionaryManager.getJSpellDictionaryManager();

retrieves an instance of the JSpellDictionaryManager object.

The next line,

manager.setDictionaryDirectory("./lexicons/");

sets the location of the JSpell dictionary files. These files have names like lex_enUS.jdx, lex_enGB.jdx, lex_frFR.jdx, etc. When this method is called, all of the JSpell dictionary files are opened and made available to the application through the JSpellDictionaryManager.

These first two lines are typically executed only at the start of an application.

The next line,

parser=new JSpellParser(manager.getJSpellDictionaryLocal("English (US)"));

creates the JSpellParser object using the dictionary obtained from the JSpellDictionaryManager. In this case, we are retrieving the JSpellDictionaryLocal object for the English (US) dictionary, lex_enUS.jdx.

The next line,

dialog=new JSpellChecker();

creates (but does not show) the JSpell GUI object that displays errors and suggestions to the user.

The next line,

dialog.setParser(parser);

passes the previously created JSpellParser instance to the spell checker dialog. The GUI performs all spell checking through the parser, which in turn validates words through the JSpellDictionaryLocal object. As you will see later, by using this design you can access the JSpell Servlet spell checker with only minor modifications to this code.

The next line,

dialog.addComponent(text);

adds a JTextComponent to the JSpellChecker internal collection of JTextComponents to spell check. You may call this method with as many JTextComponent objects as necessary for your application.

Finally, the last line,

dialog.check();

displays the JSpell Spell Checker GUI and initiates the spell checking process.

See the next section for an example of turning this code into an application that accesses a JSpell Servlet to perform spell checking, instead of accessing the local disk.

SimpleDemo2.java -Application (Servlet Spell Check)

For some applications you may want the spell check requests centralized instead of having the spell check happen on the local disk. If you want to distribute a lightweight application without including the JSpell dictionary files, or, if you want to maintain a dictionary that you can update and modify centrally, then the best solution is to have the JSpell enabled application process spell check requests through the JSpell Spell Checker Servlet.

In order to use the JSpell Spell Checker Servlet you must have the jspellsdk.war file deployed to your J2EE compatible web server. See the appendices for information on deploying the JSpell Servlet to your specific web server.

Shown below is a modification to the previous example which uses the JSpellDictionaryServlet class instead of accessing the JSpell dictionary from the local disk.

package com.jspell.demo;
 
import java.awt.event.*;
import javax.swing.*;
 
import com.jspell.domain.net.*;
import com.jspell.domain.*;
import com.jspell.gui.*;
 
public class SimpleDemo2 extends JFrame {
 
  JSpellParser parser;
  JSpellChecker dialog;
  JSpellDictionaryServlet jdServlet = null;
  JButton check = new JButton("Spell Check");
  JTextArea text = new JTextArea("Type some missspelled text here!");
 
  public SimpleDemo2() {
    getContentPane().add("North", check);
    getContentPane().add("Center", text);
    check.addActionListener(new ActionListener() {
      public void actionPerformed(ActionEvent e) { {
          jdServlet = new JSpellDictionaryServlet();
          jdServlet.setURL("http://localhost/jspellsdk/servlet/JSpellServlet");
          jdServlet.open();
          jdServlet.setLanguage("English (US)");
          parser = new JSpellParser(jdServlet);
          dialog = new JSpellChecker();
          dialog.setParser(parser);
          dialog.addComponent(text);
          dialog.check();
        }
      }
    });
 
    setSize(200, 200);
    show();
  }
 
  public static void main(String[] args) {
    new SimpleDemo2();
  }
}

Converting a JSpell application to use the JSpell Spell Checker Servlet instead of local disk access is quite easy. Now we will discuss the sections of this example that are different than the previous example.

First, there is an additional import statement:

import com.jspell.domain.net.*;

this import statement makes the JSpell network related classes available to this class.

The next change is to replace the JSpellDictionaryManager with the JSpellDictionaryServlet class:

JSpellDictionaryServlet jdServlet=null;

Note: internally, the JSpell Servlet is using a JSpellDictionaryManager to manage its dictionary files.

Finally, set the communication parameters for the JSpell Servlet, such as the URL and the language in which to perform the spell check:

jdServlet=new JSpellDictionaryServlet();
jdServlet.setURL("http://localhost/jspellsdk/servlet/JSpellServlet");
jdServlet.open();
jdServlet.setLanguage("English (US)");
parser=new JSpellParser(jdServlet);

Note that the parser is initialized with the JSpellDictionaryServlet object instead of being initialized with the JSpellDictionaryLocal object.

SimpleDemo3.java -Applet (Servlet Spell Check)

A very common JSpell implementation scenario is to use JSpell for lightweight applet spell checking. This is accomplished in a manner similar to SimpleDemo2.java but instead of using a standalone Java application you use a Java applet. An example applet is shown below:

package com.jspell.demo;
 
import java.awt.event.*;
import javax.swing.*;
import com.jspell.domain.net.*;
import com.jspell.domain.*;
import com.jspell.gui.*;
 
public class SimpleDemo3 extends javax.swing.JApplet {
 
  JSpellParser parser;
  JSpellChecker dialog;
  JSpellDictionaryServlet jdServlet = null;
  JButton check = new JButton("Spell Check");
  JTextArea text = new JTextArea("Type some missspelled text here!");
 
  public void init() {
    getContentPane().add("North", check);
    getContentPane().add("Center", text);
    check.addActionListener(new ActionListener() {
      public void actionPerformed(ActionEvent e) {
        {
          jdServlet = new JSpellDictionaryServlet();
          jdServlet.setURL("http://localhost/jspellsdk/servlet/JSpellServlet");
          jdServlet.open();
          jdServlet.setLanguage("English (US)");
          parser = new JSpellParser(jdServlet);
          dialog = new JSpellChecker();
          dialog.setParser(parser);
          dialog.addComponent(text);
          dialog.check();
        }
      }
    });
    setSize(200, 200);
  }
}

Customizing the Spell Checker Behavior

Most spell checkers provide a way to customize the behavior of the spell check process, for example, if you want to make the spell checker flag repeated words as an error, or if you want words that are in UPPER CASE to be treated as correctly spelled you can normally set these as parameters of the spell checker.

JSpell provides the same capability via a number of method calls that you make to the JSpellDictionary objects. For example, to prevent the user from adding words to the dictionary, you would use the setLearnWords(false) method call on a JSpellDictionary object. Please refer to the included examples and the JSpell Java Spell Checker SDK Javadoc for a complete reference to the API.

Word Filtering

JSpell supports the concept of a word filter that is maintained at the server. This word filter allows you to create a block list which can be used as a 'naughty word filter' or for other specialized tasks in your application. The word filter may be used by placing a file called block.lst in your JSpell dictionary directory.

The file is a standard text file which can be edited with any text based editor such as notepad or vi. Each word that you want to block should appear on its own line with an optional replacement word next to it.

word [replacement]

When the user types a word in the block list it will be flagged as an error and asterisks will be shown as a suggested replacement. They will also not be able to use the Ignore, Ignore All, or Learn buttons. If a replacement word is specified then these buttons will be enabled. You can use the word filter functionality to expand acronyms used within your company, or to change internal secret project names to another value. An example block list is shown below:

NASA National_Aeronautics_and_Space_Administration
starfire classified_project_name
dummy
jerk
nincompoop

If a user tries to use the acronym NASA the suggested replacement will be "National Aeronautics and Space Administration". Note that underscores are replaced by spaces. If a user tries to use 'dummy', 'jerk', or 'nincompoop' then the suggested replacements will be a series of asterisks.

Using and Creating Dictionaries

One of the primary features of JSpell is advanced support of multilingual spell checking. The dictionary files have the format lex_xxXX.jdx where xx is the ISO language code and the XX is the ISO country code. These files are typically located in the lexicons directory. You may change the location of the dictionary files using the JSpellDictionaryManager class. If you want to change the location of the dictionaries for the JSpell Servlet you can change that in the web.xml configuration file for JSpell.

Using the JSpell Console utility you can create additional dictionaries that are usable by JSpell. The JSpell Console utility is a free download for users of any To create a dictionary using the JSpell Console you must have a source word list in UNICODE format. The console program will take your UNICODE format word list and create a JSpell compatible dictionary from it. The JSpell Console application has a built-in help system to guide you through the creation of dictionaries. For more information see the JSpell Console section.

Appendix A - Tomcat 3.x, 4.x and 5.x

If you already have Tomcat installed then you can install the JSpell Spell Checker by following these simple instructions.

Required Software

JSpell Java SDK WAR file jspellsdk.war

Installation

Copy the jspellsdk.war file into the Tomcat webapps directory. For example, if you used the default settings and installed Tomcat 4.x on the Windows platform this will be: \Program Files\Apache Tomcat 4.0\webapps.

You MUST have the Java(tm) SDK installed. The Java(tm) JRE is not sufficient. If you are installing Java(tm) and Tomcat for the first time make sure to install the Java(tm) SDK first.

Check Tomcat Installation

Restart Tomcat

Access the URL http://localhost:8080/jspellsdk/test.html and verify that you can successfully perform a spell check. After you've verified the spell checker is working properly you can continue with the Getting Started guide.

Appendix B - JRun

The JRun platform is one of the easiest platforms on which to install. You should be up and running in minutes.

Required Software

JSpell Java SDK WAR file jspellsdk.war

Installation

Start the JRun Management Console and login.

Select the correct server, usually 'default'.

Click on the J2EE Components link.

Click the 'Add' button in the Web Applications section.

Specify the path to the jspellsdk.war file and click 'Deploy'.

Check JRun Installation

Access the URL http://localhost:8100/jspellsdk/test.html and verify that you can successfully perform a spell check. After you've verified the spell checker is working properly you can continue with the Getting Started guide and Adding JSpell to Your Web Page.