Skip to end of metadata
Go to start of metadata

Tracker:

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

Tagline:

Modifying FunctionName to support detailed info about argument/return parameters.

Children:

Description

Currently the FunctionName interface only represents some limited information about a function in terms of its arguments:

  • number of arguments
  • argument names

This proposal is to extend the list to include:

  • argument types
  • min/max argument occurrences
  • return type

The latest version of the OGC filter specification (FES 2.0) requires that the above information be included in a filter capabilities document when describing supported functions.

The current patch implementing this proposal can be found here.

Status

Voting has not started yet:

Tasks

This section is used to make sure your proposal is complete (did you remember documentation?) and has enough paid or volunteer time lined up to be a success

 

no progress

(tick)

done

(error)

impeded

(warning)

lack mandate/funds/time

(question)

volunteer needed

  1. (tick) API changed based on BEFORE / AFTER
  2. (tick) Update default implementation
  3. (tick) Update the user guide
  4. (tick) Update the existing function implementations
  • GEOT-3569 Add detailed information about Function arguments and return type to FunctionName  

API Changes

FunctionName

BEFORE:

AFTER:

New interface:

Existing Parameter class to extend new interface:

Modify FunctionName:

FilterFactory2

AFTER:

New method:

Existing Functions

In order to take advantage of the new api function implementations will have to be migrated in order to declare the required information. However since there are numerous function implementations out there a gradual migration path has to be put in place.

Since all functions today already declare either an argument count, or a set of argument names all the required information can be derived from that alone. For instance of a function simply declares that it takes 2 arguments we derive the following:

  • arg1(type=Object.class,min=1,max=1)
  • arg2(type=Object.class,min=1,max=1)
  • return(type=Object.class)

If a function declares two arguments named "foo" and "bar" we derive the following:

  • foo(type=Object.class,min=1,max=1)
  • bar(type=Object.class,min=1,max=1)
  • return(type=Object.class)

Moving forward it is expected that new function implementations will declare arguments explicitly. And that existing function implementations will do so as the need arises. The following is an example of how to do so. Consider a function named "strIn" that determines if a "String" is "in" a list of specified strings. The function arguments are the string being tested for existance, a boolean determining whether case should be taken into account, and finally a variable list of candidate string values.

The functionName method is static and avaialble to all subclasses of FunctionImpl and FunctionExpressionImpl.

Variable Arguments

Since arguments declare min/max occurrences it is possible to have variable arguments (ie. arguments that take an arbitrary number of values) and optional arguments.

Obviously this presents challenges when attempting to dispatch a function call using the current mechanism in which filter functions are invoked. So to maintain backward compatibility and prevent requiring a different mechanism for invoking filter functions we adopt the same convention as the Java language in that only the last argument to a function may be variable or optional. This convention is enforced with the help of a convenience method on the function base class FunctionImpl.

Sanity check - Existing Variable Length Functions

Note existing variable length functions from app-schema and Symbology Encoding (concatenate, interpolate) has been defined without regards to the above convention.

Interpolate represents a worst case senario where repeating pairs are required as shown below:

Icon

If you are interested the above interpolate function can be used as in this CQL example (to repalce a lot of code you often use Rules for):

Note the "table" parameter must have a minimum of 4 values to form an interpolation range. The above example has 4 pairs forming three smooth gradients. Choosing a different MODE would result in a smoother shift between the gradients.

In addition note the use of Parameter.OPTIONS to indicate arguments that are restricted to a small set of allowable values.

  • No labels