org.antforge.waqlpp.core
Interface PreprocessorEngine


public interface PreprocessorEngine

The WAQL preprocessor engine is the central preprocessor API also representing the current preprocessor state. There are three main state-changing operations for the engine, which are typically called in the given order:

  1. Parsing: Reads and parses the WAQL query in textual form from the input and constructs an intermediate representation out of it. The input is read as a whole and any syntactical or grammatical anomalies will be discovered during this phase.
  2. Resolving of data dependencies: At this point the engine has generated a list of all unresolved data dependencies contained in the WAQL query. Those dependencies have to be resolved by the application before the actual transformation can be done.
  3. Transformation: Writes the final XQuery (without any WAQL extensions) to the output. This is the last phase in the preprocessor life-cycle.

Author:
Michael Starzinger

Method Summary
 void addDataPrinter(DataPrinter printer)
          Adds a new data printer on top of the printer pipeline.
 java.util.Collection<DataDependency> getDependencies()
          Returns available unresolved data dependencies from the original query.
 void parse(java.io.InputStream input)
          Parses a WAQL query in textual form from the given input stream.
 void resolveDependency(DataDependency dependency, java.lang.Object content)
          Resolves the given data dependency by providing actual content.
 void transform(java.io.OutputStream output)
          Transforms the WAQL query into a valid XQuery (without any WAQL extensions) and writes it to the given output stream.
 

Method Detail

parse

void parse(java.io.InputStream input)
           throws MalformedQueryException
Parses a WAQL query in textual form from the given input stream. The input is read as a whole and any syntactical oder grammatical anomalies will be discovered during this phase.

Parameters:
input - An input stream of the WAQL query to be consumed.
Throws:
MalformedQueryException - In case of syntactical oder grammatical errors in the input.

getDependencies

java.util.Collection<DataDependency> getDependencies()
Returns available unresolved data dependencies from the original query. Those dependencies which already have been resolved will be excluded. In case of nested dependencies only the innermost one will be included. Note that you should regularly retrieve the dependencies after resolving with resolveDependency(org.antforge.waqlpp.core.DataDependency, java.lang.Object) because new ones might become available.

Returns:
The collection of available unresolved data dependencies.

resolveDependency

void resolveDependency(DataDependency dependency,
                       java.lang.Object content)
Resolves the given data dependency by providing actual content. The content object will be inserted into the original query in place of the data dependency. The conversion of the content object into a textual representation will be done by the printer pipeline configured for this engine, see DataPrinter for details about that. Note that resolving dependencies can generate new ones in case of nested dependencies in the input. The application should therefore call getDependencies() afterwards to retrieve those new dependencies.

Parameters:
dependency - The data dependency to be resolved.
content - An object representing the content to be inserted.

addDataPrinter

void addDataPrinter(DataPrinter printer)
Adds a new data printer on top of the printer pipeline. Those printers will be used to convert content objects into a textual representation. Take a look at the DataPrinter documentation for details about how the printer pipeline works.

Parameters:
printer - The data printer to be added to the pipeline.

transform

void transform(java.io.OutputStream output)
               throws UnresolvedDependencyException
Transforms the WAQL query into a valid XQuery (without any WAQL extensions) and writes it to the given output stream. Note that all data dependencies should have been resolved beforehand.

Parameters:
output - An output stream for the final XQuery.
Throws:
UnresolvedDependencyException - In case the query still contains unresolved data dependencies.