Expression


1   /*
2     (c) Copyright 2003, 2004, 2005 Hewlett-Packard Development Company, LP, all rights reserved.
3     [See end of file]
4     $Id: Expression.java,v 1.26 2005/02/21 11:52:15 andy_seaborne Exp $
5   */
6   
7   package com.hp.hpl.jena.graph.query;
8   
9   import java.util.*;
10  
11  import com.hp.hpl.jena.util.CollectionFactory;
12  
13  /**
14      Expression - the interface for expressions that is expected by Query for 
15      constraints. An Expression can be evaluated (given a name->value mapping);
16      it can be prepared into a Valuator (given a name->index mapping); and it can
17      be analysed into its components.
18  <p>
19      An Expression can be a variable, an application, or a literal value. If an access
20      method (eg getName) is applied to an Expression for which it is not appropriate
21      (eg an application), <em>the result is unspecified</em>; an implementation is
22      free to throw an exception, deliver a null result, deliver a misleading value,
23      whatever is convenient.
24  <p>
25      The nested class <code>Util</code> provides some expression utility
26      methods, including a generic version of <code>prepare</code>. The nested 
27      abstract class <code>Base</code> and its sub-classes <code>Literal</code>, 
28      <code>Variable</code>, and <code>Application</code> provide a framework 
29      for developers to implement Expressions over.
30  
31      @author kers
32  */
33  public interface Expression 
34      { 
35      /**
36          Answer a Valuator which, when run with a set of index-to-value bindings, 
37          evaluates this expression in the light of the given variable-to-index bindings
38          [ie as though the variables were bound to the corresponding values]
39      */
40      public Valuator prepare( VariableIndexes vi );
41      
42      /**
43          Answer true iff this Expression represents a variable.
44      */
45      public boolean isVariable();
46      
47      /**
48          If this Expression is a variable, answer a [non-null] String which is its name.
49          Otherwise the behaviour is unspecified.
50      */
51      public String   getName();
52      
53      /**
54          Answer true iff this Expression represents a literal [Java object] value.
55      */
56      public boolean isConstant();
57      
58      /**
59          If this Expression is a literal, answer the value of that literal. Otherwise the
60          behaviour is unspecified.
61      */
62      public Object   getValue();
63      
64      /**
65          Answer true iff this Expression represents the application of some function
66          [or operator] to some arguments [or operands].
67      */
68      public boolean isApply();
69      
70      /**
71           If this Expression is an application, return the string identifying the function,
72           which should be a URI. Otherwise the behaviour is unspecified.
73       */
74      public String   getFun();
75      
76      /**
77          If this Expression is an application, answer the number of arguments that
78          it has. Otherwise the behaviour is unspecified.    
79      */
80      public int argCount();
81      
82      /**
83          If this Expression is an application, and 0 &lt;= i &lt; argCount(), answer the
84          <code>i</code>th argument. Otherwise the behaviour is unspecified. 
85      */
86      public Expression getArg( int i );
87  
88      /**
89          An Expression which always evaluates to <code>true</code>.
90      */
91      public static Expression TRUE = new BoolConstant( true );
92      
93      /**
94          An Expression which always evaluates to <code>false</code>.
95      */
96      public static Expression FALSE = new BoolConstant( false );
97      
98      /**
99          An abstract base class for Expressions; over-ride as appropriate. The
100         sub-classes may be more useful. 
101     */
102     public static abstract class Base implements Expression
103         {        
104         public boolean isVariable() { return false; }
105         public boolean isApply() { return false; }
106         public boolean isConstant() { return false; }
107         public String   getName() { return null; }
108         public Object   getValue() { return null; }
109         public int argCount() { return 0; }
110         public String   getFun() { return null; }
111         public Expression getArg( int i ) { return null; }
112         
113         public boolean equals( Object   other )
114             { return other instanceof Expression && Expression.Util.equals( this, (Expression) other ); }
115         }
116     
117     /**
118         An abstract base class for literal nodes; subclasses implement getValue().
119     */
120     public static abstract class Constant extends Base
121         {
122         public boolean isConstant() { return true; }
123         public abstract Object   getValue();
124         }
125     
126     /**
127         A concrete class for representing fixed constants; each instance
128         can hold a separate value and its valuator returns that value.
129     */
130     public static class Fixed extends Constant
131         {
132         protected Object   value;
133         
134         public Fixed( Object   value )
135             { this.value = value; }
136         
137         public Object   getValue()
138             { return value; }
139         
140         public Valuator prepare( VariableIndexes vi ) 
141             { return new FixedValuator( value ); }
142         
143         public String   toString()
144             { return value.toString(); }
145         }
146     
147     /**
148         An abstract base class for variable nodes; subclasses implement getName().
149     */
150     public static abstract class Variable extends Base
151         {
152         public boolean isVariable() { return true; }
153         public abstract String   getName();
154         }
155     
156     /**
157         An abstract base class for apply nodes; subclasses implement getFun(),
158         argCount(), and getArg().
159     */
160     public static abstract class Application extends Base
161         {
162         public boolean isApply() { return true; }
163         public abstract int argCount();
164         public abstract String   getFun();
165         public abstract Expression getArg( int i );
166         }
167     
168     /**
169         Utility methods for Expressions, captured in a class because they can't be
170         written directly in the interface.
171     */
172     public static class Util
173         {
174         /**
175             Answer a set containing exactly the names of variables within 
176             <code>e</code>.
177         */
178         public static Set variablesOf( Expression e )
179             { return addVariablesOf( CollectionFactory.createHashedSet(), e ); }
180         
181         /**
182             Add all the variables of <code>e</code> to <code>s</code>, and answer
183             <code>s</code>.
184         */
185         public static Set addVariablesOf( Set s, Expression e )
186             {
187             if (e.isVariable()) 
188                 s.add( e.getName() );
189             else if (e.isApply())
190                 for (int i = 0; i < e.argCount(); i += 1)
191                     addVariablesOf( s, e.getArg( i ) );
192             return s;
193             }
194 
195         public static boolean containsAllVariablesOf( Set variables, Expression e ) 
196             {
197             if (e.isConstant()) 
198                 return true;
199             if (e.isVariable()) 
200                 return variables.contains( e.getName() );
201             if (e.isApply())
202                 {
203                 for (int i = 0; i < e.argCount(); i += 1)
204                     if (containsAllVariablesOf( variables, e.getArg(i) ) == false) return false;
205                 return true;
206                 }
207             return false;
208             }      
209         
210         public static boolean equals( Expression L, Expression R )
211             {
212             return
213                 L.isConstant() ? R.isConstant() && L.getValue().equals( R.getValue() )
214                 : L.isVariable() ? R.isVariable() && R.getName().equals( R.getName() )
215                 : L.isApply() ? R.isApply() && sameApply( L, R )
216                 : false
217                 ;
218             }
219         
220         public static boolean sameApply( Expression L, Expression R )
221             {
222             return 
223                 L.argCount() == R.argCount() && L.getFun().equals( R.getFun() )
224                 && sameArgs( L, R )
225                 ;
226             }
227         
228         public static boolean sameArgs( Expression L, Expression R )
229             {
230             for (int i = 0; i < L.argCount(); i += 1)
231                 if (!equals( L.getArg( i ), R.getArg( i ) )) return false;
232             return true;
233             }
234         }
235      
236     /**
237         Valof provides an implementation of VariableValues which composes the
238         "compile-time" VariableIndexes map with the "run-time" IndexValues map
239         to produce a VariableValues map. A Valof has mutable state; the setDomain
240         operation changes the IndexValues mapping of the Valof.
241     
242         @author kers
243      */
244     static class Valof implements VariableValues
245         {
246         private VariableIndexes map;
247         private IndexValues dom;
248         
249         public Valof( VariableIndexes map ) { this.map = map; }
250         
251         public final Object   get( String   name )
252              { return dom.get( map.indexOf( name ) );  }
253                  
254         public final Valof setDomain( IndexValues d ) { dom = d; return this; }  
255         }
256                
257     /**
258         Base class used to implement <code>TRUE</code> and <code>FALSE</code>.
259      */
260     public static class BoolConstant extends Base implements Expression, Valuator
261         {
262         private boolean value;
263         public BoolConstant( boolean value ) { this.value = value; }
264         public boolean isConstant() { return true; }
265         // TODO when moving to Jave 1.4 can use Boolean.valueOf( value )
266         public Object   getValue() { return value ? Boolean.TRUE : Boolean.FALSE; }
267         public Valuator prepare( VariableIndexes vi ) { return this; }   
268         public boolean evalBool( VariableValues vv ) { return value; }
269         public boolean evalBool( IndexValues vv ) { return value; }
270         public Object   evalObject( IndexValues iv ) { return getValue(); }
271         }    
272     }
273 
274 /*
275     (c) Copyright 2003, 2004, 2005 Hewlett-Packard Development Company, LP
276     All rights reserved.
277 
278     Redistribution and use in source and binary forms, with or without
279     modification, are permitted provided that the following conditions
280     are met:
281 
282     1. Redistributions of source code must retain the above copyright
283        notice, this list of conditions and the following disclaimer.
284 
285     2. Redistributions in binary form must reproduce the above copyright
286        notice, this list of conditions and the following disclaimer in the
287        documentation and/or other materials provided with the distribution.
288 
289     3. The name of the author may not be used to endorse or promote products
290        derived from this software without specific prior written permission.
291 
292     THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
293     IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
294     OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
295     IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
296     INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
297     NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
298     DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
299     THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
300     (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
301     THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
302 */
303
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags