org.carrot2.core

Class Controller

java.lang.Object

org.carrot2.core.Controller

All Implemented Interfaces:

Closeable, AutoCloseable

public final class Controller
extends Object
implements Closeable

A controller implementing the life cycle described in IProcessingComponent. Use ControllerFactory to obtain controllers with different characteristics, e.g. with or without pooling of IProcessingComponent, with or without caching of the processing results. If further customizations are needed, you can provide your own IProcessingComponentManager implementation.

Calls to process(Map, Class...) are thread-safe, although some care should be given to initialization. Controller instance should be initialized (using any of the init() methods) before other threads are allowed to see its instance. dispose() should be called after all threads leave process(Map, Class...) and process(Map, Object...).

Notice for IProcessingComponent developers: if data caching is used, values of Output attributes produced by the components whose output is to be cached (e.g., the Document instances in case IDocumentSource output is cached) may be accessed concurrently and therefore must be thread-safe.

See Also:

ControllerFactory

Constructor Summary

Constructors

Constructor and Description
Controller(IProcessingComponentManager componentManager) Creates a controller with a custom IProcessingComponentManager, for experts only.

Method Summary

Modifier and Type	Method and Description
void	close() Implement closeable so that controller can be closed with Java 1.7 resource block.
void	dispose() Shuts down this controller.
ControllerStatistics	getStatistics() Returns current statistics related to the processing performed in this controller, including: number of queries, number of successful queries, processing times, cache utilization if applicable.
Controller	init() Initializes this controller with an empty Init-time attributes map.
Controller	init(Map<String,Object> attributes) Initializes this controller with the provided @Init-time attributes.
Controller	init(Map<String,Object> attributes, ProcessingComponentConfiguration... configurations) Initializes this controller with the provided Init-time attributes and additional component-specific Init-time attributes.
ProcessingResult	process(List<Document> documents, String queryHint, Class<?>... processingComponentClasses) Convenience method for clustering the provided list of Documents.
ProcessingResult	process(Map<String,Object> attributes, Class<?>... processingComponentClasses) Performs processing using components designated by their class.
ProcessingResult	process(Map<String,Object> attributes, Object... processingComponentClassesOrIds) Performs processing using components designated by their identifiers or classes.
ProcessingResult	process(Map<String,Object> attributes, String... processingComponentIdsOrClassNames) Performs processing using components designated by their identifiers.
ProcessingResult	process(String query, Integer results, Class<?>... processingComponentClasses) Convenience method for performing processing with the provided query and number of results.

Methods inherited from class java.lang.Object

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

Constructor Detail

Controller

public Controller(IProcessingComponentManager componentManager)

Creates a controller with a custom IProcessingComponentManager, for experts only. Use ControllerFactory to obtain controllers in typical configurations.

Method Detail

init

public Controller init()
                throws ComponentInitializationException

Initializes this controller with an empty Init-time attributes map. Calling this method is optional, if process(Map, Object...) is called on an uninitialized controller, init() will be called automatically.

Returns:

this controller for convenience

Throws:

ComponentInitializationException

init

public Controller init(Map<String,Object> attributes)
                throws ComponentInitializationException

Initializes this controller with the provided @Init-time attributes. The provided attributes will be applied to all processing components managed by this controller. Init-time attributes can be overridden at processing time, see process(Map, Class...) or process(Map, Object...).

Parameters:

attributes - initialization-time attributes to be applied to all processing components in this controller

Returns:

this controller for convenience

Throws:

ComponentInitializationException

init

public Controller init(Map<String,Object> attributes,
                       ProcessingComponentConfiguration... configurations)
                throws ComponentInitializationException

Initializes this controller with the provided Init-time attributes and additional component-specific Init-time attributes. Init-time attributes can be overridden at processing time, see process(Map, Class...) or process(Map, Object...).

Parameters:

attributes - initialization-time attributes to be applied to all processing components in this controller

configurations - additional component-specific Init-time attributes

Returns:

this controller for convenience

Throws:

ComponentInitializationException

process

public ProcessingResult process(String query,
                                Integer results,
                                Class<?>... processingComponentClasses)
                         throws ProcessingException

Convenience method for performing processing with the provided query and number of results. The typical use cases for this method is fetching the specified number of results from an IDocumentSource and, optionally, clustering them with an IClusteringAlgorithm.

For a method allowing to pass more attributes, see: process(Map, Class...).

Parameters:

query - the query to use during processing

results - the number of results to fetch. If null is provided, the default number of results will be requested.

processingComponentClasses - classes of components to perform processing in the order they should be arranged in the pipeline. Each provided class must implement IProcessingComponent.

Returns:

results of the processing

Throws:

ProcessingException

process

public ProcessingResult process(List<Document> documents,
                                String queryHint,
                                Class<?>... processingComponentClasses)
                         throws ProcessingException

Convenience method for clustering the provided list of Documents. If the query that generated the documents is available, it can be provided in the queryHint parameter to increase the quality of clusters.

For a method allowing to pass more attributes, see: process(Map, Class...).

Parameters:

documents - the documents to cluster

queryHint - the query that generated the documents, optional, can be null if not available.

processingComponentClasses - classes of components to perform processing in the order they should be arranged in the pipeline. Each provided class must implement IProcessingComponent.

Returns:

results of the processing

Throws:

ProcessingException

process

public ProcessingResult process(Map<String,Object> attributes,
                                Class<?>... processingComponentClasses)
                         throws ProcessingException

Performs processing using components designated by their class. If you initialized this controller using init(Map, ProcessingComponentConfiguration...) and would like to designate components by their identifiers, call process(Map, String...) or process(Map, Object...).

Parameters:

attributes - attributes to be used during processing. Input attributes will be transferred from this map to the corresponding fields. Keys of the map are computed based on the key parameter of the Attribute annotation. Controller will not modify the provided map, processing results will be available in the returned ProcessingResult.

processingComponentClasses - classes of components to perform processing in the order they should be arranged in the pipeline. Each provided class must implement IProcessingComponent.

Returns:

results of the processing

Throws:

ProcessingException

process

public ProcessingResult process(Map<String,Object> attributes,
                                String... processingComponentIdsOrClassNames)
                         throws ProcessingException

Performs processing using components designated by their identifiers. Identifiers can be assigned to component configurations using the init() method.

Parameters:

attributes - attributes to be used during processing. Input attributes will be transferred from this map to the corresponding fields. Keys of the map are computed based on the key parameter of the Attribute annotation. Controller will not modify the provided map, processing results will be available in the returned ProcessingResult.

processingComponentIdsOrClassNames - identifiers of components to perform processing in the order they should be arranged in the pipeline. Fully-qualified class names are also accepted. Each provided class must implement IProcessingComponent.

Returns:

results of the processing

Throws:

ProcessingException

See Also:

init(Map, ProcessingComponentConfiguration...)

process

public ProcessingResult process(Map<String,Object> attributes,
                                Object... processingComponentClassesOrIds)
                         throws ProcessingException

Performs processing using components designated by their identifiers or classes.

Parameters:

attributes - attributes to be used during processing. Input attributes will be transferred from this map to the corresponding fields. Keys of the map are computed based on the key parameter of the Attribute annotation. Controller will not modify the provided map, processing results will be available in the returned ProcessingResult.

processingComponentClassesOrIds - classes or identifiers of components to perform processing in the order they should be arranged in the pipeline. Fully-qualified class names are also accepted. Each provided class must implement IProcessingComponent.

Returns:

results of the processing

Throws:

ProcessingException

See Also:

init(Map, ProcessingComponentConfiguration...)

dispose

public void dispose()

Shuts down this controller. For proper shut down, make sure this method is called after all threads left the processing methods. No calls processing will be performed after invoking this method.

close

public void close()

Implement closeable so that controller can be closed with Java 1.7 resource block.

Specified by:

close in interface Closeable

Specified by:

close in interface AutoCloseable

getStatistics

public ControllerStatistics getStatistics()

Returns current statistics related to the processing performed in this controller, including: number of queries, number of successful queries, processing times, cache utilization if applicable.