Let's get started!

Creating a Lucene Index Using the CFX API and Java
If you've completed the setup and configuration steps above, open your favorite Java IDE (Notepad, VI, Eclipse, or even CF Studio all work just fine), create a new document, and save the document as "LuceneIndex.java". This file will contain the source code for the CFX tag that will perform the indexing of documents later in this article. The first items you'll need to add are the following Java import statements:

import java.io.*;
import java.util.*;
import com.allaire.cfx.*;
import org.apache.lucene.analysis.*;
import org.apache.lucene.document.*;
import org.apache.lucene.index.*;

The lines of code above "import" the java.io and java.util libraries, the com.allaire.cfx library (which I'll explain in a bit), and three Lucene libraries - all of which you'll use when writing the LuceneIndex class. If you're new to Java, you can think of the previous import statements as doing something analogous to using <cfinclude> to include a file that contains one or more user-defined functions. Basically, I've just imported a number of Java functions (although in Java you only have "methods" on "objects", not "functions") into the LuceneIndex class.

Next, you'll need to add the following line:

public class LuceneIndex implements CustomTag {

Without going into too much detail, this line of code says that the name of the class is "LuceneIndex" (the name of the file must match this name) and that it "implements" CustomTag. The word implements has a special meaning in Java; when you implement something, it means that the class you are writing will have a method with the same signature as each method in the class you are implementing (which is called an "interface"). In this case, I'm implementing the "CustomTag" interface, which has only one method:

public void processRequest(Request req, Response res)

Now that you understand interfaces (don't worry if you don't, interfaces and the "implements" keyword aren't that important to this article), you should know what the next line will be:

public void processRequest(Request req, Response res) {

Look familiar? It should! This is the method from the CustomTag interface that you must implement. Let's look a bit closer at it. There are two classes passed to this method: Request and Response. If you've done any work with ASP/VBScript or JSP, you might think that you understand these classes right away, but they aren't the same. We'll look at the Response class in the next section. The Request class contains seven methods, none of which deal with the "request" made by the browser (unlike the ASP request object or the JSP request object). I'm only going to cover two in this article: attributeExists() and getAttribute(), but if you're hungry for the details, you can read about all the methods by visiting the ColdFusion Java CFX reference resource at the end of this article. The method "getAttribute()" retrieves the value of the variable given as an attribute to the method. So, for example, if I wrote this in ColdFusion:

<cfx_luceneindex path="c:\cfusionmx\wwwroot\cfdocs\">

and I wanted to retrieve the value of the attribute "path" in the Java code, I'd write this:

req.getAttribute("path")

Simple right? In the same way, if I wanted to check that a specific attribute has been passed to the tag, I'd use the attributeExists() method. For instance, if I wanted to make sure that the attribute "path" has been passed to the Java code, I'd use a statement like this:

req.attributeExists("path")

Back to the LuceneIndex class. In order to index a directory or a file, you'll need to know which directory or file, where to create the index, whether to recurse the directories, and so on. To do so, you'll add the following lines of code:

String indexName = req.getAttribute("indexName");
String indexPath = req.getAttribute("indexPath");
String directory = req.getAttribute("directory");
String file = req.getAttribute("file");
String urlpath = req.getAttribute("urlpath");

For the sake of brevity, I'm not covering the error checking code, which you can see in the source code that you can (and should!) download below. Next, add a statement that checks to see if the user wants to "optimize" a Lucene index or "index" a directory of files:

if (action.equalsIgnoreCase("index")) {

Finally, you're ready to begin using Lucene to index a directory.

Analyzer analyzer = new StopAnalyzer();
IndexWriter writer;
try {
writer = new IndexWriter(indexPath, analyzer,
bCreateIndex.booleanValue());
if (req.attributeExists("directory")) {
File f = new File(directory);
if (f.exists() && f.isDirectory()) {
indexDirectory(urlpath, f,
recursive.booleanValue(), writer);
}
} else {
File f = new File(file);
indexFile(urlpath, f, writer);
}
writer.close();
} catch (java.io.IOException e) {
errors.add(e.toString());
}

Start by creating a Lucene Analyzer (in this case using the StopAnalyzer) object and a Lucene IndexWriter object, which are then used in the index process. You'll notice that the IndexWriter constructor and the indexFile()/indexDirectory() methods are wrapped in a try/catch block so that errors resulting from insufficient permissions and nonexistent directories/files are caught appropriately. I won't discuss indexFile() and indexDirectory() methods as they aren't pertinent to the topic at hand; you can find the source code for both methods in the LuceneIndex.java file.

To optimize a Lucene index, add these short bits of code:

StopAnalyzer analyzer = new org.apache.lucene.analysis.StopAnalyzer();
IndexWriter writer;
try {
writer = new IndexWriter(indexPath, analyzer, false);
writer.optimize();
} catch (java.io.IOException ex) {
ex.toString();
}

At this point, you're ready to save and compile LuceneIndex.java. Since I haven't included all the necessary code, I'd suggest that you download the source code and unzip the archive to

[cfusionhome]/wwwroot/WEB-INF/classes/

where [cfusionhome] is the directory that contains your ColdFusion MX installation. After completing that (and keeping in mind the location of both the cfx.jar and the lucene.jar file that you downloaded/located during the previous setup and configuration steps), you can compile LuceneIndex by bringing up a command prompt and typing the following from the [cfusionhome]\wwwroot\WEB-INF\classes\ directory:

C:\CFusionMX\wwwroot\WEB-INF\classes>javac -classpath
[path_to_lucene.jar];[path_to_cfx.jar] LuceneIndex.java

substituting the appropriate values for [path_to_lucene.jar] and [path_to_cfx.jar] like I did in Figure 1.

 

After successfully compiling LuceneIndex.java, you should have a file called "LuceneIndex.class" in the [cfusionhome]\wwwroot\WEB-INF\classes\ directory. In order to test out the code you've written so far, you need to make ColdFusion aware of its existence. To do that, log in to the ColdFusion Administrator, click on "CFX Tags" under "Extensions," and then click the "Register Java CFX" button. Enter the tag name (in this case "cfx_luceneindex"), the class name ("LuceneIndex"), and optionally, a description just like I have in Figure 2.

 

You can then test the indexing and optimizing operations by running a CFML script that contains the following code:

<cfx_luceneindex
action="index"
indexpath="c:\cfusionmx\wwwroot\cfxlucene\cfdocsindex\"
bCreateIndex="true"
directory="c:\cfusionmx\wwwroot\cfdocs\CFML_Reference\"
urlpath="http://localhost:8500/cfdocs/CFML_Reference/"
recursive="true">

again, substituting the appropriate values for your environment. I included a sample script in the source code called "test_luceneindex.cfm" that contains code for indexing a file, indexing a directory, and optimizing an index. All set to search that index? Great! Let's move to the next section...

Searching a Lucene Index Using the CFX API and Java
As in the previous section, start by creating a new file using your IDE; save this one as "LuceneSearch.java". I'll start off the new class by importing the appropriate libraries, just as I did in the previous example:

import java.util.*;
import com.allaire.cfx.*;
import org.apache.lucene.analysis.*;
import org.apache.lucene.document.*;
import org.apache.lucene.index.*;
import org.apache.lucene.queryParser.*;
import org.apache.lucene.search.*;

Not much different there, you can move quickly to the next lines:

public class LuceneSearch implements CustomTag {
public void processRequest(Request req, Response res) {

Again, use the "implements" keyword in the class definition, and then immediately add a method "processRequest()" that matches the method signature of the processRequest() method from the CustomTag class. After that use the req.getAttribute() method to retrieve the value of the attributes given in the tag:

String indexPath = req.getAttribute("index");
String queryString = req.getAttribute("keyword");
String r_query = req.getAttribute("r_query");

Perform some error checking (again removed for the sake of brevity) and then you're into the heart of the tag:

IndexSearcher searcher = null;
org.apache.lucene.search.Query luceneQuery = null;
Hits hits = null;
searcher = new IndexSearcher(IndexReader.open(indexPath) );
Analyzer analyzer = new StopAnalyzer();
luceneQuery = QueryParser.parse(queryString, "body", analyzer);
//parse the hits = searcher.search(luceneQuery);

String[] columns = { "URL", "TITLE", "SUMMARY" } ;
com.allaire.cfx.Query q = res.addQuery(r_query, columns) ;

for (int i = 0; i < hits.length(); i++) {

Document doc = hits.doc(i);
String doctitle = doc.get("title");
String url = doc.get("url");
String docSummary = doc.get("summary");

int iRow = q.addRow() ;
q.setData( iRow, 1, url) ;
q.setData( iRow, 2, doctitle);
q.setData( iRow, 3, docSummary);
}

This block of code creates an IndexSearcher object, a Lucene Query object, a Lucene Hits object, and an Analyzer object, all of which are used in various ways to parse the keyword into manageable bits and then search the index you created in the above example.

Remember the Request and Response classes I mentioned? In this example you're going to use the Response object, which has four methods, only three of which you'll probably use on a regular basis. The addQuery() method enables you to return a ColdFusion query to the calling template, which is what you'll do in this example.

Additionally, you can use the setVariable() method just like you might use the SetVariable function in ColdFusion - for example, to return a string or a number to the calling template. Finally, you can use the write() method to write text directly to the screen, just as you might use

<cfoutput>Hello World!</cfoutput>

or

WriteOutput("Hello World!");

when writing CFML code. Back to the last example, the portion of code that is pertinent to this article starts with these lines:

String[] columns = { "URL", "TITLE", "SUMMARY" } ;
com.allaire.cfx.Query q = res.addQuery(r_query, columns) ;

The first line creates an array of String objects: "URL", "TITLE", and "SUMMARY"; each represents the name of a column in a query. This array is passed to the method addQuery() of the Response object, along with the "r_query" value. After creating the query, loop over each "hit" that Lucene returned, using a "for" loop, and then add the URL, the TITLE, and the SUMMARY to the query:

q.setData( iRow, 1, url) ;
q.setData( iRow, 2, doctitle);
q.setData( iRow, 3, docSummary);

where iRow is the row number and 1, 2, and 3 represent the number of the column you're adding a value to.

I left out the error checking and try/catch statements so if you want to compile the code, again I'd suggest that you download and unzip the archive to the [cfusionhome]\wwwroot\WEB-INF\classes\ directory and then compile LuceneSearch.java by typing this from the command line:

cd [cfusionhome]\wwwroot\WEB-INF\classes
javac -classpath [path_to_lucene];[path_to_cfx] LuceneSearch.java

substituting the appropriate values for [cfusionhome], [path_to_lucene], and [path_to_cfx]. After successfully compiling the Java class, you should register the CFX tag in the ColdFusion Administrator (i.e., click on CFX Tags under Extensions and click the "Register Java CFX" button, tag name should be "cfx_lucenesearch", tag class should be "LuceneSearch"). You should be able to test the search functionality using the included "test_lucenesearch.cfm" script in the source code archive, or by creating a simple script that looks like this:

<cfx_lucenesearch
r_query="r_query"
index="c:\cfusionmx\wwwroot\cfxlucene\cfdocsindex\"
keyword="software">

Tips and Tricks
As with any technology, there are things you need to watch out for. Here are a couple I found while working with Java CFX tags:

Conclusion
The Java CFX Tag API enables developers to extend ColdFusion almost anywhere Java can travel. I hope that this article has given you an excellent introduction to writing CFX tags in Java and gets you rolling on your own Java CFX projects. I'd encourage you to download and explore the source code below in which I've included error checking code, try/catch blocks, and attribute validation, and to explore Lucene further.

Resources