org.geotools.filter
Class SQLEncoder

java.lang.Object
  org.geotools.filter.SQLEncoder

All Implemented Interfaces:

FilterVisitor

Direct Known Subclasses:

SQLEncoderBBOX, SQLEncoderDB2, SQLEncoderHsql, SQLEncoderLocationsXY, SQLEncoderMySQL, SQLEncoderOracle, SQLEncoderPostgis, SQLEncoderSDE

public class SQLEncoder

extends java.lang.Object

implements FilterVisitor

Encodes a filter into a SQL WHERE statement. It should hopefully be generic enough that any SQL database will work with it, though it has only been tested with MySQL and Postgis. This generic SQL encoder should eventually be able to encode all filters except Geometry Filters (currently LikeFilters are not yet fully implemented, but when they are they should be generic enough). This is because the OGC's SFS for SQL document specifies two ways of doing SQL databases, one with native geometry types and one without. To implement an encoder for one of the two types simply subclass off of this encoder and put in the proper GeometryFilter visit method. Then add the filter types supported to the capabilities in the static capabilities.addType block.

Author:

Chris Holmes, TOPP

Task:

TODO: Implement LikeFilter encoding, need to figure out escape chars, the rest of the code should work right. Once fixed be sure to add the LIKE type to capabilities, so others know that they can be encoded., REVISIT: need to figure out exceptions, we're currently eating io errors, which is bad. Probably need a generic visitor exception.

Field Summary

protected FIDMapper	mapper the fid mapper used to encode the fid filters
protected java.io.Writer	out where to write the constructed string from visiting the filters.

Constructor Summary

SQLEncoder()
Empty constructor

SQLEncoder(java.io.Writer out, Filter filter)
Convenience constructor to perform the whole encoding process at once.

Method Summary

protected FilterCapabilities	createFilterCapabilities() Sets the capabilities of this filter.
java.lang.String	encode(Filter filter) Performs the encoding, returns a string of the encoded SQL.
void	encode(java.io.Writer out, Filter filter) Performs the encoding, sends the encoded sql to the writer passed in.
java.lang.String	escapeName(java.lang.String name) Surrounds a name with the SQL escape character.
FilterCapabilities	getCapabilities() Describes the capabilities of this encoder.
protected java.lang.String	getColnameEscape() Deprecated. the escapeName method is preferred over this, it automatically returns the name properly escaped, since that's all getColnameEscape was being used for.
void	setColnameEscape(java.lang.String escape) Deprecated. Use setSqlNameEscape instead, as it is more aptly named.
void	setFIDMapper(FIDMapper mapper) Sets the FIDMapper that will be used in subsequente visit calls.
void	setSqlNameEscape(java.lang.String escape) Sets the SQL name escape string.
void	visit(AttributeExpression expression) Writes the SQL for the attribute Expression.
void	visit(BetweenFilter filter) Writes the SQL for the Between Filter.
void	visit(CompareFilter filter) Writes the SQL for a Compare Filter.
void	visit(Expression expression) Writes the SQL for the attribute Expression.
void	visit(FidFilter filter) Encodes an FidFilter.
void	visit(Filter filter) This should never be called.
void	visit(FunctionExpression expression) Writes sql for a function expression.
void	visit(GeometryFilter filter) Called when accept is called on a Geometry Filter.
void	visit(LikeFilter filter) Writes the SQL for the Like Filter.
void	visit(LiteralExpression expression) Export the contents of a Literal Expresion
void	visit(LogicFilter filter) Writes the SQL for the Logic Filter.
void	visit(MathExpression expression) Writes the SQL for the Math Expression.
void	visit(NullFilter filter) Writes the SQL for the Null Filter.
protected void	visitLiteralGeometry(LiteralExpression expression) Subclasses must implement this method in order to encode geometry filters according to the specific database implementation

Methods inherited from class java.lang.Object

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

Field Detail

out

protected java.io.Writer out

where to write the constructed string from visiting the filters.

mapper

protected FIDMapper mapper

the fid mapper used to encode the fid filters

Constructor Detail

SQLEncoder

public SQLEncoder()

Empty constructor

SQLEncoder

public SQLEncoder(java.io.Writer out,
                  Filter filter)
           throws SQLEncoderException

Convenience constructor to perform the whole encoding process at once.

Parameters:

out - the writer to encode the SQL to.

filter - the Filter to be encoded.

Throws:

SQLEncoderException - If there were problems encoding

Method Detail

setFIDMapper

public void setFIDMapper(FIDMapper mapper)

Sets the FIDMapper that will be used in subsequente visit calls. There must be a FIDMapper in order to invoke the FIDFilter encoder.

Parameters:

mapper -

createFilterCapabilities

protected FilterCapabilities createFilterCapabilities()

Sets the capabilities of this filter.

Returns:

FilterCapabilities for this Filter

encode

public void encode(java.io.Writer out,
                   Filter filter)
            throws SQLEncoderException

Performs the encoding, sends the encoded sql to the writer passed in.

Parameters:

out - the writer to encode the SQL to.

filter - the Filter to be encoded.

Throws:

SQLEncoderException - If filter type not supported, or if there were io problems.

encode

public java.lang.String encode(Filter filter)
                        throws SQLEncoderException

Performs the encoding, returns a string of the encoded SQL.

Parameters:

filter - the Filter to be encoded.

Returns:

the string of the SQL where statement.

Throws:

SQLEncoderException - If filter type not supported, or if there were io problems.

getCapabilities

public FilterCapabilities getCapabilities()

Describes the capabilities of this encoder.

Performs lazy creation of capabilities.

Returns:

The capabilities supported by this encoder.

visit

public void visit(Filter filter)

This should never be called. This can only happen if a subclass of AbstractFilter failes to implement its own version of accept(FilterVisitor);

Specified by:

visit in interface FilterVisitor

Parameters:

filter - The filter to visit

Throws:

java.lang.RuntimeException - for IO Encoding problems.

Task:

REVISIT: I don't think Filter.NONE and Filter.ALL should be handled here. They should have their own methods, but they don't have interfaces, so I don't know if that's possible.

visit

public void visit(BetweenFilter filter)
           throws java.lang.RuntimeException

Writes the SQL for the Between Filter.

Specified by:

visit in interface FilterVisitor

Parameters:

filter - the Filter to be visited.

Throws:

java.lang.RuntimeException - for io exception with writer

visit

public void visit(LikeFilter filter)
           throws java.lang.UnsupportedOperationException

Writes the SQL for the Like Filter. Assumes the current java implemented wildcards for the Like Filter: . for multi and .? for single. And replaces them with the SQL % and _, respectively. Currently does nothing, and should not be called, not included in the capabilities.

Specified by:

visit in interface FilterVisitor

Parameters:

filter - the Like Filter to be visited.

Throws:

java.lang.UnsupportedOperationException - always, as likes aren't implemented yet.

Task:

REVISIT: Need to think through the escape char, so it works right when Java uses one, and escapes correctly with an '_'.

visit

public void visit(LogicFilter filter)
           throws java.lang.RuntimeException

Writes the SQL for the Logic Filter.

Specified by:

visit in interface FilterVisitor

Parameters:

filter - the logic statement to be turned into SQL.

Throws:

java.lang.RuntimeException - for io exception with writer

visit

public void visit(CompareFilter filter)
           throws java.lang.RuntimeException

Writes the SQL for a Compare Filter.

Specified by:

visit in interface FilterVisitor

Parameters:

filter - the comparison to be turned into SQL.

Throws:

java.lang.RuntimeException - for io exception with writer

visit

public void visit(NullFilter filter)
           throws java.lang.RuntimeException

Writes the SQL for the Null Filter.

Specified by:

visit in interface FilterVisitor

Parameters:

filter - the null filter to be written to SQL.

Throws:

java.lang.RuntimeException - for io exception with writer

visit

public void visit(FidFilter filter)

Encodes an FidFilter.

Specified by:

visit in interface FilterVisitor

Parameters:

filter -

Throws:

java.lang.RuntimeException - DOCUMENT ME!

See Also:

visit(org.geotools.filter.FidFilter)

visit

public void visit(AttributeExpression expression)
           throws java.lang.RuntimeException

Writes the SQL for the attribute Expression.

Specified by:

visit in interface FilterVisitor

Parameters:

expression - the attribute to turn to SQL.

Throws:

java.lang.RuntimeException - for io exception with writer

visit

public void visit(Expression expression)

Writes the SQL for the attribute Expression.

Specified by:

visit in interface FilterVisitor

Parameters:

expression - the attribute to turn to SQL.

visit

public void visit(LiteralExpression expression)
           throws java.lang.RuntimeException

Export the contents of a Literal Expresion

Specified by:

visit in interface FilterVisitor

Parameters:

expression - the Literal to export

Throws:

java.lang.RuntimeException - for io exception with writer

visitLiteralGeometry

protected void visitLiteralGeometry(LiteralExpression expression)
                             throws java.io.IOException

Subclasses must implement this method in order to encode geometry filters according to the specific database implementation

Parameters:

expression -

Throws:

java.io.IOException - DOCUMENT ME!

java.lang.RuntimeException - DOCUMENT ME!

visit

public void visit(GeometryFilter filter)

Description copied from interface: FilterVisitor

Called when accept is called on a Geometry Filter. Implementers will want to access the left and right geometries.

Specified by:

visit in interface FilterVisitor

Parameters:

filter - The filter to visit

See Also:

FilterVisitor.visit(org.geotools.filter.GeometryFilter)

visit

public void visit(MathExpression expression)
           throws java.lang.RuntimeException

Writes the SQL for the Math Expression.

Specified by:

visit in interface FilterVisitor

Parameters:

expression - the Math phrase to be written.

Throws:

java.lang.RuntimeException - for io problems

visit

public void visit(FunctionExpression expression)
           throws java.lang.UnsupportedOperationException

Writes sql for a function expression. Not currently supported.

Specified by:

visit in interface FilterVisitor

Parameters:

expression - a function expression

Throws:

java.lang.UnsupportedOperationException - every time, this isn't supported.

setSqlNameEscape

public void setSqlNameEscape(java.lang.String escape)

Sets the SQL name escape string.

The value of this string is prefixed and appended to table schema names, table names and column names in an SQL statement to support mixed-case and non-English names. Without this, the DBMS may assume a mixed-case name in the query should be treated as upper-case and an SQLCODE of -204 or 206 may result if the name is not found.

Typically this is the double-quote character, ", but may not be for all databases.

For example, consider the following query:

SELECT Geom FROM Spear.ArchSites May be interpreted by the database as: SELECT GEOM FROM SPEAR.ARCHSITES If the column and table names were actually created using mixed-case, the query needs to be specified as: SELECT "Geom" from "Spear"."ArchSites"

Parameters:

escape - the character to be used to escape database names

setColnameEscape

public void setColnameEscape(java.lang.String escape)

Deprecated. Use setSqlNameEscape instead, as it is more aptly named.

Sets the escape character for the column name.

Parameters:

escape - The character to be used to escape database names.

getColnameEscape

protected java.lang.String getColnameEscape()

Deprecated. the escapeName method is preferred over this, it automatically returns the name properly escaped, since that's all getColnameEscape was being used for.

Gets the column escape name.

Returns:

the string to be used to properly escape a db's name.

escapeName

public java.lang.String escapeName(java.lang.String name)

Surrounds a name with the SQL escape character.

Parameters:

name -

Returns:

DOCUMENT ME!