001 /* 002 * Licensed to the Apache Software Foundation (ASF) under one or more 003 * contributor license agreements. See the NOTICE file distributed with 004 * this work for additional information regarding copyright ownership. 005 * The ASF licenses this file to You under the Apache License, Version 2.0 006 * (the "License"); you may not use this file except in compliance with 007 * the License. You may obtain a copy of the License at 008 * 009 * http://www.apache.org/licenses/LICENSE-2.0 010 * 011 * Unless required by applicable law or agreed to in writing, software 012 * distributed under the License is distributed on an "AS IS" BASIS, 013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 014 * See the License for the specific language governing permissions and 015 * limitations under the License. 016 */ 017 package org.apache.commons.jxpath.ri; 018 019 /** 020 * The Compiler APIs are completely agnostic to the actual types of objects 021 * produced and consumed by the APIs. Arguments and return values are 022 * declared as java.lang.Object. 023 * <p> 024 * Since objects returned by Compiler methods are passed as arguments to other 025 * Compiler methods, the descriptions of these methods use virtual types. There 026 * are four virtual object types: EXPRESSION, QNAME, STEP and NODE_TEST. 027 * <p> 028 * The following example illustrates this notion. This sequence compiles 029 * the xpath "foo[round(1 div 2)]/text()": 030 * <blockquote><pre> 031 * Object qname1 = compiler.qname(null, "foo") 032 * Object expr1 = compiler.number("1"); 033 * Object expr2 = compiler.number("2"); 034 * Object expr3 = compiler.div(expr1, expr2); 035 * Object expr4 = compiler. 036 * coreFunction(Compiler.FUNCTION_ROUND, new Object[]{expr3}); 037 * Object test1 = compiler.nodeNameTest(qname1); 038 * Object step1 = compiler. 039 * step(Compiler.AXIS_CHILD, test1, new Object[]{expr4}); 040 * Object test2 = compiler.nodeTypeTest(Compiler.NODE_TYPE_TEXT); 041 * Object step2 = compiler.nodeTypeTest(Compiler.AXIS_CHILD, test2, null); 042 * Object expr5 = compiler.locationPath(false, new Object[]{step1, step2}); 043 * </pre></blockquote> 044 * 045 * @author Dmitri Plotnikov 046 * @version $Revision: 652845 $ $Date: 2008-05-02 12:46:46 -0500 (Fri, 02 May 2008) $ 047 */ 048 public interface Compiler { 049 050 public static final int NODE_TYPE_NODE = 1; 051 public static final int NODE_TYPE_TEXT = 2; 052 public static final int NODE_TYPE_COMMENT = 3; 053 public static final int NODE_TYPE_PI = 4; 054 055 public static final int AXIS_SELF = 1; 056 public static final int AXIS_CHILD = 2; 057 public static final int AXIS_PARENT = 3; 058 public static final int AXIS_ANCESTOR = 4; 059 public static final int AXIS_ATTRIBUTE = 5; 060 public static final int AXIS_NAMESPACE = 6; 061 public static final int AXIS_PRECEDING = 7; 062 public static final int AXIS_FOLLOWING = 8; 063 public static final int AXIS_DESCENDANT = 9; 064 public static final int AXIS_ANCESTOR_OR_SELF = 10; 065 public static final int AXIS_FOLLOWING_SIBLING = 11; 066 public static final int AXIS_PRECEDING_SIBLING = 12; 067 public static final int AXIS_DESCENDANT_OR_SELF = 13; 068 069 public static final int FUNCTION_LAST = 1; 070 public static final int FUNCTION_POSITION = 2; 071 public static final int FUNCTION_COUNT = 3; 072 public static final int FUNCTION_ID = 4; 073 public static final int FUNCTION_LOCAL_NAME = 5; 074 public static final int FUNCTION_NAMESPACE_URI = 6; 075 public static final int FUNCTION_NAME = 7; 076 public static final int FUNCTION_STRING = 8; 077 public static final int FUNCTION_CONCAT = 9; 078 public static final int FUNCTION_STARTS_WITH = 10; 079 public static final int FUNCTION_CONTAINS = 11; 080 public static final int FUNCTION_SUBSTRING_BEFORE = 12; 081 public static final int FUNCTION_SUBSTRING_AFTER = 13; 082 public static final int FUNCTION_SUBSTRING = 14; 083 public static final int FUNCTION_STRING_LENGTH = 15; 084 public static final int FUNCTION_NORMALIZE_SPACE = 16; 085 public static final int FUNCTION_TRANSLATE = 17; 086 public static final int FUNCTION_BOOLEAN = 18; 087 public static final int FUNCTION_NOT = 19; 088 public static final int FUNCTION_TRUE = 20; 089 public static final int FUNCTION_FALSE = 21; 090 public static final int FUNCTION_LANG = 22; 091 public static final int FUNCTION_NUMBER = 23; 092 public static final int FUNCTION_SUM = 24; 093 public static final int FUNCTION_FLOOR = 25; 094 public static final int FUNCTION_CEILING = 26; 095 public static final int FUNCTION_ROUND = 27; 096 public static final int FUNCTION_NULL = 28; 097 public static final int FUNCTION_KEY = 29; 098 public static final int FUNCTION_FORMAT_NUMBER = 30; 099 100 /** 101 * Produces an EXPRESSION object that represents a numeric constant. 102 * @param value numeric String 103 * @return Object 104 */ 105 Object number(String value); 106 107 /** 108 * Produces an EXPRESSION object that represents a string constant. 109 * @param value String literal 110 * @return Object 111 */ 112 Object literal(String value); 113 114 /** 115 * Produces an QNAME that represents a name with an optional prefix. 116 * @param prefix String prefix 117 * @param name String name 118 * @return Object 119 */ 120 Object qname(String prefix, String name); 121 122 /** 123 * Produces an EXPRESSION object representing the sum of all argumens 124 * 125 * @param arguments are EXPRESSION objects 126 * @return Object 127 */ 128 Object sum(Object[] arguments); 129 130 /** 131 * Produces an EXPRESSION object representing <i>left</i> minus <i>right</i> 132 * 133 * @param left is an EXPRESSION object 134 * @param right is an EXPRESSION object 135 * @return Object 136 */ 137 Object minus(Object left, Object right); 138 139 /** 140 * Produces an EXPRESSION object representing <i>left</i> multiplied by 141 * <i>right</i> 142 * 143 * @param left is an EXPRESSION object 144 * @param right is an EXPRESSION object 145 * @return Object 146 */ 147 Object multiply(Object left, Object right); 148 149 /** 150 * Produces an EXPRESSION object representing <i>left</i> divided by 151 * <i>right</i> 152 * 153 * @param left is an EXPRESSION object 154 * @param right is an EXPRESSION object 155 * @return Object 156 */ 157 Object divide(Object left, Object right); 158 159 /** 160 * Produces an EXPRESSION object representing <i>left</i> modulo 161 * <i>right</i> 162 * 163 * @param left is an EXPRESSION object 164 * @param right is an EXPRESSION object 165 * @return Object 166 */ 167 Object mod(Object left, Object right); 168 169 /** 170 * Produces an EXPRESSION object representing the comparison: 171 * <i>left</i> less than <i>right</i> 172 * 173 * @param left is an EXPRESSION object 174 * @param right is an EXPRESSION object 175 * @return Object 176 */ 177 Object lessThan(Object left, Object right); 178 179 /** 180 * Produces an EXPRESSION object representing the comparison: 181 * <i>left</i> less than or equal to <i>right</i> 182 * 183 * @param left is an EXPRESSION object 184 * @param right is an EXPRESSION object 185 * @return Object 186 */ 187 Object lessThanOrEqual(Object left, Object right); 188 189 /** 190 * Produces an EXPRESSION object representing the comparison: 191 * <i>left</i> greater than <i>right</i> 192 * 193 * @param left is an EXPRESSION object 194 * @param right is an EXPRESSION object 195 * @return Object 196 */ 197 Object greaterThan(Object left, Object right); 198 199 /** 200 * Produces an EXPRESSION object representing the comparison: 201 * <i>left</i> greater than or equal to <i>right</i> 202 * 203 * @param left is an EXPRESSION object 204 * @param right is an EXPRESSION object 205 * @return Object 206 */ 207 Object greaterThanOrEqual(Object left, Object right); 208 209 /** 210 * Produces an EXPRESSION object representing the comparison: 211 * <i>left</i> equals to <i>right</i> 212 * 213 * @param left is an EXPRESSION object 214 * @param right is an EXPRESSION object 215 * @return Object 216 */ 217 Object equal(Object left, Object right); 218 219 /** 220 * Produces an EXPRESSION object representing the comparison: 221 * <i>left</i> is not equal to <i>right</i> 222 * 223 * @param left is an EXPRESSION object 224 * @param right is an EXPRESSION object 225 * @return Object 226 */ 227 Object notEqual(Object left, Object right); 228 229 /** 230 * Produces an EXPRESSION object representing unary negation of the argument 231 * 232 * @param argument is an EXPRESSION object 233 * @return Object 234 */ 235 Object minus(Object argument); 236 237 /** 238 * Produces an EXPRESSION object representing variable reference 239 * 240 * @param qname is a QNAME object 241 * @return Object 242 */ 243 Object variableReference(Object qname); 244 245 /** 246 * Produces an EXPRESSION object representing the computation of 247 * a core function with the supplied arguments. 248 * 249 * @param code is one of FUNCTION_... constants 250 * @param args are EXPRESSION objects 251 * @return Object 252 */ 253 Object function(int code, Object[] args); 254 255 /** 256 * Produces an EXPRESSION object representing the computation of 257 * a library function with the supplied arguments. 258 * 259 * @param name is a QNAME object (function name) 260 * @param args are EXPRESSION objects 261 * @return Object 262 */ 263 Object function(Object name, Object[] args); 264 265 /** 266 * Produces an EXPRESSION object representing logical conjunction of 267 * all arguments 268 * 269 * @param arguments are EXPRESSION objects 270 * @return Object 271 */ 272 Object and(Object[] arguments); 273 274 /** 275 * Produces an EXPRESSION object representing logical disjunction of 276 * all arguments 277 * 278 * @param arguments are EXPRESSION objects 279 * @return Object 280 */ 281 Object or(Object[] arguments); 282 283 /** 284 * Produces an EXPRESSION object representing union of all node sets 285 * 286 * @param arguments are EXPRESSION objects 287 * @return Object 288 */ 289 Object union(Object[] arguments); 290 291 /** 292 * Produces a NODE_TEST object that represents a node name test. 293 * 294 * @param qname is a QNAME object 295 * @return Object 296 */ 297 Object nodeNameTest(Object qname); 298 299 /** 300 * Produces a NODE_TEST object that represents a node type test. 301 * 302 * @param nodeType is a NODE_TEST object 303 * @return Object 304 */ 305 Object nodeTypeTest(int nodeType); 306 307 /** 308 * Produces a NODE_TEST object that represents a processing instruction 309 * test. 310 * 311 * @param instruction is a NODE_TEST object 312 * @return Object 313 */ 314 Object processingInstructionTest(String instruction); 315 316 /** 317 * Produces a STEP object that represents a node test. 318 * 319 * @param axis is one of the AXIS_... constants 320 * @param nodeTest is a NODE_TEST object 321 * @param predicates are EXPRESSION objects 322 * @return Object 323 */ 324 Object step(int axis, Object nodeTest, Object[] predicates); 325 326 /** 327 * Produces an EXPRESSION object representing a location path 328 * 329 * @param absolute indicates whether the path is absolute 330 * @param steps are STEP objects 331 * @return Object 332 */ 333 Object locationPath(boolean absolute, Object[] steps); 334 335 /** 336 * Produces an EXPRESSION object representing a filter expression 337 * 338 * @param expression is an EXPRESSION object 339 * @param predicates are EXPRESSION objects 340 * @param steps are STEP objects 341 * @return Object 342 */ 343 Object expressionPath( 344 Object expression, 345 Object[] predicates, 346 Object[] steps); 347 }