org.geotools.filter.function
Class EnvFunction

Object
  extended by ExpressionAbstract
      extended by DefaultExpression
          extended by FunctionExpressionImpl
              extended by EnvFunction
All Implemented Interfaces:
Factory, ExpressionType, FunctionExpression, Expression, Function

public class EnvFunction
extends FunctionExpressionImpl

Provides a lookup table of named variables allowing externally defined values to be access within a SLD document.

Example: in the application, prior to rendering...


 EnvFunction.setValue("foo", 42);
 
Then, in the SLD document we can refer to this variable using the "env" function

 ...
 <FeatureTypeStyle>
   <Rule>
     <Filter>
       <PropertyIsEqualTo>
         <PropertyName>FooValue</PropertyName>
         <Function name="env">
           <literal>foo</literal>
         </Function>
       </PropertyIsEqualTo>
     </Filter>
     ...
 
The function provides a lookup table that is local to the active thread so that a given variable can hold different values in different threads. There is also a global lookup table, accessible from all threads. When the function is given a variable to look up it first searches the thread's local table and then, if the variable was not found, the global table. All lookups are case-insensitive.

Setting a fallback value is not supported in accordance with SLD 1.1 specification. However, you can provide a default value when calling the function as in these examples:


   <!-- Here, if variable foo is not set the function returns null -->
   <Function name="env">
     <Literal>foo</Literal>
   </Function>

   <!-- Here, a second argument is provided. If foo is not set the -->
   <!-- function will return 0.                                    -->
   <Function name="env">
     <Literal>foo</Literal>
     <Literal>0</Literal>
   </Function>
 
The same approach can be used programmatically...

 // set argument to set a default return value of 0
 FilterFactory ff = ...
 ff.function("env", ff.literal("foo"), ff.literal(0));
 

Since:
2.6
Author:
Andrea Aime, Michael Bedward

Field Summary
static FunctionName NAME
           
 
Fields inherited from class FunctionExpressionImpl
fallback, functionName, name, params
 
Fields inherited from class DefaultExpression
expressionType, permissiveConstruction
 
Fields inherited from interface ExpressionType
ATTRIBUTE, ATTRIBUTE_DOUBLE, ATTRIBUTE_GEOMETRY, ATTRIBUTE_INTEGER, ATTRIBUTE_STRING, ATTRIBUTE_UNDECLARED, FUNCTION, LITERAL_DOUBLE, LITERAL_GEOMETRY, LITERAL_INTEGER, LITERAL_LONG, LITERAL_STRING, LITERAL_UNDECLARED, MATH_ADD, MATH_DIVIDE, MATH_MULTIPLY, MATH_SUBTRACT
 
Fields inherited from interface Expression
NIL
 
Constructor Summary
EnvFunction()
          Create a new instance of this function.
 
Method Summary
static void clearGlobalValues()
          Clear all values from the global (accessible from any thread) lookup table.
static void clearLocalValues()
          Clear all values from the local (to this thread) lookup table.
 Object evaluate(Object feature)
          This method checks if the object is an instance of Feature and if so, calls through to #evaluate(Feature).
 int getArgCount()
          Gets the number of arguments that are set.
 void setFallbackValue(Literal fallback)
           This method is overriden to ignore the fallback value and log a warning message.
static void setGlobalValue(String name, Object value)
          Add a named value to the global (accessible from any thread) lookup table.
static void setGlobalValues(Map<String,Object> values)
          Set the table of global lookup values that is accessible from any thread, replacing the previously set table.
static void setLocalValue(String name, Object value)
          Add a named value to the local (to this thread) lookup table.
static void setLocalValues(Map<String,Object> values)
          Set the local (to this thread) table of lookup values, deleting any previously set table.
 void setParameters(List params)
          Sets the function parameters.
 
Methods inherited from class FunctionExpressionImpl
accept, equals, functionName, getArgs, getExpression, getFallbackValue, getFunctionName, getImplementationHints, getName, getParameters, getType, setArgs, setName, toString
 
Methods inherited from class DefaultExpression
accept, evaluate, getValue, isAttributeExpression, isExpression, isFunctionExpression, isGeometryExpression, isLiteralExpression, isMathExpression, isMathExpression
 
Methods inherited from class ExpressionAbstract
eval, eval, evaluate
 
Methods inherited from class Object
clone, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface Expression
accept, evaluate, getValue
 
Methods inherited from interface Expression
evaluate
 

Field Detail

NAME

public static FunctionName NAME
Constructor Detail

EnvFunction

public EnvFunction()
Create a new instance of this function.

Method Detail

setLocalValues

public static void setLocalValues(Map<String,Object> values)
Set the local (to this thread) table of lookup values, deleting any previously set table. The input Map is copied.

Parameters:
values - the lookup table; if null the existing lookup table will be cleared.

clearLocalValues

public static void clearLocalValues()
Clear all values from the local (to this thread) lookup table.


setGlobalValues

public static void setGlobalValues(Map<String,Object> values)
Set the table of global lookup values that is accessible from any thread, replacing the previously set table. The input Map is copied.

Parameters:
values - the lookup table; if null the existing lookup table will be cleared.

clearGlobalValues

public static void clearGlobalValues()
Clear all values from the global (accessible from any thread) lookup table.


setLocalValue

public static void setLocalValue(String name,
                                 Object value)
Add a named value to the local (to this thread) lookup table. If the name is already present in the table it will be assigned the new value.

Parameters:
name - the name
value - the value

setGlobalValue

public static void setGlobalValue(String name,
                                  Object value)
Add a named value to the global (accessible from any thread) lookup table. If the name is already present in the table it will be assigned the new value.

Parameters:
name - the name
value - the value

getArgCount

public int getArgCount()
Gets the number of arguments that are set.

Specified by:
getArgCount in interface FunctionExpression
Overrides:
getArgCount in class FunctionExpressionImpl
Returns:
Always returns 1

evaluate

public Object evaluate(Object feature)
This method checks if the object is an instance of Feature and if so, calls through to #evaluate(Feature). This is done to maintain backwards compatability with previous version of Expression api which depended on Feature. If the object is not an instance of feature the super implementation is called. The variable name to search for is provided as the single argument to this function. The active thread's local lookup table is searched first. If the name is not found there the global table is searched.

Specified by:
evaluate in interface Expression
Overrides:
evaluate in class DefaultExpression
Returns:
the variable value or null if the variable was not found

setParameters

public void setParameters(List params)
Sets the function parameters. This method is overriden to allow for either a single parameter (variable name) or two parameters (variable name plus default value).

Specified by:
setParameters in interface FunctionExpression
Overrides:
setParameters in class FunctionExpressionImpl

setFallbackValue

public void setFallbackValue(Literal fallback)
This method is overriden to ignore the fallback value and log a warning message. If you want to set a default value it can be provided as a second argument when calling the function. See the class description for details.

Overrides:
setFallbackValue in class FunctionExpressionImpl


Copyright © 1996-2014 Geotools. All Rights Reserved.