/*
* GeoTools - The Open Source Java GIS Toolkit
* http://geotools.org
*
* (C) 2006-2008, Open Source Geospatial Foundation (OSGeo)
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation;
* version 2.1 of the License.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*/
package org.geotools.filter.text.ecql;
import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStreamReader;
import java.util.Iterator;
import java.util.List;
import javax.xml.transform.TransformerException;
import org.geotools.filter.FilterTransformer;
import org.geotools.filter.text.commons.CompilerUtil;
import org.geotools.filter.text.commons.ExpressionToText;
import org.geotools.filter.text.cql2.CQLException;
import org.opengis.filter.Filter;
import org.opengis.filter.FilterFactory;
import org.opengis.filter.expression.Expression;
/**
* <b>Extended Contextual Query Language (ECQL)</b> is an extension of <b>CQL</b>. This class presents the operations available
* to parse the ECQL language and generates the correspondent filter.
* </p>
* <p>
* <h2>Usage</h2>
* Here are some usage examples. Refer to the
* <a href="http://docs.codehaus.org/display/GEOTOOLS/ECQL+Parser+Design">BNF of grammar</a> to see what exactly you can do.
*
* <pre>
* <code>
* Filter filter = ECQL.toFilter(<b>"POP_RANK > 6"</b>);
*
* Filter filter = ECQL.toFilter(<b>"POP_RANK > 3 AND POP_RANK < 6"</b>);
*
* Filter filter = ECQL.toFilter(<b>"area(the_geom) > 3000"</b>);
*
* Filter filter = ECQL.toFilter(<b>"Name LIKE '%omer%'"</b>);
*
* Filter filter = ECQL.toFilter(<b>"RELATE( the_geom1,the_geom2) like 'T**F*****'"</b>);
*
* Filter filter = ECQL.toFilter(<b>"DISJOINT(buffer(the_geom, 10) , POINT(1 2))"</b>);
*
* Filter filter = ECQL.toFilter(<b>"IN ('river.1', 'river.2')"</b>);
*
* Filter filter = ECQL.toFilter(<b>"LENGHT IN (4100001,4100002, 4100003 )"</b>);
*
* List <Filter> list = ECQL.toFilterList(<b>"LENGHT = 100; NAME like '%omer%'"</b>);
*
* Expression expression = ECQL.toExpression(<b>"LENGHT + 100"</b>);
*
* </code>
* </pre>
*
* The reverse process is possible too. To generate the ECQL associated to a filter you should use the <b>toCQL(...)</b> methods.
* </p>
* @author Jody Garnett
* @author Mauricio Pazos (Axios Engineering)
*
* @since 2.6
*
*
*
* @source $URL$
*/
public class ECQL {
private ECQL(){
// do nothing, private constructor
// to indicate it is a pure utility class
}
/**
* Parses the input string in ECQL format into a Filter, using the
* systems default FilterFactory implementation.
*
* @param ECQLPredicate
* a string containing a query predicate in ECQL format.
* @return a {@link Filter} equivalent to the constraint specified in
* <code>ecqlPredicate</code>.
*/
public static Filter toFilter(final String ecqlPredicate)
throws CQLException {
Filter filter = ECQL.toFilter(ecqlPredicate, null);
return filter;
}
/**
* Parses the input string in ECQL format into a Filter, using the
* provided FilterFactory.
*
* @param ecqlPredicate
* a string containing a query predicate in ECQL format.
* @param filterFactory
* the {@link FilterFactory} to use for the creation of the
* Filter. If it is null the method finds the default implementation.
* @return a {@link Filter} equivalent to the constraint specified in
* <code>Predicate</code>.
*/
public static Filter toFilter(final String ecqlPredicate, final FilterFactory filterFactory)
throws CQLException {
ECQLCompilerFactory compilerFactory = new ECQLCompilerFactory();
Filter result = CompilerUtil.parseFilter(ecqlPredicate, compilerFactory, filterFactory);
return result;
}
/**
* Parses the input string in ECQL format into an Expression, using the
* systems default {@link FilterFactory} implementation.
*
* @param ecqlExpression a string containing an ECQL expression.
* @return a {@link Expression} equivalent to the one specified in
* <code>ecqlExpression</code>.
*/
public static Expression toExpression(String ecqlExpression)
throws CQLException {
return toExpression(ecqlExpression, null);
}
/**
* Parses the input string in ECQL format and makes the correspondent Expression ,
* using the provided FilterFactory.
*
* @param ecqlExpression
* a string containing a ECQL expression.
*
* @param filterFactory
* the {@link FilterFactory} to use for the creation of the
* Expression. If it is null the method finds the default implementation.
* @return a {@link Filter} equivalent to the constraint specified in
* <code>ecqlExpression</code>.
*/
public static Expression toExpression(final String ecqlExpression,
final FilterFactory filterFactory) throws CQLException {
ECQLCompilerFactory compilerFactory = new ECQLCompilerFactory();
Expression expression = CompilerUtil.parseExpression(ecqlExpression, compilerFactory, filterFactory);
return expression;
}
/**
* Parses the input string, which has to be a list of ECQL predicates
* separated by "<code>;</code>" into a {@link List} of
* {@link Filter}, using the provided FilterFactory.
*
* @param ecqlSequencePredicate
* a list of ECQL predicates separated by "<code>;</code>"
*
* @return a List of {@link Filter}, one for each input ECQL statement
*/
public static List<Filter> toFilterList(final String ecqlSequencePredicate)
throws CQLException {
return toFilterList(ecqlSequencePredicate, null);
}
/**
* Parses the input string, which has to be a list of ECQL predicates
* separated by "<code>;</code>" into a {@link List} of
* {@link Filter}, using the provided FilterFactory.
*
* @param ecqlSequencePredicate a ECQL predicate sequence
* @param filterFactory the factory used to make the filters
* @return a List of {@link Filter}, one for each input ECQL statement
* @throws CQLException
*/
public static List<Filter> toFilterList(final String ecqlSequencePredicate, FilterFactory filterFactory)
throws CQLException {
ECQLCompilerFactory compilerFactory = new ECQLCompilerFactory();
List<Filter> filters = CompilerUtil.parseFilterList(ecqlSequencePredicate, compilerFactory, filterFactory);
return filters;
}
/**
* Generates the ecql predicates associated to the {@link List} of {@link Filter}s object.
*
* @param filterList
* @return ecql predicates separated by ";"
*/
public static String toCQL( List<Filter> filterList ){
FilterToECQL toECQL = new FilterToECQL();
StringBuilder output = new StringBuilder();
Iterator<Filter> iter = filterList.iterator();
while( iter.hasNext() ){
Filter filter = iter.next();
filter.accept( toECQL, output );
if(iter.hasNext() ){
output.append("; ");
}
}
return output.toString();
}
/**
* Generates the ecql predicate associated to the {@link Filter} object.
*
* @param filter
* @return ecql predicate
*/
public static String toCQL( Filter filter ){
FilterToECQL toCQL = new FilterToECQL();
StringBuilder output = (StringBuilder) filter.accept( toCQL, new StringBuilder() );
return output.toString();
}
/**
* Generates the expression text associated to the {@link Expression} object.
*
* @param filter
* @return expression as text
*/
public static String toCQL( Expression expression ){
ExpressionToText toECQL = new ExpressionToText();
StringBuilder output = (StringBuilder) expression.accept( toECQL, new StringBuilder() );
return output.toString();
}
/**
* Command line expression tester used to try out filters and expressions.
* @param args
*/
public static final void main(String[] args) {
System.out.println("ECQL Filters Tester");
System.out.println("Seperate with \";\" or \"quit\" to finish)");
BufferedReader reader = new BufferedReader(new InputStreamReader(System.in));
FilterTransformer filterTransformer = new FilterTransformer();
filterTransformer.setIndentation(4);
while (true) {
System.out.print(">");
String line = null;
try {
line = reader.readLine();
if (line.equals("quit")) {
System.out.println("Bye!");
break;
}
List<Filter> filters = ECQL.toFilterList(line);
for( Filter filter : filters ){
System.out.println();
filterTransformer.transform( filter, System.out);
}
} catch (IOException e1) {
e1.printStackTrace();
} catch (CQLException cqlex) {
System.out.println(cqlex.getSyntaxError());
} catch (TransformerException e) {
e.printStackTrace();
}
}
}
}