001: /*
002: * Copyright 2004-2007 Gary Bentley
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License"); you may
005: * not use this file except in compliance with the License.
006: * You may obtain a copy of the License at
007: * http://www.apache.org/licenses/LICENSE-2.0
008: *
009: * Unless required by applicable law or agreed to in writing, software
010: * distributed under the License is distributed on an "AS IS" BASIS,
011: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
012: * See the License for the specific language governing permissions and
013: * limitations under the License.
014: */
015: package org.josql.expressions;
016:
017: import org.josql.Query;
018: import org.josql.QueryExecutionException;
019: import org.josql.QueryParseException;
020:
021: /**
022: * The base class for all expressions.
023: */
024: public abstract class Expression {
025:
026: private boolean bracketed = false;
027:
028: /**
029: * This method allows ANY expression (including those that extend {@link ValueExpression})
030: * to be used in the WHERE and HAVING clauses but ensuring that a boolean value is
031: * available for every expression.
032: *
033: * @param o The current object to evaluate the expression on.
034: * @param q The Query object.
035: * @return <code>true</code> if the expression evaluates to <code>true</code> (well duh...).
036: * @throws QueryExecutionException If there is a problem with the execution of the
037: * expression.
038: */
039: public abstract boolean isTrue(Object o, Query q)
040: throws QueryExecutionException;
041:
042: /**
043: * Return whether the expression will evaluate to a fixed/constant result.
044: * This allows certain optimisations to be performed when an expression is
045: * evaluated. A "fixed result" is basically one in which multiple calls to
046: * either the: {@link #isTrue(Object,Query)} or {@link #getValue(Object,Query)}
047: * methods will return the same object (or that o1.equals (o2) == true)
048: * regardless of the object passed to the method.
049: *
050: * @param q The Query object.
051: * @return <code>true</code> if the expression evaluates to a fixed/constant result.
052: */
053: public abstract boolean hasFixedResult(Query q);
054:
055: public void setBracketed(boolean v) {
056:
057: this .bracketed = v;
058:
059: }
060:
061: public boolean isBracketed() {
062:
063: return this .bracketed;
064:
065: }
066:
067: /**
068: * Return the class of the object that "should" be returned from a call to the:
069: * {@link #getValue(Object,Query)} method. It may be that repeated executions
070: * of a query will return different classes from this method. In general
071: * sub-classes should take this variance into account.
072: *
073: * @param q The Query object.
074: * @return The expected type that will be returned from the {@link #getValue(Object,Query)}
075: * method.
076: * @throws QueryParseException If something goes wrong with determining the type.
077: */
078: public abstract Class getExpectedReturnType(Query q)
079: throws QueryParseException;
080:
081: /**
082: * Perform the necessary initialisation for this expression.
083: * The exact operations performed are defined by the sub-class.
084: *
085: * @param q The Query object.
086: * @throws QueryParseException If something goes wrong with the initialisation.
087: */
088: public abstract void init(Query q) throws QueryParseException;
089:
090: /**
091: * Get the value for this expression based upon the object passed in. In general
092: * sub-classes should perform some operation on the object to generate their result.
093: * The Query object is provided so that sub-classes can gain access to the
094: * bind variables (if required), save values and so on.
095: * Whilst it may seem better to have the Query object as a member of this class
096: * this would then prevent the expression from being used separately from the Query
097: * (a design goal of JoSQL, i.e. independent processing).
098: *
099: * @param o The current object that the expression should be evaluated on.
100: * @param q The Query object.
101: * @return The value of the expression.
102: * @throws QueryExecutionException If something goes wrong with gaining the value.
103: */
104: public abstract Object getValue(Object o, Query q)
105: throws QueryExecutionException;
106:
107: /**
108: * Return a string representation of the expression, making this abstract forces
109: * sub-classes to provide an implementation.
110: *
111: * @return A string representation of the expression.
112: */
113: public abstract String toString();
114:
115: }
|