Motivation:

Make use of FilterCapabilitiesImpl

Contact:

Jody Garnett

Tracker:

http://jira.codehaus.org/browse/GEOT-1637

Tagline:

what filters are available?

This page represents the current plan; for discussion please check the tracker link above.

Motivation

Some parts of migrating to opengis Filter are done; this is one aspect of the move that has not yet been addressed.

For reference:

FilterCapabilities

GeoAPI Javadocs

filterCapabilitiesExample.xml

Example filter capabilities XML file

Description

The proposal is to have a Capabilities wrapper / builder around a opengis FilterCapabilities data structure. This proposal only covers creating the utility class; hooking this up to FilterToSQL is another matter.

The idea is to easily switch back and forth between operator names and Filter interface classes (since the mapping is too scary for anyone to remember). As long as we need this class we can make the methods line up with the old FilterCapabilities class (to help people migrate).

Capabilities capabilities = new Capabilities( filterCapabilities );
capabilities.addType( Beyond.class ); // add to SpatialCapabilities
capabilities.addType( PropertyIsEqualTo.class ); // add to ScalarCapabilities
capabilities.addName( "NullCheck" ); // will enable PropertyIsNull use
capabilities.addName( "MUL" ); // will enable hasSimpleArithmatic
capabilities.addName( "random" ); // a function returning a random number
capabilities.addName( "Length", 1 ); // single argument function
capabilities.addName( "toDegrees", "radians" ); // single argument function
capabilities.addName( "length", "expression" );

if( capabilities.fullySupports( filter ) ){
    // encode as SQL
}

Capabilities capabilities2 = new Capabilities();

capabilities2.addAll( capabilities );
capabilities2.addAll( Capabilities.LOGICAL ); // Capabilities.LOGICAL is a FilterCapabilities

OUT OF SCOPE

Above we are defining some methods and classes constants to match the old FilterCapabilities class, we could go even further make everything method and field compatible but that would waste our time:

capabilities2.addType( Capabilities.LIKE );    // Capabiities.LIKE is now PropertyIsLike.class

Status

This proposal has been accepted as the voting period has now ended.

Tasks

 

no progress

(tick)

done

(error)

impeded

(warning)

lack mandate/funds/time

(question)

volunteer needed

  1. (tick) Write a Capabilities wrapper around FilterCapabilties data structure to perform tests in a method compatible way with the old FilterCapabilities class
  2. (tick) Make FilterCapabilitiesImpl data structure mutable so Capabilities wrapper can build it up as needed
  3. (tick) Add static NAME fields to the GeoAPI interfaces we are trying to map between; even if just to minimize cut and paste mistakes
  4. (tick) Change FilterCapabilities data structure to use Collection (so we can use a Set behind the scenes)
  5. (tick) Change Operator interfaces to implement equals and hashCode based on getName()
  6. Add FunctionFinder.getFilterCapabilities()
  7. (tick) Add Function.getArgumentNames() to GeoAPI
  8. Migrate FilterToSQLSDE to use new data structure; as an example
  9. Create Capabilities and FitlerCapabiities user documentation
  10. Suffer a performance review from Andrea - and probably introduce HashMaps rather than HashSets to make lookup faster

API Changes

Create a Capabilities wrapper around FilterCapabilities capturing the mapping from Filter interfaces to Operation.getName().
Where possible make this method comptible with the old FilterCapabilities class.

import org.opengis.filter.capabilities.FilterCapabilties;
public class Capabilities {
    public Capabilities( FilterCapabilities contents );
    FilterCapabilitiesImpl getContents();

    addType(Class);
    supports(Filter);
    fullySupports(Filter);
    fullySupports(Expression);
    addAll( Capabilities );
    addAll( FilterCapabilities );

    .. add additional methods as needed..

    addName(String);
    addName(String, int);
    addName(String, String...);
    toOperationName(Filter);
    toOperationName(Class);
}

Add NAME constants to non abstract GeoAPI Filer interfaces

BEFORE:

@XmlElement("PropertyIsNull")
public interface PropertyIsNull extends Filter {
    Expression getExpression();
}

AFTER:

@XmlElement("PropertyIsNull") // XML Element from filter.xsd
public interface PropertyIsNull extends Filter {
    /** Operator name used to check FilterCapabilities */
    public static String NAME = "NullCheck"; // XML Element from capabilities.xsd
    Expression getExpression();
}

Adrian Custer asked about the difference here:

Ask Operator to be a data object

The interface Operator is part of the filterCapabilities.xsd based data structures.

BEFORE:

public interface Operator {	
    String getName();
}

AFTER:

public interface Operator {	
    String getName();
    public boolean equals(Object obj);
    public int hashCode();
}

Make FilterCapabilitiesImpl mutable

Change the FilterCapabilitiesImpl classes to be mutable, with both a copy constructor and an addAll method for use when combining several FilterCapabilities data structures into one.

BEFORE:

public class FilterCapabilitiesImpl implements FilterCapabilities {
    public FilterCapabilitiesImpl();
    FilterCapabilitiesImpl( String, ScalarCapabilities, SpatialCapabilities, IdCapabilities);
   
    getVersion();
    IdCapabilitiesImpl getIdCapabilities();
    ScalarCapabilitiesImpl getScalarCapabilities();
    SpatialCapabilitiesImpl getSpatialCapabilities()
}

AFTER:

public class FilterCapabilitiesImpl implements FilterCapabilities {
    public FilterCapabilitiesImpl();
    FilterCapabilitiesImpl( String, ScalarCapabilities, SpatialCapabilities, IdCapabilities);
    FilterCapabilitiesImpl( FilterCapabilities );
   
    setVersion(String);
    getVersion();

    setId(IdCapabilities );
    IdCapabilitiesImpl getIdCapabilities();

    setScalar(ScalarCapabilities);
    ScalarCapabilitiesImpl getScalarCapabilities();

    setSpatial(SpatialCapabilities)
    SpatialCapabilitiesImpl getSpatialCapabilities()

    addAll(FilterCapabilities);
}

Add Optional getArgumentNames() to FunctionName:

This is an UNRELATED CHANGE THAT WAS FUN (and will let me write a query builder).
BEFORE:

public interface FunctionName extends Operator {
    int getArgumentCount();
}

AFTER:

public interface FunctionName extends Operator {
    int getArgumentCount();
    List<String> getArgumentNames(); // may be null if unknown
}

Access Functions data structure from FuntionFinder

The interface Functions is part of the filterCapabilities.xsd based data structures.

BEFORE:

class FunctionFinder {
   FunctionFinder(Hints)
   Function findFunction(String);
   Function findFunction(String, List);

AFTER:

class FunctionFinder {
   FunctionFinder(Hints)
   Function findFunction(String);
   Function findFunction(String, List);
   Functions getFunctions();

Documentation Changes