KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > josql > expressions > Expression


1 /*
2  * Copyright 2004-2005 Gary Bentley
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License"); you may
5  * not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  * http://www.apache.org/licenses/LICENSE-2.0
8  *
9  * Unless required by applicable law or agreed to in writing, software
10  * distributed under the License is distributed on an "AS IS" BASIS,
11  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12  * See the License for the specific language governing permissions and
13  * limitations under the License.
14  */
15 package org.josql.expressions;
16
17 import org.josql.Query;
18 import org.josql.QueryExecutionException;
19 import org.josql.QueryParseException;
20
21 /**
22  * The base class for all expressions.
23  * <p>
24  * Last Modified By: $Author: barrygently $<br />
25  * Last Modified On: $Date: 2004/12/20 16:22:43 $<br />
26  * Current Revision: $Revision: 1.2 $<br />
27  */
28 public abstract class Expression
29 {
30
31     private boolean bracketed = false;
32
33     /**
34      * This method allows ANY expression (including those that extend {@link ValueExpression})
35      * to be used in the WHERE and HAVING clauses but ensuring that a boolean value is
36      * available for every expression.
37      *
38      * @param o The current object to evaluate the expression on.
39      * @param q The Query object.
40      * @return <code>true</code> if the expression evaluates to <code>true</code> (well duh...).
41      * @throws QueryExecutionException If there is a problem with the execution of the
42      * expression.
43      */
44     public abstract boolean isTrue (Object JavaDoc o,
45                     Query q)
46                                 throws QueryExecutionException;
47
48     /**
49      * Return whether the expression will evaluate to a fixed/constant result.
50      * This allows certain optimisations to be performed when an expression is
51      * evaluated. A "fixed result" is basically one in which multiple calls to
52      * either the: {@link #isTrue(Object,Query)} or {@link #getValue(Object,Query)}
53      * methods will return the same object (or that o1.equals (o2) == true)
54      * regardless of the object passed to the method.
55      *
56      * @param q The Query object.
57      * @return <code>true</code> if the expression evaluates to a fixed/constant result.
58      */
59     public abstract boolean hasFixedResult (Query q);
60
61     public void setBracketed (boolean v)
62     {
63
64     this.bracketed = v;
65
66     }
67
68     public boolean isBracketed ()
69     {
70
71     return this.bracketed;
72
73     }
74
75     /**
76      * Return the class of the object that "should" be returned from a call to the:
77      * {@link #getValue(Object,Query)} method. It may be that repeated executions
78      * of a query will return different classes from this method. In general
79      * sub-classes should take this variance into account.
80      *
81      * @param q The Query object.
82      * @return The expected type that will be returned from the {@link #getValue(Object,Query)}
83      * method.
84      * @throws QueryParseException If something goes wrong with determining the type.
85      */
86     public abstract Class JavaDoc getExpectedReturnType (Query q)
87                                              throws QueryParseException;
88
89     /**
90      * Perform the necessary initialisation for this expression.
91      * The exact operations performed are defined by the sub-class.
92      *
93      * @param q The Query object.
94      * @throws QueryParseException If something goes wrong with the initialisation.
95      */
96     public abstract void init (Query q)
97                            throws QueryParseException;
98
99     /**
100      * Get the value for this expression based upon the object passed in. In general
101      * sub-classes should perform some operation on the object to generate their result.
102      * The Query object is provided so that sub-classes can gain access to the
103      * bind variables (if required), save values and so on.
104      * Whilst it may seem better to have the Query object as a member of this class
105      * this would then prevent the expression from being used separately from the Query
106      * (a design goal of JoSQL, i.e. independent processing).
107      *
108      * @param o The current object that the expression should be evaluated on.
109      * @param q The Query object.
110      * @return The value of the expression.
111      * @throws QueryExecutionException If something goes wrong with gaining the value.
112      */
113     public abstract Object JavaDoc getValue (Object JavaDoc o,
114                      Query q)
115                                  throws QueryExecutionException;
116
117     /**
118      * Return a string representation of the expression, making this abstract forces
119      * sub-classes to provide an implementation.
120      *
121      * @return A string representation of the expression.
122      */
123     public abstract String JavaDoc toString ();
124
125 }
126
Popular Tags