001 /*
002 * GeoAPI - Java interfaces for OGC/ISO standards
003 * http://www.geoapi.org
004 *
005 * Copyright (C) 2006-2013 Open Geospatial Consortium, Inc.
006 * All Rights Reserved. http://www.opengeospatial.org/ogc/legal
007 *
008 * Permission to use, copy, and modify this software and its documentation, with
009 * or without modification, for any purpose and without fee or royalty is hereby
010 * granted, provided that you include the following on ALL copies of the software
011 * and documentation or portions thereof, including modifications, that you make:
012 *
013 * 1. The full text of this NOTICE in a location viewable to users of the
014 * redistributed or derivative work.
015 * 2. Notice of any changes or modifications to the OGC files, including the
016 * date changes were made.
017 *
018 * THIS SOFTWARE AND DOCUMENTATION IS PROVIDED "AS IS," AND COPYRIGHT HOLDERS MAKE
019 * NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
020 * TO, WARRANTIES OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT
021 * THE USE OF THE SOFTWARE OR DOCUMENTATION WILL NOT INFRINGE ANY THIRD PARTY
022 * PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS.
023 *
024 * COPYRIGHT HOLDERS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL OR
025 * CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE SOFTWARE OR DOCUMENTATION.
026 *
027 * The name and trademarks of copyright holders may NOT be used in advertising or
028 * publicity pertaining to the software without specific, written prior permission.
029 * Title to copyright in this software and any associated documentation will at all
030 * times remain with copyright holders.
031 */
032 package org.opengis.filter.expression;
033
034 import org.opengis.annotation.XmlElement;
035 import org.opengis.feature.Feature;
036
037
038 /**
039 * Interface for all the OGC Filter elements that compute values.
040 * <p>
041 * The most common use is with potentially using {@linkplain Feature feature} and
042 * metadata. The ability to access "attributes" based on the provided content is
043 * defined based on XPath queries currently.
044 *
045 * @version <A HREF="http://www.opengis.org/docs/02-059.pdf">Implementation specification 1.0</A>
046 * @author Chris Dillard (SYS Technologies)
047 * @author Justin Deoliveira (The Open Planning Project)
048 * @since GeoAPI 2.0
049 */
050 @XmlElement("expression")
051 public interface Expression {
052 /**
053 * Constant expression that always evaulates to {@code null}.
054 * <p>
055 * This constant is a "NullObject" that can represent the absense of
056 * expression in a data structures. As example it can be used to represent
057 * the default stroke color in a LineSymbolizer Stroke structure.
058 */
059 Expression NIL = new NilExpression();
060
061 /**
062 * Evaluates the given expression based on the content of the given object.
063 */
064 Object evaluate(Object object);
065
066 /**
067 * Evaluates the given expressoin based on the content of the given object
068 * and the context type.
069 * <p>
070 * The {@code context} parameter is used to control the type of the
071 * result of the expression. A particular expression may not be able to evaluate
072 * to an instance of {@code context}. Therefore to be safe calling code
073 * should do a null check on the return value of this method, and call {@link #evaluate(Object)}
074 * if neccessary. Example:
075 * <pre>
076 * Object input = ...;
077 * String result = expression.evaluate( input, String.class );
078 * if ( result == null ) {
079 * result = expression.evalute( input ).toString();
080 * }
081 * ...
082 * </pre>
083 * </p>
084 * <p>
085 * Implementations that can not return a result as an instance of {@code context}
086 * should return {@code null}.
087 * </p>
088 * @param <T> The type of the returned object.
089 * @param object The object to evaluate the expression against.
090 * @param context The type of the resulting value of the expression.
091 *
092 * @return Evaluates the given expression based on the content of the given object an
093 * an instance of {@code context}.
094 */
095 <T> T evaluate( Object object, Class<T> context );
096
097 /**
098 * Accepts a visitor. Subclasses must implement with a method whose content is the following:
099 * <pre>return visitor.{@linkplain ExpressionVisitor#visit visit}(this, extraData);</pre>
100 */
101 Object accept(ExpressionVisitor visitor, Object extraData);
102 }