Expression


1   /*******************************************************************************
2    * Copyright (c) 2000, 2006 IBM Corporation and others.
3    * All rights reserved. This program and the accompanying materials
4    * are made available under the terms of the Eclipse Public License v1.0
5    * which accompanies this distribution, and is available at
6    * http://www.eclipse.org/legal/epl-v10.html
7    *
8    * Contributors:
9    *     IBM Corporation - initial API and implementation
10   *******************************************************************************/
11  package org.eclipse.core.expressions;
12  
13  import org.eclipse.core.runtime.CoreException;
14  
15  /**
16   * Abstract base class for all expressions provided by the common
17   * expression language.
18   * <p>
19   * An expression is evaluated by calling {@link #evaluate(IEvaluationContext)}.
20   * </p>
21   * <p>
22   * This class may be subclassed to provide specific expressions.
23   * </p>
24   * 
25   * @since 3.0
26   */
27  public abstract class Expression {
28  
29      /**
30       * Checks whether two objects are equal using the
31       * <code>equals(Object)</code> method of the <code>left</code> object.
32       * This method handles <code>null</code> for either the <code>left</code>
33       * or <code>right</code> object.
34       * 
35       * @param left the first object to compare; may be <code>null</code>.
36       * @param right the second object to compare; may be <code>null</code>.
37       * @return <code>true</code> if the two objects are equivalent;
38       *         <code>false</code> otherwise.
39       *         
40       * @since 3.2
41       */
42      protected static final boolean equals(final Object   left, final Object   right) {
43          return left == null ? right == null : ((right != null) && left
44                  .equals(right));
45      }
46  
47      /**
48       * Tests whether two arrays of objects are equal to each other. The arrays
49       * must not be <code>null</code>, but their elements may be
50       * <code>null</code>.
51       * 
52       * @param leftArray the left array to compare; may be <code>null</code>, and
53       *  may be empty and may contain <code>null</code> elements.
54       * @param rightArray the right array to compare; may be <code>null</code>, 
55       *  and may be empty and may contain <code>null</code> elements.
56       *  
57       * @return <code>true</code> if the arrays are equal length and the elements 
58       *  at the same position are equal; <code>false</code> otherwise.
59       *         
60       * @since 3.2
61       */
62      protected static final boolean equals(final Object  [] leftArray, final Object  [] rightArray) {
63          if (leftArray == rightArray) {
64              return true;
65          }
66  
67          if (leftArray == null) {
68              return (rightArray == null);
69          } else if (rightArray == null) {
70              return false;
71          }
72  
73          if (leftArray.length != rightArray.length) {
74              return false;
75          }
76  
77          for (int i= 0; i < leftArray.length; i++) {
78              final Object   left= leftArray[i];
79              final Object   right= rightArray[i];
80              final boolean equal= (left == null) ? (right == null) : (left.equals(right));
81              if (!equal) {
82                  return false;
83              }
84          }
85  
86          return true;
87      }
88  
89      /**
90       * Returns the hash code for the given <code>object</code>. This method
91       * handles <code>null</code>.
92       * 
93       * @param object the object for which the hash code is desired; may be
94       *  <code>null</code>.
95       *  
96       * @return The hash code of the object; zero if the object is
97       *  <code>null</code>.
98       *         
99       * @since 3.2
100      */
101     protected static final int hashCode(final Object   object) {
102         return object != null ? object.hashCode() : 0;
103     }
104 
105     /**
106      * Returns the hash code for the given array. This method handles
107      * <code>null</code>.
108      * 
109      * @param array the array for which the hash code is desired; may be
110      *  <code>null</code>.
111      * @return the hash code of the array; zero if the object is
112      *  <code>null</code>.
113      *         
114      * @since 3.2
115      */
116     protected static final int hashCode(final Object  [] array) {
117         if (array == null) {
118             return 0;
119         }
120         int hashCode= array.getClass().getName().hashCode();
121         for (int i= 0; i < array.length; i++) {
122             hashCode= hashCode * HASH_FACTOR + hashCode(array[i]);
123         }
124         return hashCode;
125     }
126     
127     /**
128      * The constant integer hash code value meaning the hash code has not yet
129      * been computed.
130      */
131     protected static final int HASH_CODE_NOT_COMPUTED = -1;
132 
133     /**
134      * A factor for computing the hash code for all expressions.
135      */
136     protected static final int HASH_FACTOR = 89;
137     
138     /**
139      * Name of the value attribute of an expression (value is <code>value</code>).
140      */ 
141     protected static final String   ATT_VALUE= "value"; //$NON-NLS-1$
142 
143     /**
144      * The expression corresponding to {@link EvaluationResult#TRUE}.
145      */
146     public static final Expression TRUE= new Expression() {
147         public EvaluationResult evaluate(IEvaluationContext context) {
148             return EvaluationResult.TRUE;
149         }   
150         public void collectExpressionInfo(ExpressionInfo info) {
151         }
152     };
153     
154     /**
155      * The expression corresponding to {@link EvaluationResult#FALSE}.
156      */
157     public static final Expression FALSE= new Expression() {
158         public EvaluationResult evaluate(IEvaluationContext context) {
159             return EvaluationResult.FALSE;
160         }
161         public void collectExpressionInfo(ExpressionInfo info) {
162         }
163     };
164 
165     /**
166      * The hash code for this object. This value is computed lazily.  If it is
167      * not yet computed, it is equal to {@link #HASH_CODE_NOT_COMPUTED}.
168      */
169     private transient int fHashCode= HASH_CODE_NOT_COMPUTED;
170     
171     /**
172      * Evaluates this expression. 
173      * 
174      * @param context an evaluation context providing information like variable,
175      *  name spaces, etc. necessary to evaluate this expression
176      * 
177      * @return the result of the expression evaluation
178      * 
179      * @throws CoreException if the evaluation failed. The concrete reason is 
180      *  defined by the subclass implementing this method
181      */
182     public abstract EvaluationResult evaluate(IEvaluationContext context) throws CoreException;
183     
184     /**
185      * Computes the expression information for the given expression tree.
186      * <p>
187      * This is a convenience method for collecting the expression information
188      * using {@link Expression#collectExpressionInfo(ExpressionInfo)}.
189      * </p>
190      * 
191      * @return the expression information
192      *  
193      * @since 3.2
194      */
195     public final ExpressionInfo computeExpressionInfo() {
196         ExpressionInfo result= new ExpressionInfo();
197         collectExpressionInfo(result);
198         return result;
199     }
200     
201     /**
202      * Collects information about this expression tree. This default
203      * implementation add the expression's type to the set of misbehaving
204      * expression types.
205      * 
206      * @param info the expression information object used
207      *  to collect the information
208      *  
209      * @since 3.2
210      */
211     public void collectExpressionInfo(ExpressionInfo info) {
212         info.addMisBehavingExpressionType(getClass());
213     }
214     
215     /**
216      * Method to compute the hash code for this object. The result
217      * returned from this method in cached in the <code>fHashCode</code>
218      * field. If the value returned from the method equals {@link #HASH_CODE_NOT_COMPUTED}
219      * (e.g. <code>-1</code>) then the value is incremented by one.
220      * <p>
221      * This default implementation calls <code>super.hashCode()</code>
222      * </p>
223      * @return a hash code for this object.
224      *         
225      * @since 3.2
226      */
227     protected int computeHashCode() {
228         return super.hashCode();
229     }
230     
231     /**
232      * {@inheritDoc}
233      */
234     public int hashCode() {
235         if (fHashCode != HASH_CODE_NOT_COMPUTED)
236             return fHashCode;
237         fHashCode= computeHashCode();
238         if (fHashCode == HASH_CODE_NOT_COMPUTED)
239             fHashCode++;
240         return fHashCode;
241     }
242 }
243
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Free Books Free Magazines
Popular Tags