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 018package org.apache.commons.jxpath.ri; 019 020/** 021 * The Compiler APIs are completely agnostic to the actual types of objects produced and consumed by the APIs. Arguments and return values are declared as 022 * java.lang.Object. 023 * <p> 024 * Since objects returned by Compiler methods are passed as arguments to other Compiler methods, the descriptions of these methods use virtual types. There are 025 * four virtual object types: EXPRESSION, QNAME, STEP and NODE_TEST. 026 * <p> 027 * The following example illustrates this notion. This sequence compiles the XPath "foo[round(1 div 2)]/text()": <blockquote> 028 * 029 * <pre> 030 * Object qname1 = compiler.qname(null, "foo") 031 * Object expr1 = compiler.number("1"); 032 * Object expr2 = compiler.number("2"); 033 * Object expr3 = compiler.div(expr1, expr2); 034 * Object expr4 = compiler. 035 * coreFunction(Compiler.FUNCTION_ROUND, new Object[]{expr3}); 036 * Object test1 = compiler.nodeNameTest(qname1); 037 * Object step1 = compiler. 038 * step(Compiler.AXIS_CHILD, test1, new Object[]{expr4}); 039 * Object test2 = compiler.nodeTypeTest(Compiler.NODE_TYPE_TEXT); 040 * Object step2 = compiler.nodeTypeTest(Compiler.AXIS_CHILD, test2, null); 041 * Object expr5 = compiler.locationPath(false, new Object[]{step1, step2}); 042 * </pre> 043 * 044 * </blockquote> 045 */ 046public interface Compiler { 047 048 /** Constant {@value} */ 049 int NODE_TYPE_NODE = 1; 050 051 /** Constant {@value} */ 052 int NODE_TYPE_TEXT = 2; 053 054 /** Constant {@value} */ 055 int NODE_TYPE_COMMENT = 3; 056 057 /** Constant {@value} */ 058 int NODE_TYPE_PI = 4; 059 060 /** Constant {@value} */ 061 int AXIS_SELF = 1; 062 063 /** Constant {@value} */ 064 int AXIS_CHILD = 2; 065 066 /** Constant {@value} */ 067 int AXIS_PARENT = 3; 068 069 /** Constant {@value} */ 070 int AXIS_ANCESTOR = 4; 071 072 /** Constant {@value} */ 073 int AXIS_ATTRIBUTE = 5; 074 075 /** Constant {@value} */ 076 int AXIS_NAMESPACE = 6; 077 078 /** Constant {@value} */ 079 int AXIS_PRECEDING = 7; 080 081 /** Constant {@value} */ 082 int AXIS_FOLLOWING = 8; 083 084 /** Constant {@value} */ 085 int AXIS_DESCENDANT = 9; 086 087 /** Constant {@value} */ 088 int AXIS_ANCESTOR_OR_SELF = 10; 089 090 /** Constant {@value} */ 091 int AXIS_FOLLOWING_SIBLING = 11; 092 093 /** Constant {@value} */ 094 int AXIS_PRECEDING_SIBLING = 12; 095 096 /** Constant {@value} */ 097 int AXIS_DESCENDANT_OR_SELF = 13; 098 099 /** Constant {@value} */ 100 int FUNCTION_LAST = 1; 101 102 /** Constant {@value} */ 103 int FUNCTION_POSITION = 2; 104 105 /** Constant {@value} */ 106 int FUNCTION_COUNT = 3; 107 108 /** Constant {@value} */ 109 int FUNCTION_ID = 4; 110 111 /** Constant {@value} */ 112 int FUNCTION_LOCAL_NAME = 5; 113 114 /** Constant {@value} */ 115 int FUNCTION_NAMESPACE_URI = 6; 116 117 /** Constant {@value} */ 118 int FUNCTION_NAME = 7; 119 120 /** Constant {@value} */ 121 int FUNCTION_STRING = 8; 122 123 /** Constant {@value} */ 124 int FUNCTION_CONCAT = 9; 125 126 /** Constant {@value} */ 127 int FUNCTION_STARTS_WITH = 10; 128 129 /** Constant {@value} */ 130 int FUNCTION_CONTAINS = 11; 131 132 /** Constant {@value} */ 133 int FUNCTION_SUBSTRING_BEFORE = 12; 134 135 /** Constant {@value} */ 136 int FUNCTION_SUBSTRING_AFTER = 13; 137 138 /** Constant {@value} */ 139 int FUNCTION_SUBSTRING = 14; 140 141 /** Constant {@value} */ 142 int FUNCTION_STRING_LENGTH = 15; 143 144 /** Constant {@value} */ 145 int FUNCTION_NORMALIZE_SPACE = 16; 146 147 /** Constant {@value} */ 148 int FUNCTION_TRANSLATE = 17; 149 150 /** Constant {@value} */ 151 int FUNCTION_BOOLEAN = 18; 152 153 /** Constant {@value} */ 154 int FUNCTION_NOT = 19; 155 156 /** Constant {@value} */ 157 int FUNCTION_TRUE = 20; 158 159 /** Constant {@value} */ 160 int FUNCTION_FALSE = 21; 161 162 /** Constant {@value} */ 163 int FUNCTION_LANG = 22; 164 165 /** Constant {@value} */ 166 int FUNCTION_NUMBER = 23; 167 168 /** Constant {@value} */ 169 int FUNCTION_SUM = 24; 170 171 /** Constant {@value} */ 172 int FUNCTION_FLOOR = 25; 173 174 /** Constant {@value} */ 175 int FUNCTION_CEILING = 26; 176 177 /** Constant {@value} */ 178 int FUNCTION_ROUND = 27; 179 180 /** Constant {@value} */ 181 int FUNCTION_NULL = 28; 182 183 /** Constant {@value} */ 184 int FUNCTION_KEY = 29; 185 186 /** Constant {@value} */ 187 int FUNCTION_FORMAT_NUMBER = 30; 188 189 /** Constant {@value} */ 190 int FUNCTION_ENDS_WITH = 31; 191 192 /** 193 * Produces an EXPRESSION object representing logical conjunction of all arguments 194 * 195 * @param arguments are EXPRESSION objects 196 * @return Object 197 */ 198 Object and(Object[] arguments); 199 200 /** 201 * Produces an EXPRESSION object representing <em>left</em> divided by <em>right</em> 202 * 203 * @param left is an EXPRESSION object 204 * @param right is an EXPRESSION object 205 * @return Object 206 */ 207 Object divide(Object left, Object right); 208 209 /** 210 * Produces an EXPRESSION object representing the comparison: <em>left</em> equals to <em>right</em> 211 * 212 * @param left is an EXPRESSION object 213 * @param right is an EXPRESSION object 214 * @return Object 215 */ 216 Object equal(Object left, Object right); 217 218 /** 219 * Produces an EXPRESSION object representing a filter expression 220 * 221 * @param expression is an EXPRESSION object 222 * @param predicates are EXPRESSION objects 223 * @param steps are STEP objects 224 * @return Object 225 */ 226 Object expressionPath(Object expression, Object[] predicates, Object[] steps); 227 228 /** 229 * Produces an EXPRESSION object representing the computation of a core function with the supplied arguments. 230 * 231 * @param code is one of FUNCTION_... constants 232 * @param args are EXPRESSION objects 233 * @return Object 234 */ 235 Object function(int code, Object[] args); 236 237 /** 238 * Produces an EXPRESSION object representing the computation of a library function with the supplied arguments. 239 * 240 * @param name is a QNAME object (function name) 241 * @param args are EXPRESSION objects 242 * @return Object 243 */ 244 Object function(Object name, Object[] args); 245 246 /** 247 * Produces an EXPRESSION object representing the comparison: <em>left</em> greater than <em>right</em> 248 * 249 * @param left is an EXPRESSION object 250 * @param right is an EXPRESSION object 251 * @return Object 252 */ 253 Object greaterThan(Object left, Object right); 254 255 /** 256 * Produces an EXPRESSION object representing the comparison: <em>left</em> greater than or equal to <em>right</em> 257 * 258 * @param left is an EXPRESSION object 259 * @param right is an EXPRESSION object 260 * @return Object 261 */ 262 Object greaterThanOrEqual(Object left, Object right); 263 264 /** 265 * Produces an EXPRESSION object representing the comparison: <em>left</em> less than <em>right</em> 266 * 267 * @param left is an EXPRESSION object 268 * @param right is an EXPRESSION object 269 * @return Object 270 */ 271 Object lessThan(Object left, Object right); 272 273 /** 274 * Produces an EXPRESSION object representing the comparison: <em>left</em> less than or equal to <em>right</em> 275 * 276 * @param left is an EXPRESSION object 277 * @param right is an EXPRESSION object 278 * @return Object 279 */ 280 Object lessThanOrEqual(Object left, Object right); 281 282 /** 283 * Produces an EXPRESSION object that represents a string constant. 284 * 285 * @param value String literal 286 * @return Object 287 */ 288 Object literal(String value); 289 290 /** 291 * Produces an EXPRESSION object representing a location path 292 * 293 * @param absolute indicates whether the path is absolute 294 * @param steps are STEP objects 295 * @return Object 296 */ 297 Object locationPath(boolean absolute, Object[] steps); 298 299 /** 300 * Produces an EXPRESSION object representing unary negation of the argument 301 * 302 * @param argument is an EXPRESSION object 303 * @return Object 304 */ 305 Object minus(Object argument); 306 307 /** 308 * Produces an EXPRESSION object representing <em>left</em> minus <em>right</em> 309 * 310 * @param left is an EXPRESSION object 311 * @param right is an EXPRESSION object 312 * @return Object 313 */ 314 Object minus(Object left, Object right); 315 316 /** 317 * Produces an EXPRESSION object representing <em>left</em> modulo <em>right</em> 318 * 319 * @param left is an EXPRESSION object 320 * @param right is an EXPRESSION object 321 * @return Object 322 */ 323 Object mod(Object left, Object right); 324 325 /** 326 * Produces an EXPRESSION object representing <em>left</em> multiplied by <em>right</em> 327 * 328 * @param left is an EXPRESSION object 329 * @param right is an EXPRESSION object 330 * @return Object 331 */ 332 Object multiply(Object left, Object right); 333 334 /** 335 * Produces a NODE_TEST object that represents a node name test. 336 * 337 * @param qname is a QNAME object 338 * @return Object 339 */ 340 Object nodeNameTest(Object qname); 341 342 /** 343 * Produces a NODE_TEST object that represents a node type test. 344 * 345 * @param nodeType is a NODE_TEST object 346 * @return Object 347 */ 348 Object nodeTypeTest(int nodeType); 349 350 /** 351 * Produces an EXPRESSION object representing the comparison: <em>left</em> is not equal to <em>right</em> 352 * 353 * @param left is an EXPRESSION object 354 * @param right is an EXPRESSION object 355 * @return Object 356 */ 357 Object notEqual(Object left, Object right); 358 359 /** 360 * Produces an EXPRESSION object that represents a numeric constant. 361 * 362 * @param value numeric String 363 * @return Object 364 */ 365 Object number(String value); 366 367 /** 368 * Produces an EXPRESSION object representing logical disjunction of all arguments 369 * 370 * @param arguments are EXPRESSION objects 371 * @return Object 372 */ 373 Object or(Object[] arguments); 374 375 /** 376 * Produces a NODE_TEST object that represents a processing instruction test. 377 * 378 * @param instruction is a NODE_TEST object 379 * @return Object 380 */ 381 Object processingInstructionTest(String instruction); 382 383 /** 384 * Produces an QNAME that represents a name with an optional prefix. 385 * 386 * @param prefix String prefix 387 * @param name String name 388 * @return Object 389 */ 390 Object qname(String prefix, String name); 391 392 /** 393 * Produces a STEP object that represents a node test. 394 * 395 * @param axis is one of the AXIS_... constants 396 * @param nodeTest is a NODE_TEST object 397 * @param predicates are EXPRESSION objects 398 * @return Object 399 */ 400 Object step(int axis, Object nodeTest, Object[] predicates); 401 402 /** 403 * Produces an EXPRESSION object representing the sum of all argumens 404 * 405 * @param arguments are EXPRESSION objects 406 * @return Object 407 */ 408 Object sum(Object[] arguments); 409 410 /** 411 * Produces an EXPRESSION object representing union of all node sets 412 * 413 * @param arguments are EXPRESSION objects 414 * @return Object 415 */ 416 Object union(Object[] arguments); 417 418 /** 419 * Produces an EXPRESSION object representing variable reference 420 * 421 * @param qname is a QNAME object 422 * @return Object 423 */ 424 Object variableReference(Object qname); 425}