org.carrot2.source.xml

Class XmlDocumentSource

java.lang.Object

org.carrot2.core.ProcessingComponentBase

org.carrot2.source.xml.XmlDocumentSource

All Implemented Interfaces:

IDocumentSource, IProcessingComponent

@Bindable(prefix="XmlDocumentSource",
          inherit=CommonAttributes.class)
public class XmlDocumentSource
extends ProcessingComponentBase
implements IDocumentSource

Fetches documents from XML files and streams. For additional flexibility, an XSLT stylesheet can be applied to the XML stream before it is deserialized into Carrot2 data.

See Also:

xml

Field Summary

Fields

Modifier and Type	Field and Description
List<Cluster>	clusters If readClusters is true and clusters are present in the input XML, they will be deserialized and exposed to components further down the processing chain.
List<Document>	documents Documents read from the XML data.
String	query After processing this field may hold the query read from the XML data, if any.
boolean	readAll If true, all documents are read from the input XML stream, regardless of the limit set by results.
boolean	readClusters If clusters are present in the input XML they will be read and exposed to components further down the processing chain.
int	results The maximum number of documents to read from the XML data if readAll is false.
String	title The title (file name or query attribute, if present) for the search result fetched from the resource.
IResource	xml The resource to load XML data from.
Map<String,String>	xmlParameters Values for custom placeholders in the XML URL.
IResource	xslt The resource to load XSLT stylesheet from.
Map<String,String>	xsltParameters Parameters to be passed to the XSLT transformer.

Constructor Summary

Constructors

Constructor and Description
XmlDocumentSource()

Method Summary

Methods

Modifier and Type	Method and Description
void	init(IControllerContext context) Invoked after component's attributes marked with Init and Input annotations have been bound, but before calls to any other methods of this component.
void	process() Performs the processing required to fulfill the request.

Methods inherited from class org.carrot2.core.ProcessingComponentBase

afterProcessing, beforeProcessing, dispose, getContext, getSharedExecutor

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.carrot2.core.IProcessingComponent

afterProcessing, beforeProcessing, dispose

Field Detail

xml

@Input
@Processing
@Attribute
@Required
@Internal(configuration=true)
@Label(value="XML resource")
@Level(value=BASIC)
@Group(value="XML data")
public IResource xml

The resource to load XML data from. You can either create instances of IResource implementations directly or use ResourceLookup to look up IResource instances from a variety of locations.

One special IResource implementation you can use is URLResourceWithParams. It allows you to specify attribute placeholders in the URL that will be replaced with actual values at runtime. The placeholder format is ${attribute}. The following common attributes will be substituted:

• query will be replaced with the current query being processed. If the query has not been provided, this attribute will fall back to an empty string.
• results will be replaced with the number of results requested. If the number of results has not been provided, this attribute will be substituted with an empty string.

Additionally, custom placeholders can be used. Values for the custom placeholders should be provided in the xmlParameters attribute.

xslt

@Input
@Processing
@Attribute
@Internal(configuration=true)
@Label(value="XSLT stylesheet")
@Level(value=MEDIUM)
@Group(value="XML transformation")
public IResource xslt

The resource to load XSLT stylesheet from. The XSLT stylesheet is optional and is useful when the source XML stream does not follow the Carrot2 format. The XSLT transformation will be applied to the source XML stream, the transformed XML stream will be deserialized into Documents.

The XSLT IResource can be provided both on initialization and processing time. The stylesheet provided on initialization will be cached for the life time of the component, while processing-time style sheets will be compiled every time processing is requested and will override the initialization-time stylesheet.

To pass additional parameters to the XSLT transformer, use the xsltParameters attribute.

xmlParameters

@Input
@Processing
@Attribute
@Internal(configuration=true)
@Label(value="XML parameters")
@Level(value=ADVANCED)
@Group(value="XML data")
public Map<String,String> xmlParameters

Values for custom placeholders in the XML URL. If the type of resource provided in the xml attribute is URLResourceWithParams, this map provides values for custom placeholders found in the XML URL. Keys of the map correspond to placeholder names, values of the map will be used to replace the placeholders. Please see xml for the placeholder syntax.

xsltParameters

@Input
@Processing
@Attribute
@Internal(configuration=true)
@Label(value="XSLT parameters")
@Level(value=ADVANCED)
@Group(value="XML transformation")
public Map<String,String> xsltParameters

Parameters to be passed to the XSLT transformer. Keys of the map will be used as parameter names, values of the map as parameter values.

query

@Input
@Output
@Processing
@Attribute(key="query",
           inherit=true)
public String query

After processing this field may hold the query read from the XML data, if any. For the semantics of this field on input, see xml.

results

@Input
@Processing
@Attribute(key="results",
           inherit=true)
@IntRange(min=1)
public int results

The maximum number of documents to read from the XML data if readAll is false.

readClusters

@Input
@Processing
@Attribute
@Label(value="Read clusters from input")
@Level(value=BASIC)
@Group(value="XML transformation")
public boolean readClusters

If clusters are present in the input XML they will be read and exposed to components further down the processing chain.

readAll

@Input
@Processing
@Attribute
@Label(value="Read all documents")
@Level(value=BASIC)
@Group(value="Search query")
public boolean readAll

If true, all documents are read from the input XML stream, regardless of the limit set by results.

title

@Output
@Processing
@Attribute(key="processing-result.title",
           inherit=true)
public String title

The title (file name or query attribute, if present) for the search result fetched from the resource.

documents

@Processing
@Output
@Attribute(key="documents",
           inherit=true)
public List<Document> documents

Documents read from the XML data.

clusters

@Processing
@Input
@Output
@Internal
@Attribute(key="clusters",
           inherit=true)
public List<Cluster> clusters

If readClusters is true and clusters are present in the input XML, they will be deserialized and exposed to components further down the processing chain.

Constructor Detail

XmlDocumentSource

public XmlDocumentSource()

Method Detail

init

public void init(IControllerContext context)

Description copied from interface: IProcessingComponent

Invoked after component's attributes marked with Init and Input annotations have been bound, but before calls to any other methods of this component. After a call to this method completes without an exception, attributes marked with Init Output will be collected. In this method, components should perform initializations based on the initialization-time attributes. This method is called once in the life time of a processing component instance.

Specified by:

init in interface IProcessingComponent

Overrides:

init in class ProcessingComponentBase

Parameters:

context - An instance of IControllerContext of the controller to which this component instance will be bound.

process

public void process()
             throws ProcessingException

Description copied from interface: IProcessingComponent

Performs the processing required to fulfill the request. This method is called once per request.

Specified by:

process in interface IProcessingComponent

Overrides:

process in class ProcessingComponentBase

Throws:

ProcessingException - when processing failed. If thrown, the IProcessingComponent.afterProcessing() method will be called and the component will be ready to accept further requests or to be disposed of. Finally, the exception will be rethrown from the controller method that caused the component to perform processing.