1 /***
2 * Redistribution and use of this software and associated documentation
3 * ("Software"), with or without modification, are permitted provided
4 * that the following conditions are met:
5 *
6 * 1. Redistributions of source code must retain copyright
7 * statements and notices. Redistributions must also contain a
8 * copy of this document.
9 *
10 * 2. Redistributions in binary form must reproduce the
11 * above copyright notice, this list of conditions and the
12 * following disclaimer in the documentation and/or other
13 * materials provided with the distribution.
14 *
15 * 3. The name "Exolab" must not be used to endorse or promote
16 * products derived from this Software without prior written
17 * permission of Exoffice Technologies. For written permission,
18 * please contact info@exolab.org.
19 *
20 * 4. Products derived from this Software may not be called "Exolab"
21 * nor may "Exolab" appear in their names without prior written
22 * permission of Exoffice Technologies. Exolab is a registered
23 * trademark of Exoffice Technologies.
24 *
25 * 5. Due credit should be given to the Exolab Project
26 * (http://www.exolab.org/).
27 *
28 * THIS SOFTWARE IS PROVIDED BY EXOFFICE TECHNOLOGIES AND CONTRIBUTORS
29 * ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT
30 * NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
31 * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
32 * EXOFFICE TECHNOLOGIES OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
33 * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
34 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
35 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
36 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
37 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
38 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
39 * OF THE POSSIBILITY OF SUCH DAMAGE.
40 *
41 * Copyright 2000-2001,2003 (C) Exoffice Technologies Inc. All Rights Reserved.
42 */
43
44 package org.exolab.jms.selector;
45
46 import java.util.HashSet;
47
48
49 /***
50 * This interface specifies the methods needed to create all of the
51 * expressions supported by the message selector. It exists solely to
52 * decouple the expression evaluation classes from the parser.
53 *
54 * @version $Revision: 1.1 $ $Date: 2004/11/26 01:50:44 $
55 * @author <a href="mailto:tma@netspace.net.au">Tim Anderson</a>
56 * @see Expression
57 * @see org.exolab.jms.selector.parser.SelectorTokenTypes
58 * @see org.exolab.jms.selector.parser.SelectorTreeParser
59 */
60 public interface ExpressionFactory {
61
62 /***
63 * Create a binary operator expression
64 *
65 * @param operator the operator token type from SelectorTokenTypes
66 * @param left the left-hand side of the binary expression
67 * @param right the right-hand side of the binary expression
68 * @return a new binary expression
69 * @throws SelectorException if the operator is not a valid binary operator
70 */
71 Expression binaryOperator(int operator, Expression left, Expression right)
72 throws SelectorException;
73
74 /***
75 * Create an unary operator expression
76 *
77 * @param operator the operator token type from SelectorTokenTypes
78 * @param operand the expression to apply the operator to
79 * @return a new unary expression
80 * @throws SelectorException if the operator is not a valid unary operator
81 */
82 Expression unaryOperator(int operator, Expression operand)
83 throws SelectorException;
84
85 /***
86 * Create an identifier expression
87 *
88 * @param name the name of the identifier
89 * @return a new identifier expression
90 * @throws SelectorException is name is not a valid identifier
91 */
92 Expression identifier(String name) throws SelectorException;
93
94 /***
95 * Create an 'is null' expression
96 *
97 * @param identifier the identifer expression to apply the 'is null' test
98 * @return an 'is null' expression
99 * @throws SelectorException for any error
100 */
101 Expression isNull(Expression identifier) throws SelectorException;
102
103 /***
104 * Create a 'like' expression
105 *
106 * @param identifier the identifer to apply the 'like' test to
107 * @param pattern the search pattern
108 * @param escape the escape character. This may be null
109 * @return a new 'like' expression
110 * @throws SelectorException if the pattern or escape is invalid
111 */
112 Expression like(Expression identifier, String pattern, String escape)
113 throws SelectorException;
114
115 /***
116 * Create a 'between' expression that returns the result of:<br/>
117 * <code>num1 >= num2 and num1 <= num3</code>
118 * when evaluated
119 *
120 * @param num1 an arithmethic expression
121 * @param num2 an arithmethic expression
122 * @param num3 an arithmethic expression
123 * @return a new 'between' expression
124 * @throws SelectorException for any error
125 */
126 Expression between(Expression num1, Expression num2, Expression num3)
127 throws SelectorException;
128
129 /***
130 * Create an 'in' expression
131 *
132 * @param identifier string identifer to apply the 'in' test to
133 * @param set the set of string values to compare against
134 * @return a new 'in' expression
135 * @throws SelectorException for any error
136 */
137 Expression in(Expression identifier, HashSet set) throws SelectorException;
138
139 /***
140 * Create a literal expression
141 *
142 * @param type the operator token type from SelectorTokenTypes
143 * @param text the literal text
144 * @return a new literal expression
145 * @throws SelectorException if type is not a valid literal type
146 */
147 Expression literal(int type, String text) throws SelectorException;
148
149 }