org.carrot2.apiexample
Class Example

java.lang.Object
  org.carrot2.apiexample.Example

public final class Example
extends Object

This is an example of using the Carrot² API and components directly from a Java application. The walk-through starts in the main(String[]) method (command-line application's entry point).

Author:

Dawid Weiss

Constructor Summary

Example()

Method Summary

(package private) static void	displayResults(ArrayOutputComponent.Result result) In this method we display documents and clusters received from an output component of type ArrayOutputComponent.Result.
static void	main(String[] args) Carrot2 API example

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Example

public Example()

Method Detail

main

public static void main(String[] args)

Carrot² API example

Introduction

Carrot² is composed of components bound together in a processing chain. To start clustering search results we will need at least three components:

• input - anything that produces snippets to be clustered. Each snippet consists of a unique URL, a title and a fragment of text from the content of a document. Example input components available in Carrot² provide bridges to existing major search engines (Yahoo, Google), open source search engines (Lucene), but also adapt XMLs (such as RSS or OpenSearch). As a final resort, you can try to write your own input component using the examples available in the project.
• filters - typically a clustering component and a set of filters that it requires. Carrot² comes with a number of clustering components; each one implements a different algorithm and has different requirements concerning configuration and previous filters in the processing chain. You'll need to take a look at the demo applications (web application and local application) - there are full scripts configuring each clustering component there. In this example we will use Lingo clustering component and configure it directly from the source code.
• output - a clustering component typically produces instances of RawCluster. The role of an output component is to do something with clusters once you receive them from the clusterer. The easiest way is to save them in an array and wait until all the processing is finished (all the clusters are available). A more advanced application could use (display?) clusters as soon as they appear from the clustering component. In this example we will buffer the output clusters in an array.

Initialization

The next step after deciding which components to use is to create an instance of a LocalController which provides the facility for executing queries and assembling a fully functional processing chain. This is explained in initLocalController() method.

Running queries

Once you have a fully configured LocalController, running queries is quite trivial. The only thing you need to do is to invoke LocalController.query(String, String, java.util.Map) method, passing it a process identifier, a query and a Map of request parameters. These parameters can be used by certain components to alter their behaviour or settings for the duration of a single query. Each component will expose a different set of parameters, so you'll need to take a look at source code to see what is available.

Note that an instance of a LocalController is thread-safe and may (should!) be reused.

The result of running a query is an instance of a ProcessingResult interface. The actual output depends a lot on the last (output) component in the chain, so you'll need to see what is available. In our case, the result is a buffered array of snippets and clusters of type ArrayOutputComponent.Result. We can display documents (snippets) and clusters by fetching data from this object. This procedure is shown in displayResults(ArrayOutputComponent.Result) method.

Cleanup

No special cleanup is necessary when you close your application. Just let the garbage collector consume the resources taken by LocalController.

Other things to look at

This example configures the controller in a very "manual", step-by-step way to explain how things in Carrot² work. In the Web and local demo applications, however, you'll see that components and processes can be instantiated semi-automatically using Beanshell scripts and component autodiscovery. These are more advanced topics, refer to the source code of demo applications and JUnit test cases for details.

Parameters:

args - Command line arguments are not used in this application.

displayResults

static void displayResults(ArrayOutputComponent.Result result)

In this method we display documents and clusters received from an output component of type ArrayOutputComponent.Result.