Java API By Example, From Geeks To Geeks.

1 /* 2  * The contents of this file are subject to the terms 3  * of the Common Development and Distribution License 4  * (the "License"). You may not use this file except 5  * in compliance with the License. 6  * 7  * You can obtain a copy of the license at 8  * glassfish/bootstrap/legal/CDDLv1.0.txt or 9  * https://glassfish.dev.java.net/public/CDDLv1.0.html. 10  * See the License for the specific language governing 11  * permissions and limitations under the License. 12  * 13  * When distributing Covered Code, include this CDDL 14  * HEADER in each file and include the License file at 15  * glassfish/bootstrap/legal/CDDLv1.0.txt. If applicable, 16  * add the following below this CDDL HEADER, with the 17  * fields enclosed by brackets "[]" replaced with your 18  * own identifying information: Portions Copyright [yyyy] 19  * [name of copyright owner] 20  */ 21 22 // Copyright (c) 1998, 2006, Oracle. All rights reserved. 23 package oracle.toplink.essentials.expressions; 24 25 import java.util.*; 26 import java.io.*; 27 import oracle.toplink.essentials.queryframework.*; 28 import oracle.toplink.essentials.exceptions.*; 29 import oracle.toplink.essentials.internal.helper.*; 30 import oracle.toplink.essentials.internal.expressions.*; 31 import oracle.toplink.essentials.internal.localization.*; 32 import oracle.toplink.essentials.internal.sessions.AbstractRecord; 33 import oracle.toplink.essentials.internal.sessions.AbstractSession; 34 import oracle.toplink.essentials.descriptors.ClassDescriptor; 35 36 /** 37  * <p> 38  * <b>Purpose</b>: Define an object-level representation of a database query where clause.</p> 39  * <p> 40  * <b>Description</b>: An expression is a tree-like structure that defines the selection 41  * criteria for a query against objects in the database. The expression has the advantage 42  * over SQL by being at the object-level, i.e. the object model attributes and relationships 43  * can be used to be query on instead of the database field names. 44  * Because it is an object, not a string the expression has the advantage that is can be 45  * easily manipulated through code to easily build complex selection criterias.</p> 46  * <p> 47  * <b>Responsibilities</b>: 48  * <ul> 49  * <li> Store the selection criteria in a tree-like structure. 50  * <li> Support public manipulation protocols for all comparison and function opperators. 51  * <li> Use opperator overloading to support all primitive types as well as objects. 52  * </ul></p> 53  */ 54 public abstract class Expression implements Serializable, Cloneable { 55 56     /** Required for serialization compatibility. */ 57     static final long serialVersionUID = -5979150600092006081L; 58 59     /** Temporary values for table aliasing */ 60     protected transient DatabaseTable lastTable; 61     protected transient DatabaseTable currentAlias; 62     protected boolean selectIfOrderedBy = true; 63 64     /** 65      * Base Expression Constructor. Not generally used by Developers 66      */ 67     public Expression() { 68         super(); 69     } 70 71     /** 72      * PUBLIC: 73      * Function, return an expression that adds to a date based on 74      * the specified datePart. This is eqivalent to the Sybase DATEADD funtion. 75      * <p>Example: 76      * <pre><blockquote> 77      * TopLink: employee.get("date").addDate("year", 2) 78      * Java: NA 79      * SQL: DATEADD(date, 2, year) 80      * </pre></blockquote> 81      */ 82     public Expression addDate(String datePart, int numberToAdd) { 83         return addDate(datePart, new Integer (numberToAdd)); 84     } 85 86     /** 87      * PUBLIC: 88      * Function, return an expression that adds to a date based on 89      * the specified datePart. This is eqivalent to the Sybase DATEADD funtion. 90      * <p>Example: 91      * <pre><blockquote> 92      * TopLink: employee.get("date").addDate("year", 2) 93      * Java: NA 94      * SQL: DATEADD(date, 2, year) 95      * </pre></blockquote> 96      */ 97     public Expression addDate(String datePart, Object numberToAdd) { 98         ExpressionOperator anOperator = getOperator(ExpressionOperator.AddDate); 99         FunctionExpression expression = new FunctionExpression(); 100         expression.setBaseExpression(this); 101         expression.addChild(this); 102         expression.addChild(Expression.fromLiteral(datePart, this)); 103         expression.addChild(Expression.from(numberToAdd, this)); 104         expression.setOperator(anOperator); 105         return expression; 106     } 107 108     /** 109      * PUBLIC: 110      * Function, to add months to a date. 111      */ 112     public Expression addMonths(int months) { 113         return addMonths(new Integer (months)); 114     } 115 116     /** 117      * PUBLIC: 118      * Function, to add months to a date. 119      */ 120     public Expression addMonths(Object months) { 121         ExpressionOperator anOperator = getOperator(ExpressionOperator.AddMonths); 122         return anOperator.expressionFor(this, months); 123     } 124 125     /** 126      * INTERNAL: 127      * Find the alias for a given table 128      */ 129     public DatabaseTable aliasForTable(DatabaseTable table) { 130         return null; 131     } 132 133     /** 134      * PUBLIC: Returns an expression equivalent to all of <code>attributeName</code> 135      * holding true for <code>criteria</code>. 136      * <p> 137      * For every expression with an anyOf, its negation has either an allOf or a 138      * noneOf. The following two examples will illustrate as the second is the 139      * negation of the first: 140      * <p> 141      * AnyOf Example: Employees with a non '613' area code phone number. 142      * <pre><blockquote> 143      * ReadAllQuery query = new ReadAllQuery(Employee.class); 144      * ExpressionBuilder employee = new ExpressionBuilder(); 145      * Expression exp = employee.anyOf("phoneNumbers").get("areaCode").notEqual("613"); 146      * </blockquote></pre> 147      * <p> 148      * AllOf Example: Employees with all '613' area code phone numbers. 149      * <pre><blockquote> 150      * ExpressionBuilder employee = new ExpressionBuilder(); 151      * ExpressionBuilder phones = new ExpressionBuilder(); 152      * Expression exp = employee.allOf("phoneNumbers", phones.get("areaCode").equal("613")); 153      * SQL: 154      * SELECT ... EMPLOYEE t0 WHERE NOT EXISTS (SELECT ... PHONE t1 WHERE 155      * (t0.EMP_ID = t1.EMP_ID) AND NOT (t1.AREACODE = '613')) 156      * </blockquote></pre> 157      * <p> 158      * allOf is the universal counterpart to the existential anyOf. To have the 159      * condition evaluated for each instance it must be put inside of a subquery, 160      * which can be expressed as not exists (any of attributeName some condition). 161      * (All x such that y = !Exist x such that !y). 162      * <p>Likewise the syntax employee.allOf("phoneNumbers").get("areaCode").equal("613") 163      * is not supported for the <code>equal</code> must go inside a subQuery. 164      * <p> 165      * This method saves you from writing the sub query yourself. The above is 166      * equivalent to the following expression: 167      * <pre><blockquote> 168      * ExpressionBuilder employee = new ExpressionBuilder(); 169      * ExpressionBuilder phone = new ExpressionBuilder(); 170      * ReportQuery subQuery = new ReportQuery(Phone.class, phone); 171      * subQuery.retreivePrimaryKeys(); 172      * subQuery.setSelectionCriteria(phone.equal(employee.anyOf("phoneNumbers").and( 173      * phone.get("areaCode").notEqual("613"))); 174      * Expression exp = employee.notExists(subQuery); 175      * </blockquote></pre> 176      * <p> 177      * Note if employee has no phone numbers allOf ~ noneOf. 178      * @param criteria must have its own builder, as it will become the 179      * seperate selection criteria of a subQuery. 180      * @return a notExists subQuery expression 181      */ 182     public Expression allOf(String attributeName, Expression criteria) { 183         ReportQuery subQuery = new ReportQuery(); 184         subQuery.setShouldRetrieveFirstPrimaryKey(true); 185         Expression builder = criteria.getBuilder(); 186         criteria = builder.equal(anyOf(attributeName)).and(criteria.not()); 187         subQuery.setSelectionCriteria(criteria); 188         return notExists(subQuery); 189     } 190 191     /** 192      * PUBLIC: 193      * Return an expression that is the boolean logical combination of both expressions. 194      * This is equivalent to the SQL "AND" operator and the Java "&&" operator. 195      * <p>Example: 196      * <pre><blockquote> 197      * TopLink: employee.get("firstName").equal("Bob").and(employee.get("lastName").equal("Smith")) 198      * Java: (employee.getFirstName().equals("Bob")) && (employee.getLastName().equals("Smith")) 199      * SQL: F_NAME = 'Bob' AND L_NAME = 'Smith' 200      * </blockquote></pre> 201      */ 202     public Expression and(Expression theExpression) { 203         // Allow ands with null. 204 if (theExpression == null) { 205             return this; 206         } 207 208         ExpressionBuilder base = getBuilder(); 209         Expression expressionToUse = theExpression; 210 211         // Ensure the same builder, unless a parralel query is used. 212 // For flashback added an extra condition: if left side is a 'NullExpression' 213 // then rebuild on it regardless. 214 if ((theExpression.getBuilder() != base) && ((base == this) || (theExpression.getBuilder().getQueryClass() == null))) { 215             expressionToUse = theExpression.rebuildOn(base); 216         } 217 218         if (base == this) {// Allow and to be sent to the builder. 219 return expressionToUse; 220         } 221 222         ExpressionOperator anOperator = getOperator(ExpressionOperator.And); 223         return anOperator.expressionFor(this, expressionToUse); 224     } 225 226     /** 227      * PUBLIC: 228      * Return an expression representing traversal of a 1:many or many:many relationship. 229      * This allows you to query whether any of the "many" side of the relationship satisfies the remaining criteria. 230      * <p>Example: 231      * <p> 232      * <table border=0 summary="This table compares an example TopLink anyOf Expression to Java and SQL"> 233      * <tr> 234      * <th id="c1">Format</th> 235      * <th id="c2">Equivalent</th> 236      * </tr> 237      * <tr> 238      * <td headers="c1">TopLink</td> 239      * <td headers="c2"> 240      * <code> 241      * ReadAllQuery query = new ReadAllQuery(Employee.class);</br> 242      * ExpressionBuilder builder = new ExpressionBuilder();</br> 243      * Expression exp = builder.get("id").equal("14858");</br> 244      * exp = exp.or(builder.anyOf("managedEmployees").get("firstName").equal("Bob"));</br> 245      * </code> 246      * </td> 247      * </tr> 248      * <tr> 249      * <td headers="c1">Java</td> 250      * <td headers="c2">No direct equivalent</td> 251      * </tr> 252      * <tr> 253      * <td headers="c1">SQL</td> 254      * <td headers="c2">SELECT DISTINCT ... WHERE (t2.MGR_ID (+) = t1.ID) AND (t2.F_NAME = 'Bob')</td> 255      * </tr> 256      * </table> 257      */ 258     public Expression anyOf(String attributeName) { 259         QueryKeyExpression queryKey = (QueryKeyExpression)get(attributeName); 260 261         queryKey.doQueryToManyRelationship(); 262         return queryKey; 263 264     } 265 266     /** 267      * ADVANCED: 268      * Return an expression representing traversal of a 1:many or many:many relationship. 269      * This allows you to query whether any of the "many" side of the relationship satisfies the remaining criteria. 270      * This version of the anyOf operation performs an outer join. 271      * Outer joins allow the join to performed even if the target of the relationship is empty. 272      * NOTE: outer joins are not supported on all database and have differing symantics. 273      * <p>Example: 274      * <p> 275      * <table border=0 summary="This table compares an example TopLink anyOfAllowingNone Expression to Java and SQL"> 276      * <tr> 277      * <th id="c1">Format</th> 278      * <th id="c2">Equivalent</th> 279      * </tr> 280      * <tr> 281      * <td headers="c1">TopLink</td> 282      * <td headers="c2"> 283      * <code> 284      * ReadAllQuery query = new ReadAllQuery(Employee.class);</br> 285      * ExpressionBuilder builder = new ExpressionBuilder();</br> 286      * Expression exp = builder.get("id").equal("14858");</br> 287      * exp = exp.or(builder.anyOfAllowingNone("managedEmployees").get("firstName").equal("Bob"));</br> 288      * </code> 289      * </td> 290      * </tr> 291      * <tr> 292      * <td headers="c1">Java</td> 293      * <td headers="c2">No direct equivalent</td> 294      * </tr> 295      * <tr> 296      * <td headers="c1">SQL</td> 297      * <td headers="c2">SELECT DISTINCT ... WHERE (t2.MGR_ID (+) = t1.ID) AND (t2.F_NAME = 'Bob')</td> 298      * </tr> 299      * </table> 300      */ 301     public Expression anyOfAllowingNone(String attributeName) { 302         QueryKeyExpression queryKey = (QueryKeyExpression)getAllowingNull(attributeName); 303 304         queryKey.doQueryToManyRelationship(); 305         return queryKey; 306 307     } 308 309     /** 310      * PUBLIC: 311      * This can only be used within an ordering expression. 312      * It will order the result ascending. 313      * Example: 314      * <pre><blockquote> 315      * readAllQuery.addOrderBy(expBuilder.get("address").get("city").ascending()) 316      * </blockquote></pre> 317      */ 318     public Expression ascending() { 319         return getFunction(ExpressionOperator.Ascending); 320     } 321 322     /** 323      * PUBLIC: 324      * Function, returns the single character strings ascii value. 325      */ 326     public Expression asciiValue() { 327         ExpressionOperator anOperator = getOperator(ExpressionOperator.Ascii); 328         return anOperator.expressionFor(this); 329     } 330 331     /** 332      * INTERNAL: 333      * Alias a particular table within this node 334      */ 335     protected void assignAlias(String name, DatabaseTable tableOrExpression) { 336         // By default, do nothing. 337 } 338 339     /** 340      * INTERNAL: 341      * Assign aliases to any tables which I own. Start with t<initialValue>, 342      * and return the new value of the counter , i.e. if initialValue is one 343      * and I have tables ADDRESS and EMPLOYEE I will assign them t1 and t2 respectively, and return 3. 344      */ 345     public int assignTableAliasesStartingAt(int initialValue) { 346         if (hasBeenAliased()) { 347             return initialValue; 348         } 349         int counter = initialValue; 350         Vector ownedTables = getOwnedTables(); 351         if (ownedTables != null) { 352             for (Enumeration e = ownedTables.elements(); e.hasMoreElements();) { 353                 assignAlias("t" + counter, (DatabaseTable)e.nextElement()); 354                 counter++; 355             } 356         } 357         return counter; 358     } 359 360     /** 361      * PUBLIC: 362      * Function, This represents the aggregate function Average. Can be used only within Report Queries. 363      */ 364     public Expression average() { 365         return getFunction(ExpressionOperator.Average); 366     } 367 368     /** 369      * PUBLIC: 370      * Function, between two bytes 371      */ 372     public Expression between(byte leftValue, byte rightValue) { 373         return between(new Byte (leftValue), new Byte (rightValue)); 374     } 375 376     /** 377      * PUBLIC: 378      * Function, between two chars 379      */ 380     public Expression between(char leftChar, char rightChar) { 381         return between(new Character (leftChar), new Character (rightChar)); 382     } 383 384     /** 385      * PUBLIC: 386      * Function, between two doubles 387      */ 388     public Expression between(double leftValue, double rightValue) { 389         return between(new Double (leftValue), new Double (rightValue)); 390     } 391 392     /** 393      * PUBLIC: 394      * Function, between two floats 395      */ 396     public Expression between(float leftValue, float rightValue) { 397         return between(new Float (leftValue), new Float (rightValue)); 398     } 399 400     /** 401      * PUBLIC: 402      * Function, between two ints 403      */ 404     public Expression between(int leftValue, int rightValue) { 405         return between(new Integer (leftValue), new Integer (rightValue)); 406     } 407 408     /** 409      * PUBLIC: 410      * Function, between two longs 411      */ 412     public Expression between(long leftValue, long rightValue) { 413         return between(new Long (leftValue), new Long (rightValue)); 414     } 415 416     /** 417      * PUBLIC: 418      * Return an expression that compares if the receiver's value is between two other values. 419      * This means the receiver's value is greater than or equal to the leftValue argument and less than or equal to the 420      * rightValue argument. 421      * <p> 422      * This is equivalent to the SQL "BETWEEN AND" operator and Java ">=", "<=;" operators. 423      * <p>Example: 424      * <pre> 425      * TopLink: employee.get("age").between(19,50) 426      * Java: (employee.getAge() >= 19) && (employee.getAge() <= 50) 427      * SQL: AGE BETWEEN 19 AND 50 428      * </pre> 429      */ 430     public Expression between(Object leftValue, Object rightValue) { 431         ExpressionOperator anOperator = getOperator(ExpressionOperator.Between); 432         Vector args = oracle.toplink.essentials.internal.helper.NonSynchronizedVector.newInstance(); 433         args.addElement(leftValue); 434         args.addElement(rightValue); 435         return anOperator.expressionForArguments(this, args); 436     } 437 438     public Expression between(Expression leftExpression, Expression rightExpression) { 439         return between((Object )leftExpression, (Object )rightExpression); 440 441     } 442 443     /** 444      * PUBLIC: 445      * Function, between two shorts 446      */ 447     public Expression between(short leftValue, short rightValue) { 448         return between(new Short (leftValue), new Short (rightValue)); 449     } 450 451     /** 452      * PUBLIC: 453      * Function Convert values returned by the query to values 454      * given in the caseItems hashtable. The equivalent of 455      * the Oracle CASE function 456      * <p>Example: 457      * <pre><blockquote> 458      * Hashtable caseTable = new Hashtable(); 459      * caseTable.put("Robert", "Bob"); 460      * caseTable.put("Susan", "Sue"); 461      * 462      * TopLink: employee.get("name").caseStatement(caseTable, "No-Nickname") 463      * Java: NA 464      * SQL: CASE name WHEN "Robert" THEN "Bob" 465      * WHEN "Susan" THEN "Sue" 466      * ELSE "No-Nickname" 467      * </pre></blockquote> 468      * @param caseItems java.util.Hashtable 469      * a hashtable containing the items to be processed. Keys represent 470      * the items to match coming from the query. Values represent what 471      * a key will be changed to. 472      * @param defaultItem java.lang.String the default value that will be used if none of the keys in the 473      * hashtable match 474      **/ 475     public Expression caseStatement(Hashtable caseItems, String defaultItem) { 476 477         /** 478          * case (like decode) works differently than most of the functionality in the expression 479          * framework. It takes a variable number of arguments and as a result, the printed strings 480          * for a case call have to be built when the number of arguments are known. 481          * As a result, we do not look up case in the ExpressionOperator. Instead we build 482          * the whole operator here. The side effect of this is that case will not throw 483          * an invalid operator exception for any platform. (Even the ones that do not support 484          * case) 485          */ 486         ExpressionOperator anOperator = new ExpressionOperator(); 487         anOperator.setSelector(ExpressionOperator.Case); 488         anOperator.setNodeClass(FunctionExpression.class); 489         anOperator.setType(ExpressionOperator.FunctionOperator); 490         anOperator.bePrefix(); 491 492         Vector v = oracle.toplink.essentials.internal.helper.NonSynchronizedVector.newInstance(caseItems.size() + 1); 493         v.addElement("CASE "); 494 495         FunctionExpression expression = new FunctionExpression(); 496         expression.setBaseExpression(this); 497         expression.addChild(this); 498         Enumeration enumeration = caseItems.keys(); 499         while (enumeration.hasMoreElements()) { 500             Object key = enumeration.nextElement(); 501             expression.addChild(Expression.from(key, this)); 502             expression.addChild(Expression.from(caseItems.get(key), this)); 503             v.addElement(" WHEN "); 504             v.addElement(" THEN "); 505         } 506         ; 507         v.addElement(" ELSE "); 508         expression.addChild(Expression.from(defaultItem, this)); 509         v.addElement(" END"); 510         anOperator.printsAs(v); 511         expression.setOperator(anOperator); 512         return expression; 513     } 514 515     /** 516      * INTERNAL: 517      * Clone the expression maintaining clone identity in the inter-connected expression graph. 518      */ 519     public Object clone() { 520         // 2612538 - the default size of IdentityHashtable (32) is appropriate 521 Dictionary alreadyDone = new IdentityHashtable(); 522         return copiedVersionFrom(alreadyDone); 523     } 524 525     /** 526      * INTERNAL: 527      * This expression is built on a different base than the one we want. Rebuild it and 528      * return the root of the new tree. 529      * This method will rebuildOn the receiver even it is a parallel select or a 530      * sub select: it will not replace every base with newBase. 531      * Also it will rebuild using anyOf as appropriate not get. 532      * @see oracle.toplink.essentials.mappings.ForeignReferenceMapping#batchedValueFromRow 533      * @see #rebuildOn(Expression) 534      * @bug 2637484 INVALID QUERY KEY EXCEPTION THROWN USING BATCH READS AND PARALLEL EXPRESSIONS 535      * @bug 2612567 CR4298- NULLPOINTEREXCEPTION WHEN USING SUBQUERY AND BATCH READING IN 4.6 536      * @bug 2612140 CR2973- BATCHATTRIBUTE QUERIES WILL FAIL WHEN THE INITIAL QUERY HAS A SUBQUERY 537      * @bug 2720149 INVALID SQL WHEN USING BATCH READS AND MULTIPLE ANYOFS 538      */ 539     public Expression cloneUsing(Expression newBase) { 540         // 2612538 - the default size of IdentityHashtable (32) is appropriate 541 Dictionary alreadyDone = new IdentityHashtable(); 542 543         // cloneUsing is identical to cloning save that the primary builder 544 // will be replaced not with its clone but with newBase. 545 // ExpressionBuilder.registerIn() will check for this newBase with 546 // alreadyDone.get(alreadyDone); 547 // copiedVersionFrom() must be called on the primary builder before 548 // other builders. 549 alreadyDone.put(alreadyDone, newBase); 550         return copiedVersionFrom(alreadyDone); 551     } 552 553     /** 554      * PUBLIC: 555      * Function, returns the concatenation of the two string values. 556      */ 557     public Expression concat(Object left) { 558         ExpressionOperator anOperator = getOperator(ExpressionOperator.Concat); 559         return anOperator.expressionFor(this, left); 560     } 561 562     /** 563      * PUBLIC: 564      * Return an expression that performs a key word search. 565      * <p>Example: 566      * <pre><blockquote> 567      * TopLink: project.get("description").containsAllKeyWords("TopLink rdbms java") 568      * </blockquote></pre> 569      */ 570     public Expression containsAllKeyWords(String spaceSeperatedKeyWords) { 571         StringTokenizer tokenizer = new StringTokenizer(spaceSeperatedKeyWords); 572         Expression expression = null; 573         while (tokenizer.hasMoreTokens()) { 574             String token = tokenizer.nextToken(); 575             if (expression == null) { 576                 expression = containsSubstringIgnoringCase(token); 577             } else { 578                 expression = expression.and(containsSubstringIgnoringCase(token)); 579             } 580         } 581 582         if (expression == null) { 583             return like("%"); 584         } else { 585             return expression; 586         } 587     } 588 589     /** 590      * PUBLIC: 591      * Return an expression that performs a key word search. 592      * <p>Example: 593      * <pre><blockquote> 594      * TopLink: project.get("description").containsAllKeyWords("TopLink rdbms java") 595      * </blockquote></pre> 596      */ 597     public Expression containsAnyKeyWords(String spaceSeperatedKeyWords) { 598         StringTokenizer tokenizer = new StringTokenizer(spaceSeperatedKeyWords); 599         Expression expression = null; 600         while (tokenizer.hasMoreTokens()) { 601             String token = tokenizer.nextToken(); 602             if (expression == null) { 603                 expression = containsSubstringIgnoringCase(token); 604             } else { 605                 expression = expression.or(containsSubstringIgnoringCase(token)); 606             } 607         } 608 609         if (expression == null) { 610             return like("%"); 611         } else { 612             return expression; 613         } 614     } 615 616     /** 617      * PUBLIC: 618      * Return an expression that compares if the receivers value contains the substring. 619      * <p>Example: 620      * <pre><blockquote> 621      * TopLink: employee.get("firstName").containsSubstring("Bob") 622      * Java: employee.getFirstName().indexOf("Bob") != -1 623      * SQL: F_NAME LIKE '%BOB%' 624      * </blockquote></pre> 625      */ 626     public Expression containsSubstring(String theValue) { 627         return like("%" + theValue + "%"); 628     } 629 630     /** 631      * PUBLIC: 632      * Return an expression that compares if the receivers value contains the substring. 633      * <p>Example: 634      * <pre><blockquote> 635      * TopLink: employee.get("firstName").containsSubstring("Bob") 636      * Java: employee.getFirstName().indexOf("Bob") != -1 637      * SQL: F_NAME LIKE '%BOB%' 638      * </blockquote></pre> 639      */ 640     public Expression containsSubstring(Expression expression) { 641         return like((value("%").concat(expression)).concat("%")); 642     } 643 644     /** 645      * PUBLIC: 646      * Return an expression that compares if the receivers value contains the substring, ignoring case. 647      * <p>Example: 648      * <pre><blockquote> 649      * TopLink: employee.get("firstName").containsSubstringIgnoringCase("Bob") 650      * Java: employee.getFirstName().toUpperCase().indexOf("BOB") != -1 651      * SQL: F_NAME LIKE '%BOB%' 652      * </blockquote></pre> 653      */ 654     public Expression containsSubstringIgnoringCase(String theValue) { 655         return toUpperCase().containsSubstring(theValue.toUpperCase()); 656     } 657 658     /** 659      * PUBLIC: 660      * Return an expression that compares if the receivers value contains the substring, ignoring case. 661      * <p>Example: 662      * <pre><blockquote> 663      * TopLink: employee.get("firstName").containsSubstringIgnoringCase("Bob") 664      * Java: employee.getFirstName().toUpperCase().indexOf("BOB") != -1 665      * SQL: F_NAME LIKE '%BOB%' 666      * </blockquote></pre> 667      */ 668     public Expression containsSubstringIgnoringCase(Expression expression) { 669         return toUpperCase().containsSubstring(expression.toUpperCase()); 670     } 671 672     /* 673      * Modify this individual expression node to use outer joins wherever there are 674      * equality operations between two field nodes. 675      */ 676     protected void convertNodeToUseOuterJoin() { 677     } 678 679     /** 680      * INTERNAL: 681      * Modify this expression to use outer joins wherever there are 682      * equality operations between two field nodes. 683      */ 684     public Expression convertToUseOuterJoin() { 685         ExpressionIterator iterator = new ExpressionIterator() { 686             public void iterate(Expression each) { 687                 each.convertNodeToUseOuterJoin(); 688             } 689         }; 690         iterator.iterateOn(this); 691         return this; 692     } 693 694     /** 695      * INTERNAL: 696      */ 697     public Expression copiedVersionFrom(Dictionary alreadyDone) { 698         Expression existing = (Expression)alreadyDone.get(this); 699         if (existing == null) { 700             return registerIn(alreadyDone); 701         } else { 702             return existing; 703         } 704     } 705 706     /** 707      * PUBLIC: 708      * This represents the aggregate function Average. Can be used only within Report Queries. 709      */ 710     public Expression count() { 711         return getFunction(ExpressionOperator.Count); 712     } 713 714     /** 715      * INTERNAL: 716      */ 717     public Expression create(Expression base, Object singleArgument, ExpressionOperator anOperator) { 718         // This is a replacement for real class methods in Java. Instead of returning a new instance we create it, then 719 // mutate it using this method. 720 return this; 721     } 722 723     /** 724      * INTERNAL: 725      */ 726     public Expression createWithBaseLast(Expression base, Object singleArgument, ExpressionOperator anOperator) { 727         // This is a replacement for real class methods in Java. Instead of returning a new instance we create it, then 728 // mutate it using this method. 729 return this; 730     } 731 732     /** 733      * INTERNAL: 734      */ 735     public Expression create(Expression base, Vector arguments, ExpressionOperator anOperator) { 736         // This is a replacement for real class methods in Java. Instead of returning a new instance we create it, then 737 // mutate it using this method. 738 return this; 739     } 740 741     /** 742      * PUBLIC: 743      * This gives access to the current date on the database through expression. 744      */ 745     public Expression currentDate() { 746         return getFunction(ExpressionOperator.Today); 747     } 748 749    /** 750     * PUBLIC: 751     * This gives access to the current date only on the database through expression. 752     * Note the difference between currentDate() and this method. This method does 753     * not return the time portion of current date where as currentDate() does. 754     */ 755    public Expression currentDateDate() { 756        return getFunction(ExpressionOperator.currentDate); 757    } 758 759     /** 760      * PUBLIC: 761      * Function, Return the difference between the queried part of a date(i.e. years, days etc.) 762      * and same part of the given date. The equivalent of the Sybase function DateDiff 763      * <p>Example: 764      * <pre><blockquote> 765      * TopLink: employee.get("date").dateDifference("year", new Date(System.currentTimeMillis())) 766      * Java: NA 767      * SQL: DATEADD(date, 2, GETDATE) 768      * </pre></blockquote> * 769      */ 770     public Expression dateDifference(String datePart, java.util.Date date) { 771         ExpressionOperator anOperator = getOperator(ExpressionOperator.DateDifference); 772         FunctionExpression expression = new FunctionExpression(); 773         expression.setBaseExpression(this); 774         expression.addChild(Expression.fromLiteral(datePart, this)); 775         expression.addChild(Expression.from(date, this)); 776         expression.addChild(this); 777         expression.setOperator(anOperator); 778         return expression; 779     } 780 781     /** 782      * PUBLIC: 783      * Function, Return the difference between the queried part of a date(i.e. years, days etc.) 784      * and same part of the given date. The equivalent of the Sybase function DateDiff 785      * <p>Example: 786      * <pre><blockquote> 787      * TopLink: employee.get("date").dateDifference("year", new Date(System.currentTimeMillis())) 788      * Java: NA 789      * SQL: DATEADD(date, 2, GETDATE) 790      * </pre></blockquote> * 791      */ 792     public Expression dateDifference(String datePart, Expression comparisonExpression) { 793         ExpressionOperator anOperator = getOperator(ExpressionOperator.DateDifference); 794         FunctionExpression expression = new FunctionExpression(); 795         expression.setBaseExpression(this); 796         expression.addChild(Expression.fromLiteral(datePart, this)); 797         expression.addChild(comparisonExpression); 798         expression.addChild(this); 799         expression.setOperator(anOperator); 800         return expression; 801     } 802 803     /** 804      * PUBLIC: 805      * return a string that represents the given part of a date. The equivalent 806      * of the Sybase DATENAME function 807      * <p>Example: 808      * <pre><blockquote> 809      * TopLink: employee.get("date").dateName("year") 810      * Java: new String(date.getYear()) 811      * SQL: DATENAME(date, year) 812      * </pre></blockquote> * 813      */ 814     public Expression dateName(String datePart) { 815         ExpressionOperator anOperator = getOperator(ExpressionOperator.DateName); 816         FunctionExpression expression = new FunctionExpression(); 817         expression.setBaseExpression(this); 818         expression.addChild(Expression.fromLiteral(datePart, this)); 819         expression.addChild(this); 820         expression.setOperator(anOperator); 821         return expression; 822     } 823 824     /** 825      * PUBLIC: 826      * Function return an integer which represents the requested 827      * part of the date. Equivalent of the Sybase function DATEPART 828      * <p>Example: 829      * <pre><blockquote> 830      * TopLink: employee.get("date").datePart("year") 831      * Java: date.getYear() 832      * SQL: DATEPART(date, year) 833      * </pre></blockquote> * */ 834     public Expression datePart(String datePart) { 835         ExpressionOperator anOperator = getOperator(ExpressionOperator.DatePart); 836         FunctionExpression expression = new FunctionExpression(); 837         expression.setBaseExpression(this); 838         expression.addChild(Expression.fromLiteral(datePart, this)); 839         expression.addChild(this); 840         expression.setOperator(anOperator); 841         return expression; 842     } 843 844     /** 845      * PUBLIC: 846      * Function, returns the date converted to the string value in the default database format. 847      */ 848     public Expression dateToString() { 849         ExpressionOperator anOperator = getOperator(ExpressionOperator.DateToString); 850         return anOperator.expressionFor(this); 851     } 852 853     /** 854      * PUBLIC: 855      * Function Convert values returned by the query to values 856      * given in the decodeableItems hashtable. The equivalent of 857      * the Oracle DECODE function. Note: This will only work on databases that support 858      * Decode with the syntax below. 859      * <p>Example: 860      * <pre><blockquote> 861      * Hashtable decodeTable = new Hashtable(); 862      * decodeTable.put("Robert", "Bob"); 863      * decodeTable.put("Susan", "Sue"); 864      * 865      * TopLink: employee.get("name").Decode(decodeTable, "No-Nickname") 866      * Java: NA 867      * SQL: DECODE(name, "Robert", "Bob", "Susan", "Sue", "No-Nickname") 868      * </pre></blockquote> 869      * @param decodeableItems java.util.Hashtable 870      * a hashtable containing the items to be decoded. Keys represent 871      * the items to match coming from the query. Values represent what 872      * a key will be changed to. 873      * @param defaultItem 874      * the default value that will be used if none of the keys in the 875      * hashtable match 876      **/ 877     public Expression decode(Hashtable decodeableItems, String defaultItem) { 878 879         /** 880          * decode works differently than most of the functionality in the expression framework. 881          * It takes a variable number of arguments and as a result, the printed strings for 882          * a decode call have to be built when the number of arguments are known. 883          * As a result, we do not look up decode in the ExpressionOperator. Instead we build 884          * the whole operator here. The side effect of this is that decode will not thrown 885          * an invalid operator exception for any platform. (Even the ones that do not support 886          * decode) 887          */ 888         ExpressionOperator anOperator = new ExpressionOperator(); 889         anOperator.setSelector(ExpressionOperator.Decode); 890         anOperator.setNodeClass(ClassConstants.FunctionExpression_Class); 891         anOperator.setType(ExpressionOperator.FunctionOperator); 892         anOperator.bePrefix(); 893 894         Vector v = oracle.toplink.essentials.internal.helper.NonSynchronizedVector.newInstance(decodeableItems.size() + 1); 895         v.addElement("DECODE("); 896         for (int i = 0; i < ((decodeableItems.size() * 2) + 1); i++) { 897             v.addElement(", "); 898         } 899         ; 900         v.addElement(")"); 901         anOperator.printsAs(v); 902 903         FunctionExpression expression = new FunctionExpression(); 904         expression.setBaseExpression(this); 905         expression.addChild(this); 906         Enumeration enumeration = decodeableItems.keys(); 907         while (enumeration.hasMoreElements()) { 908             Object key = enumeration.nextElement(); 909             expression.addChild(Expression.from(key, this)); 910             expression.addChild(Expression.from(decodeableItems.get(key), this)); 911         } 912         ; 913         expression.addChild(Expression.from(defaultItem, this)); 914         expression.setOperator(anOperator); 915         return expression; 916     } 917 918     /** 919      * PUBLIC: 920      * This can only be used within an ordering expression. 921      * It will order the result descending. 922      * <p>Example: 923      * <pre><blockquote> 924      * readAllQuery.addOrderBy(expBuilder.get("address").get("city").descending()) 925      * </blockquote></pre> 926      */ 927     public Expression descending() { 928         return getFunction(ExpressionOperator.Descending); 929     } 930 931     /** 932      * INTERNAL: 933      * Used in debug printing of this node. 934      */ 935     public String descriptionOfNodeType() { 936         return "Expression"; 937     } 938 939 940     /** 941      * INTERNAL: 942      * Check if any element in theObjects is Expression. 943      */ 944     public boolean detectExpression(Vector theObjects) { 945         boolean foundExpression = false; 946         int size = theObjects.size(); 947         for (int i = 0; i < size; i++) { 948             Object element = theObjects.get(i); 949             if (element instanceof Expression) { 950                 foundExpression = true; 951                 break; 952             } 953         } 954         return foundExpression; 955     } 956      957     /** 958      * PUBLIC: 959      * Function return a value which indicates how much difference there is 960      * between two expressions. Equivalent of the Sybase DIFFERENCE function 961      * <p>Example: 962      * <pre><blockquote> 963      * TopLink: employee.get("name").difference("Frank") 964      * SQL: DIFFERENCE(name, 'Frank') 965      * </pre></blockquote> * */ 966     public Expression difference(String expression) { 967         ExpressionOperator anOperator = getOperator(ExpressionOperator.Difference); 968         return anOperator.expressionFor(this, expression); 969     } 970 971     /** 972      * PUBLIC: 973      * Function, This represents the distinct option inside an aggregate function. Can be used only within Report Queries. 974      */ 975     public Expression distinct() { 976         return getFunction(ExpressionOperator.Distinct); 977     } 978 979     /** 980      * INTERNAL: 981      * Check if the object conforms to the expression in memory. 982      * This is used for in-memory querying. 983      * By default throw an exception as all valid root expressions must override. 984      * If the expression in not able to determine if the object conform throw a not supported exception. 985      */ 986     public boolean doesConform(Object object, AbstractSession session, AbstractRecord translationRow, InMemoryQueryIndirectionPolicy valueHolderPolicy) throws QueryException { 987         return doesConform(object, session, translationRow, valueHolderPolicy, false); 988     } 989 990     /** 991      * INTERNAL: 992      * New parameter added to doesConform for feature 2612601 993      * @param isObjectRegistered true if object possibly not a clone, but is being 994      * conformed against the unit of work cache; if object is not in the UOW cache 995      * but some of its attributes are, use the registered versions of 996      * object's attributes for the purposes of this method. 997      */ 998     public boolean doesConform(Object object, AbstractSession session, AbstractRecord translationRow, InMemoryQueryIndirectionPolicy valueHolderPolicy, boolean objectIsUnregistered) throws QueryException { 999         throw QueryException.cannotConformExpression(); 1000    } 1001 1002    public Expression equal(byte theValue) { 1003        return equal(new Byte (theValue)); 1004    } 1005 1006    public Expression equal(char theChar) { 1007        return equal(new Character (theChar)); 1008    } 1009 1010    public Expression equal(double theValue) { 1011        return equal(new Double (theValue)); 1012    } 1013 1014    public Expression equal(float theValue) { 1015        return equal(new Float (theValue)); 1016    } 1017 1018    public Expression equal(int theValue) { 1019        return equal(new Integer (theValue)); 1020    } 1021 1022    public Expression equal(long theValue) { 1023        return equal(new Long (theValue)); 1024    } 1025 1026    /** 1027     * PUBLIC: 1028     * Return an expression that compares if the receiver's value is equal to the other value. 1029     * This is equivalent to the SQL "=" operator and Java "equals" method. 1030     * <p>Example: 1031     * <pre><blockquote> 1032     * TopLink: employee.get("firstName").equal("Bob") 1033     * Java: employee.getFirstName().equals("Bob") 1034     * SQL: F_NAME = 'Bob' 1035     * </blockquote></pre> 1036     */ 1037    public Expression equal(Object theValue) { 1038        ExpressionOperator anOperator = getOperator(ExpressionOperator.Equal); 1039        return anOperator.expressionFor(this, theValue); 1040    } 1041 1042    /** 1043     * Returns an expression that compares if the receiver's value is equal to the other value. 1044     * This is equivalent to the SQL "=" operator and Java "equals" method. 1045     * <p>Since OracleAS TopLink 10<i>g</i> (9.0.4) if <code>this</code> is an <code>ExpressionBuilder</code> and <code>theValue</code> 1046     * is not used elsewhere, both will be translated to the same table. This can 1047     * generate SQL with one less join for most exists subqueries. 1048     * <p>Example: 1049     * <pre><blockquote> 1050     * TopLink: employee.get("manager").equal(employee) 1051     * Java: employee.getManager().equals(employee) 1052     * SQL (optimized): EMP_ID = MANAGER_ID 1053     * SQL (unoptimized): t0.MANAGER_ID = t1.EMP_ID AND t0.EMP_ID = t1.EMP_ID 1054     * </blockquote></pre> 1055     * @see #equal(Object) 1056     */ 1057    public Expression equal(Expression theValue) { 1058        ExpressionOperator anOperator = getOperator(ExpressionOperator.Equal); 1059        return anOperator.expressionFor(this, theValue); 1060 1061    } 1062 1063    public Expression equal(short theValue) { 1064        return equal(new Short (theValue)); 1065    } 1066 1067    public Expression equal(boolean theBoolean) { 1068        return equal(new Boolean (theBoolean)); 1069    } 1070 1071    /** 1072     * INTERNAL: 1073     * Return an expression representing an outer join comparison 1074     */ 1075 1076    // cr3546 1077 public Expression equalOuterJoin(Object theValue) { 1078        ExpressionOperator anOperator = getOperator(ExpressionOperator.EqualOuterJoin); 1079        return anOperator.expressionFor(this, theValue); 1080    } 1081 1082    /** 1083     * INTERNAL: 1084     * Return an expression representing an outer join comparison 1085     */ 1086    public Expression equalOuterJoin(Expression theValue) { 1087        ExpressionOperator anOperator = getOperator(ExpressionOperator.EqualOuterJoin); 1088        return anOperator.expressionFor(this, theValue); 1089 1090    } 1091 1092    /** 1093     * PUBLIC: 1094     * Return an expression that compares if the receiver's value is equal to the other value, ignoring case. 1095     * This is equivalent to the Java "equalsIgnoreCase" method. 1096     * <p>Example: 1097     * <pre><blockquote> 1098     * TopLink: employee.get("firstName").equalsIgnoreCase("Bob") 1099     * Java: employee.getFirstName().equalsIgnoreCase("Bob") 1100     * SQL: UPPER(F_NAME) = 'BOB' 1101     * </blockquote></pre> 1102     */ 1103    public Expression equalsIgnoreCase(String theValue) { 1104        return toUpperCase().equal(theValue.toUpperCase()); 1105    } 1106 1107    /** 1108     * PUBLIC: 1109     * Return an expression that compares if the receiver's value is equal to the other value, ignoring case. 1110     * This is equivalent to the Java "equalsIgnoreCase" method. 1111     * <p>Example: 1112     * <pre><blockquote> 1113     * TopLink: employee.get("firstName").equalsIgnoreCase("Bob") 1114     * Java: employee.getFirstName().equalsIgnoreCase("Bob") 1115     * SQL: UPPER(F_NAME) = 'BOB' 1116     * </blockquote></pre> 1117     */ 1118    public Expression equalsIgnoreCase(Expression theValue) { 1119        return toUpperCase().equal(theValue.toUpperCase()); 1120    } 1121 1122    /** 1123     * PUBLIC: 1124     * Return a sub query expression. 1125     * A sub query using a report query to define a subselect within another queries expression or select's where clause. 1126     * The sub query (the report query) will use its own expression builder be can reference expressions from the base expression builder. 1127     * <p>Example: 1128     * <pre><blockquote> 1129     * ExpressionBuilder builder = new ExpressionBuilder(); 1130     * ReportQuery subQuery = new ReportQuery(Employee.class, new ExpressionBuilder()); 1131     * subQuery.setSelectionCriteria(subQuery.getExpressionBuilder().get("name").equal(builder.get("name"))); 1132     * builder.exists(subQuery); 1133     * </blockquote></pre> 1134     */ 1135    public Expression exists(ReportQuery subQuery) { 1136        ExpressionOperator anOperator = getOperator(ExpressionOperator.Exists); 1137        return anOperator.expressionFor(subQuery(subQuery)); 1138    } 1139 1140    /** 1141     * INTERNAL: 1142     * Extract the primary key from the expression into the row. 1143     * Ensure that the query is quering the exact primary key. 1144     * Return false if not on the primary key. 1145     */ 1146    public boolean extractPrimaryKeyValues(boolean requireExactMatch, ClassDescriptor descriptor, AbstractRecord primaryKeyRow, AbstractRecord translationRow) { 1147        return false; 1148    } 1149 1150    /** 1151     * INTERNAL: 1152     * Create an expression node. 1153     */ 1154    public static Expression from(Object value, Expression base) { 1155        //CR#... null value used to return null, must build a null constant expression. 1156 if (value instanceof Expression) { 1157            Expression exp = (Expression)value; 1158            if (exp.isValueExpression()) { 1159                exp.setLocalBase(base); 1160            } else { 1161                // We don't know which side of the relationship cares about the other one, so notify both 1162 // However for 3107049 value.equal(value) would cause infinite loop if did that. 1163 base.setLocalBase(exp); 1164            } 1165            return exp; 1166        } 1167        if (value instanceof ReportQuery) { 1168            Expression exp = base.subQuery((ReportQuery)value); 1169            exp.setLocalBase(base);// We don't know which side of the relationship cares about the other one, so notify both 1170 base.setLocalBase(exp); 1171            return exp; 1172        } 1173        return fromConstant(value, base); 1174 1175    } 1176 1177    /** 1178     * INTERNAL: 1179     * Create an expression node. 1180     */ 1181    public static Expression fromConstant(Object value, Expression base) { 1182        return new ConstantExpression(value, base); 1183    } 1184 1185    /** 1186     * INTERNAL: 1187     * Create an expression node. 1188     */ 1189    public static Expression fromLiteral(String value, Expression base) { 1190        return new LiteralExpression(value, base); 1191    } 1192 1193    /** 1194     * PUBLIC: 1195     * Return an expression that wraps the attribute or query key name. 1196     * This method is used to construct user-defined queries containing joins. 1197     * <p>Example: 1198     * <pre><blockquote> 1199     * builder.get("address").get("city").equal("Ottawa"); 1200     * </blockquote></pre> 1201     */ 1202    public Expression get(String attributeName) { 1203        return get(attributeName, null); 1204    } 1205 1206    /** 1207     * INTERNAL: 1208     */ 1209    public Expression get(String attributeName, Vector arguments) { 1210        return null; 1211    } 1212 1213    /** 1214     * ADVANCED: 1215     * Return an expression that wraps the attribute or query key name. 1216     * This is only applicable to 1:1 relationships, and allows the target of 1217     * the relationship to be null if there is no correspondingn relationship in the database. 1218     * Implemented via an outer join in the database. 1219     * <p>Example: 1220     * <pre><blockquote> 1221     * builder.getAllowingNull("address").get("city").equal("Ottawa"); 1222     * </blockquote></pre> 1223     */ 1224    public Expression getAllowingNull(String attributeName) { 1225        return getAllowingNull(attributeName, null); 1226    } 1227 1228    /** 1229     * INTERNAL: 1230     */ 1231    public Expression getAllowingNull(String attributeName, Vector arguments) { 1232 1233        /* this is meaningless for expressions in general */ 1234        return get(attributeName, arguments); 1235    } 1236 1237    /** 1238     * INTERNAL: 1239     * Return the expression builder which is the ultimate base of this expression, or 1240     * null if there isn't one (shouldn't happen if we start from a root) 1241     */ 1242    public abstract ExpressionBuilder getBuilder(); 1243 1244    /** 1245     * INTERNAL: 1246     * If there are any fields associated with this expression, return them 1247     */ 1248    public DatabaseField getClonedField() { 1249        return null; 1250    } 1251 1252    /** 1253     * ADVANCED: 1254     * Return an expression representing a field in a data-level query. 1255     * This is used internally in TopLink, or to construct queries involving 1256     * fields and/or tables that are not mapped. 1257     * <p> Example: 1258     * <pre><blockquote> 1259     * builder.getField("ADDR_ID").greaterThan(100); 1260     * builder.getTable("PROJ_EMP").getField("TYPE").equal("S"); 1261     * </blockquote></pre> 1262     */ 1263    public Expression getField(String fieldName) { 1264        throw QueryException.illegalUseOfGetField(fieldName); 1265    } 1266 1267    /** 1268     * ADVANCED: Return an expression representing a field in a data-level query. 1269     * This is used internally in TopLink, or to construct queries involving 1270     * fields and/or tables that are not mapped. 1271     * <p> Example: 1272     * <pre><blockquote> 1273     * builder.getField(aField).greaterThan(100); 1274     * </blockquote></pre> 1275     */ 1276    public Expression getField(DatabaseField field) { 1277        throw QueryException.illegalUseOfGetField(field); 1278    } 1279 1280    /** 1281     * INTERNAL: 1282     */ 1283    public Vector getFields() { 1284        return oracle.toplink.essentials.internal.helper.NonSynchronizedVector.newInstance(1); 1285    } 1286 1287    /** 1288     * INTERNAL: 1289     * Transform the object-level value into a database-level value 1290     */ 1291    public Object getFieldValue(Object objectValue) { 1292        return objectValue; 1293 1294    } 1295 1296    /** 1297     * ADVANCED: 1298     * This can be used for accessing user defined functions. 1299     * The operator must be defined in ExpressionOperator to be able to reference it. 1300     * @see ExpressionOperator 1301     * <p> Example: 1302     * <pre><blockquote> 1303     * builder.get("name").getFunction(MyFunctions.FOO_BAR).greaterThan(100); 1304     * </blockquote></pre> 1305     */ 1306    public Expression getFunction(int selector) { 1307        ExpressionOperator anOperator = getOperator(selector); 1308        return anOperator.expressionFor(this); 1309    } 1310 1311    /** 1312     * ADVANCED: 1313     * This can be used for accessing user defined functions that have arguments. 1314     * The operator must be defined in ExpressionOperator to be able to reference it. 1315     * @see ExpressionOperator 1316     * <p> Example: 1317     * <pre><blockquote> 1318     * Vector arguments = new Vector(); 1319     * arguments.addElement("blee"); 1320     * builder.get("name").getFunction(MyFunctions.FOO_BAR, arguments).greaterThan(100); 1321     * </blockquote></pre> 1322     */ 1323    public Expression getFunction(int selector, Vector arguments) { 1324        ExpressionOperator anOperator = getOperator(selector); 1325        return anOperator.expressionForArguments(this, arguments); 1326    } 1327 1328    /** 1329     * ADVANCED: 1330     * Return a user defined function accepting the argument. 1331     * The function is assumed to be a normal prefix function and will print like, UPPER(base). 1332     * <p> Example: 1333     * <pre><blockquote> 1334     * builder.get("firstName").getFunction("UPPER"); 1335     * </blockquote></pre> 1336     */ 1337    public Expression getFunction(String functionName) { 1338        ExpressionOperator anOperator = ExpressionOperator.simpleFunction(0, functionName); 1339        return anOperator.expressionFor(this); 1340    } 1341 1342    /** 1343     * ADVANCED: 1344     * Return a user defined function accepting the argument. 1345     * The function is assumed to be a normal prefix function and will print like, CONCAT(base, argument). 1346     */ 1347    public Expression getFunction(String functionName, Object argument) { 1348        ExpressionOperator anOperator = ExpressionOperator.simpleTwoArgumentFunction(0, functionName); 1349        return anOperator.expressionFor(this, argument); 1350    } 1351 1352    /** 1353     * ADVANCED: 1354     * Return a user defined function accepting all of the arguments. 1355     * The function is assumed to be a normal prefix function like, CONCAT(base, value1, value2, value3, ...). 1356     */ 1357    public Expression getFunctionWithArguments(String functionName, Vector arguments) { 1358        ExpressionOperator anOperator = new ExpressionOperator(); 1359        anOperator.setType(ExpressionOperator.FunctionOperator); 1360        Vector v = oracle.toplink.essentials.internal.helper.NonSynchronizedVector.newInstance(arguments.size()); 1361        v.addElement(functionName + "("); 1362        for (int index = 0; index < arguments.size(); index++) { 1363            v.addElement(", "); 1364        } 1365        v.addElement(")"); 1366        anOperator.printsAs(v); 1367        anOperator.bePrefix(); 1368        anOperator.setNodeClass(ClassConstants.FunctionExpression_Class); 1369 1370        return anOperator.expressionForArguments(this, arguments); 1371    } 1372 1373    /** 1374     * INTERNAL: 1375     */ 1376    public String getName() { 1377        return ""; 1378    } 1379 1380    /** 1381     * INTERNAL: 1382     * Most expression have operators, so this is just a convenience method. 1383     */ 1384    public ExpressionOperator getOperator() { 1385        return null; 1386    } 1387 1388    /** 1389     * INTERNAL: 1390     * Create a new expression tree with the named operator. Part of the implementation of user-level "get" 1391     */ 1392    public ExpressionOperator getOperator(int selector) { 1393        ExpressionOperator result = ExpressionOperator.getOperator(new Integer (selector)); 1394        if (result != null) { 1395            return result; 1396        } 1397 1398        // Make a temporary operator which we expect the platform 1399 // to supply later. 1400 result = new ExpressionOperator(); 1401        result.setSelector(selector); 1402        result.setNodeClass(ClassConstants.FunctionExpression_Class); 1403        return result; 1404    } 1405 1406    /** 1407     * INTERNAL: 1408     * Return the tables that this node owns for purposes of table aliasing. 1409     */ 1410    public Vector getOwnedTables() { 1411        return null; 1412    } 1413 1414    /** 1415     * INTERNAL: 1416     * Return an expression representing a parameter with the given name and type 1417     */ 1418    public Expression getParameter(String parameterName, Object type) { 1419        return new ParameterExpression(parameterName, this, type); 1420 1421    } 1422 1423    /** 1424     * ADVANCED: 1425     * Return an expression representing a parameter with the given name. 1426     */ 1427    public Expression getParameter(String parameterName) { 1428        return new ParameterExpression(parameterName, this, null); 1429 1430    } 1431 1432    /** 1433     * ADVANCED: 1434     * Return an expression representing a parameter with the given name. 1435     */ 1436    public Expression getParameter(DatabaseField field) { 1437        return new ParameterExpression(field, this); 1438 1439    } 1440 1441    /** 1442     * INTERNAL: 1443     */ 1444    public AbstractSession getSession() { 1445        return getBuilder().getSession(); 1446    } 1447 1448    /** 1449     * ADVANCED: Return an expression representing a table in a data-level query. 1450     * This is used internally in TopLink, or to construct queries involving 1451     * fields and/or tables that are not mapped. 1452     * <p> Example: 1453     * <pre><blockquote> 1454     * builder.getTable("PROJ_EMP").getField("TYPE").equal("S"); 1455     * </blockquote></pre> 1456     */ 1457    public Expression getTable(String tableName) { 1458        DatabaseTable table = new DatabaseTable(tableName); 1459        return getTable(table); 1460    } 1461 1462    /** 1463     * ADVANCED: Return an expression representing a table in a data-level query. 1464     * This is used internally in TopLink, or to construct queries involving 1465     * fields and/or tables that are not mapped. 1466     * <p> Example: 1467     * <pre><blockquote> 1468     * builder.getTable(linkTable).getField("TYPE").equal("S"); 1469     * </blockquote></pre> 1470     */ 1471    public Expression getTable(DatabaseTable table) { 1472        throw QueryException.illegalUseOfGetTable(table); 1473    } 1474 1475    /** 1476     * INTERNAL: 1477     * Return the aliases used. By default, return null, since we don't have tables. 1478     */ 1479    public TableAliasLookup getTableAliases() { 1480        return null; 1481 1482    } 1483 1484    /** 1485     * PUBLIC: 1486     * Return an expression that compares if the receivers value is equal to the other value. 1487     * This is equivalent to the SQL "=" operator and Java "equals" method. 1488     */ 1489    public Expression greaterThan(byte theValue) { 1490        return greaterThan(new Byte (theValue)); 1491    } 1492 1493    /** 1494     * PUBLIC: 1495     * Return an expression that compares if the receivers value is equal to the other value. 1496     * This is equivalent to the SQL "=" operator and Java "equals" method. 1497     */ 1498    public Expression greaterThan(char theChar) { 1499        return greaterThan(new Character (theChar)); 1500    } 1501 1502    /** 1503     * PUBLIC: 1504     * Return an expression that compares if the receivers value is equal to the other value. 1505     * This is equivalent to the SQL "=" operator and Java "equals" method. 1506     */ 1507    public Expression greaterThan(double theValue) { 1508        return greaterThan(new Double (theValue)); 1509    } 1510 1511    /** 1512     * PUBLIC: 1513     * Return an expression that compares if the receivers value is equal to the other value. 1514     * This is equivalent to the SQL "=" operator and Java "equals" method. 1515     */ 1516    public Expression greaterThan(float theValue) { 1517        return greaterThan(new Float (theValue)); 1518    } 1519 1520    /** 1521     * PUBLIC: 1522     * Return an expression that compares if the receivers value is equal to the other value. 1523     * This is equivalent to the SQL "=" operator and Java "equals" method. 1524     */ 1525    public Expression greaterThan(int theValue) { 1526        return greaterThan(new Integer (theValue)); 1527    } 1528 1529    /** 1530     * PUBLIC: 1531     * Return an expression that compares if the receivers value is equal to the other value. 1532     * This is equivalent to the SQL "=" operator and Java "equals" method. 1533     */ 1534    public Expression greaterThan(long theValue) { 1535        return greaterThan(new Long (theValue)); 1536    } 1537 1538    /** 1539     * PUBLIC: 1540     * Return an expression that compares if the receiver's value is greater than the other value. 1541     * This is equivalent to the SQL ">" operator. 1542     */ 1543    public Expression greaterThan(Object theValue) { 1544        ExpressionOperator anOperator = getOperator(ExpressionOperator.GreaterThan); 1545        return anOperator.expressionFor(this, theValue); 1546    } 1547 1548    public Expression greaterThan(Expression theValue) { 1549        ExpressionOperator anOperator = getOperator(ExpressionOperator.GreaterThan); 1550        return anOperator.expressionFor(this, theValue); 1551 1552    } 1553 1554    /** 1555     * PUBLIC: 1556     * Return an expression that compares if the receivers value is equal to the other value. 1557     * This is equivalent to the SQL "=" operator and Java "equals" method. 1558     */ 1559    public Expression greaterThan(short theValue) { 1560        return greaterThan(new Short (theValue)); 1561    } 1562 1563    /** 1564     * PUBLIC: 1565     * Return an expression that compares if the receivers value is equal to the other value. 1566     * This is equivalent to the SQL "=" operator and Java "equals" method. 1567     */ 1568    public Expression greaterThan(boolean theBoolean) { 1569        return greaterThan(new Boolean (theBoolean)); 1570    } 1571 1572    /** 1573     * PUBLIC: 1574     * Return an expression that compares if the receivers value is greater and equal to the other value. 1575     * This is equivalent to the SQL ">=" operator . 1576     */ 1577    public Expression greaterThanEqual(byte theValue) { 1578        return greaterThanEqual(new Byte (theValue)); 1579    } 1580 1581    /** 1582     * PUBLIC: 1583     * Return an expression that compares if the receivers value is greater and equal to the other value. 1584     * This is equivalent to the SQL ">=" operator . 1585     */ 1586    public Expression greaterThanEqual(char theChar) { 1587        return greaterThanEqual(new Character (theChar)); 1588    } 1589 1590    /** 1591     * PUBLIC: 1592     * Return an expression that compares if the receivers value is greater and equal to the other value. 1593     * This is equivalent to the SQL ">=" operator . 1594     */ 1595    public Expression greaterThanEqual(double theValue) { 1596        return greaterThanEqual(new Double (theValue)); 1597    } 1598 1599    /** 1600     * PUBLIC: 1601     * Return an expression that compares if the receivers value is greater and equal to the other value. 1602     * This is equivalent to the SQL ">=" operator . 1603     */ 1604    public Expression greaterThanEqual(float theValue) { 1605        return greaterThanEqual(new Float (theValue)); 1606    } 1607 1608    /** 1609     * PUBLIC: 1610     * Return an expression that compares if the receivers value is greater and equal to the other value. 1611     * This is equivalent to the SQL ">=" operator . 1612     */ 1613    public Expression greaterThanEqual(int theValue) { 1614        return greaterThanEqual(new Integer (theValue)); 1615    } 1616 1617    /** 1618     * PUBLIC: 1619     * Return an expression that compares if the receivers value is greater and equal to the other value. 1620     * This is equivalent to the SQL ">=" operator . 1621     */ 1622    public Expression greaterThanEqual(long theValue) { 1623        return greaterThanEqual(new Long (theValue)); 1624    } 1625 1626    /** 1627     * PUBLIC: 1628     * Return an expression that compares if the receivers value is greater and equal to the other value. 1629     * This is equivalent to the SQL ">=" operator . 1630     */ 1631    public Expression greaterThanEqual(Object theValue) { 1632        ExpressionOperator anOperator = getOperator(ExpressionOperator.GreaterThanEqual); 1633        return anOperator.expressionFor(this, theValue); 1634 1635    } 1636 1637    /** 1638     * PUBLIC: 1639     * Return an expression that compares if the receivers value is greater and equal to the other value. 1640     * This is equivalent to the SQL ">=" operator . 1641     */ 1642    public Expression greaterThanEqual(Expression theValue) { 1643        ExpressionOperator anOperator = getOperator(ExpressionOperator.GreaterThanEqual); 1644        return anOperator.expressionFor(this, theValue); 1645 1646    } 1647 1648    /** 1649     * PUBLIC: 1650     * Return an expression that compares if the receivers value is greater and equal to the other value. 1651     * This is equivalent to the SQL ">=" operator . 1652     */ 1653    public Expression greaterThanEqual(short theValue) { 1654        return greaterThanEqual(new Short (theValue)); 1655    } 1656 1657    /** 1658     * PUBLIC: 1659     * Return an expression that compares if the receivers value is greater and equal to the other value. 1660     * This is equivalent to the SQL ">=" operator . 1661     */ 1662    public Expression greaterThanEqual(boolean theBoolean) { 1663        return greaterThanEqual(new Boolean (theBoolean)); 1664    } 1665 1666    /** 1667     * ADVANCED: 1668     * Answers true if <code>this</code> is to be queried as of a past time. 1669     * @return false from <code>asOf(null); hasAsOfClause()</code>. 1670     * @see #getAsOfClause 1671     */ 1672    public boolean hasAsOfClause() { 1673        return false; 1674    } 1675 1676    /** 1677     * INTERNAL: 1678     * Answers if the database tables associated with this expression have been 1679     * aliased. This insures the same tables are not aliased twice. 1680     */ 1681    public boolean hasBeenAliased() { 1682        return false; 1683    } 1684 1685    /** 1686     * PUBLIC: 1687     * Function, returns binary array value for the hex string. 1688     */ 1689    public Expression hexToRaw() { 1690        ExpressionOperator anOperator = getOperator(ExpressionOperator.HexToRaw); 1691        return anOperator.expressionFor(this); 1692    } 1693 1694    /** 1695     * PUBLIC: 1696     * Function return the a specific value if item returned from the 1697     * query is null. Equivalent of the oracle NVL function 1698     * <p>Example: 1699     * <pre><blockquote> 1700     * TopLink: employee.get("name").ifNull("no-name") 1701     * Java: NA 1702     * SQL: NVL(name, 'no-name') 1703     * </pre></blockquote> * 1704     */ 1705    public Expression ifNull(Object nullValue) { 1706        ExpressionOperator anOperator = getOperator(ExpressionOperator.Nvl); 1707        return anOperator.expressionFor(this, nullValue); 1708    } 1709 1710    /** 1711     * PUBLIC: 1712     * Return an expression that checks if the receivers value is contained in the collection. 1713     * This is equivalent to the SQL "IN" operator and Java "contains" operator. 1714     */ 1715    public Expression in(byte[] theBytes) { 1716        Vector vector = oracle.toplink.essentials.internal.helper.NonSynchronizedVector.newInstance(); 1717 1718        for (int index = 0; index < theBytes.length; index++) { 1719            vector.addElement(new Byte (theBytes[index])); 1720        } 1721 1722        return in(vector); 1723    } 1724 1725    /** 1726     * PUBLIC: 1727     * Return an expression that checks if the receivers value is contained in the collection. 1728     * This is equivalent to the SQL "IN" operator and Java "contains" operator. 1729     */ 1730    public Expression in(char[] theChars) { 1731        Vector vector = oracle.toplink.essentials.internal.helper.NonSynchronizedVector.newInstance(); 1732 1733        for (int index = 0; index < theChars.length; index++) { 1734            vector.addElement(new Character (theChars[index])); 1735        } 1736 1737        return in(vector); 1738    } 1739 1740    /** 1741     * PUBLIC: 1742     * Return an expression that checks if the receivers value is contained in the collection. 1743     * This is equivalent to the SQL "IN" operator and Java "contains" operator. 1744     */ 1745    public Expression in(double[] theDoubles) { 1746        Vector vector = oracle.toplink.essentials.internal.helper.NonSynchronizedVector.newInstance(); 1747 1748        for (int index = 0; index < theDoubles.length; index++) { 1749            vector.addElement(new Double (theDoubles[index])); 1750        } 1751 1752        return in(vector); 1753    } 1754 1755    /** 1756     * PUBLIC: 1757     * Return an expression that checks if the receivers value is contained in the collection. 1758     * This is equivalent to the SQL "IN" operator and Java "contains" operator. 1759     */ 1760    public Expression in(float[] theFloats) { 1761        Vector vector = oracle.toplink.essentials.internal.helper.NonSynchronizedVector.newInstance(); 1762 1763        for (int index = 0; index < theFloats.length; index++) { 1764            vector.addElement(new Float (theFloats[index])); 1765        } 1766 1767        return in(vector); 1768    } 1769 1770    /** 1771     * PUBLIC: 1772     * Return an expression that checks if the receivers value is contained in the collection. 1773     * This is equivalent to the SQL "IN" operator and Java "contains" operator. 1774     */ 1775    public Expression in(int[] theInts) { 1776        Vector vector = oracle.toplink.essentials.internal.helper.NonSynchronizedVector.newInstance(); 1777 1778        for (int index = 0; index < theInts.length; index++) { 1779            vector.addElement(new Integer (theInts[index])); 1780        } 1781 1782        return in(vector); 1783    } 1784 1785    /** 1786     * PUBLIC: 1787     * Return an expression that checks if the receivers value is contained in the collection. 1788     * This is equivalent to the SQL "IN" operator and Java "contains" operator. 1789     */ 1790    public Expression in(long[] theLongs) { 1791        Vector vector = oracle.toplink.essentials.internal.helper.NonSynchronizedVector.newInstance(); 1792 1793        for (int index = 0; index < theLongs.length; index++) { 1794            vector.addElement(new Long (theLongs[index])); 1795        } 1796 1797        return in(vector); 1798    } 1799 1800    /** 1801     * PUBLIC: 1802     * Return an expression that checks if the receivers value is contained in the collection. 1803     * This is equivalent to the SQL "IN" operator and Java "contains" operator. 1804     */ 1805    public Expression in(Object [] theObjects) { 1806        Vector vector = oracle.toplink.essentials.internal.helper.NonSynchronizedVector.newInstance(); 1807 1808        for (int index = 0; index < theObjects.length; index++) { 1809            vector.addElement(theObjects[index]); 1810        } 1811 1812        return in(vector); 1813    } 1814 1815    /** 1816     * PUBLIC: 1817     * Return an expression that checks if the receivers value is contained in the collection. 1818     * This is equivalent to the SQL "IN" operator and Java "contains" operator. 1819     */ 1820    public Expression in(short[] theShorts) { 1821        Vector vector = oracle.toplink.essentials.internal.helper.NonSynchronizedVector.newInstance(); 1822 1823        for (int index = 0; index < theShorts.length; index++) { 1824            vector.addElement(new Short (theShorts[index])); 1825        } 1826 1827        return in(vector); 1828    } 1829 1830    /** 1831     * PUBLIC: 1832     * Return an expression that checks if the receivers value is contained in the collection. 1833     * This is equivalent to the SQL "IN" operator and Java "contains" operator. 1834     */ 1835    public Expression in(boolean[] theBooleans) { 1836        Vector vector = oracle.toplink.essentials.internal.helper.NonSynchronizedVector.newInstance(); 1837 1838        for (int index = 0; index < theBooleans.length; index++) { 1839            vector.addElement(new Boolean (theBooleans[index])); 1840        } 1841 1842        return in(vector); 1843    } 1844 1845    /** 1846     * PUBLIC: 1847     * Return an expression that checks if the receivers value is contained in the collection. 1848     * The collection can be a collection of constants or expressions. 1849     * This is equivalent to the SQL "IN" operator and Java "contains" operator. 1850     * <p>Example: 1851     * <pre><blockquote> 1852     * TopLink: employee.get("age").in(agesVector) 1853     * Java: agesVector.contains(employee.getAge()) 1854     * SQL: AGE IN (55, 18, 30) 1855     * </blockquote></pre> 1856     */ 1857    public Expression in(Vector theObjects) { 1858        //If none of the elements in theObjects is expression, build a ConstantExpression with theObjects. 1859 if (!detectExpression(theObjects)) { 1860            return in(new ConstantExpression(theObjects, this)); 1861        } 1862        //Otherwise build a collection of expressions. 1863 ExpressionOperator anOperator = getOperator(ExpressionOperator.In); 1864        return anOperator.expressionForArguments(this, theObjects); 1865    } 1866 1867    public Expression in(Expression arguments) { 1868        ExpressionOperator anOperator = getOperator(ExpressionOperator.In); 1869        return anOperator.expressionFor(this, arguments); 1870    } 1871 1872    public Expression in(ReportQuery subQuery) { 1873        return in(subQuery(subQuery)); 1874    } 1875 1876    /** 1877     * PUBLIC: 1878     * Function, returns the integer index of the substring within the source string. 1879     */ 1880    public Expression indexOf(Object substring) { 1881        ExpressionOperator anOperator = getOperator(ExpressionOperator.Instring); 1882        return anOperator.expressionFor(this, substring); 1883    } 1884 1885    /** 1886     * INTERNAL: 1887     */ 1888    public boolean isCompoundExpression() { 1889        return false; 1890    } 1891 1892    /** 1893     * INTERNAL: 1894     */ 1895    public boolean isConstantExpression() { 1896        return false; 1897    } 1898 1899    /** 1900     * INTERNAL: 1901     */ 1902    public boolean isDataExpression() { 1903        return false; 1904    } 1905 1906    /** 1907     * PUBLIC: A logical expression for the collection <code>attributeName</code> 1908     * being empty. 1909     * Equivalent to <code>size(attributeName).equal(0)</code> 1910     * <p>Example: 1911     * <pre><blockquote> 1912     * TopLink: employee.isEmpty("phoneNumbers") 1913     * Java: employee.getPhoneNumbers().size() == 0 1914     * SQL: SELECT ... FROM EMP t0 WHERE ( 1915     * (SELECT COUNT(*) FROM PHONE t1 WHERE (t0.EMP_ID = t1.EMP_ID)) = 0) 1916     * </blockquote></pre> 1917     * This is a case where a fast operation in java does not translate to an 1918     * equally fast operation in SQL, requiring a correlated subselect. 1919     * @see #size(java.lang.String) 1920     */ 1921    public Expression isEmpty(String attributeName) { 1922        return size(attributeName).equal(0); 1923    } 1924 1925    /** 1926     * INTERNAL: 1927     */ 1928    public boolean isExpressionBuilder() { 1929        return false; 1930    } 1931 1932    /** 1933     * INTERNAL: 1934     */ 1935    public boolean isFieldExpression() { 1936        return false; 1937    } 1938 1939    /** 1940     * INTERNAL: 1941     */ 1942    public boolean isFunctionExpression() { 1943        return false; 1944    } 1945 1946    /** 1947     * INTERNAL: 1948     */ 1949    public boolean isLiteralExpression() { 1950        return false; 1951    } 1952 1953    /** 1954     * INTERNAL: 1955     */ 1956    public boolean isLogicalExpression() { 1957        return false; 1958    } 1959 1960    /** 1961     * PUBLIC: 1962     * Compare to null. 1963     */ 1964    public Expression isNull() { 1965        ExpressionOperator anOperator = getOperator(ExpressionOperator.IsNull); 1966        return anOperator.expressionFor(this); 1967    } 1968 1969    /** 1970     * INTERNAL: 1971     */ 1972    public boolean isObjectExpression() { 1973        return false; 1974    } 1975 1976    /** 1977     * INTERNAL: 1978     */ 1979    public boolean isParameterExpression() { 1980        return false; 1981    } 1982 1983    /** 1984     * INTERNAL: 1985     */ 1986    public boolean isQueryKeyExpression() { 1987        return false; 1988    } 1989 1990    /** 1991     * INTERNAL: 1992     */ 1993    public boolean isRelationExpression() { 1994        return false; 1995    } 1996 1997    /** 1998     * INTERNAL: 1999     */ 2000    public boolean isTableExpression() { 2001        return false; 2002    } 2003 2004    /** 2005     * INTERNAL: 2006     * Subclasses implement (isParameterExpression() || isConstantExpression()) 2007     */ 2008    public boolean isValueExpression() { 2009        return false; 2010    } 2011 2012    /** 2013     * INTERNAL: 2014     * For iterating using an inner class 2015     */ 2016    public void iterateOn(ExpressionIterator iterator) { 2017        iterator.iterate(this); 2018    } 2019 2020    /** 2021     * PUBLIC: 2022     * Function, returns the date with the last date in the months of this source date. 2023     */ 2024    public Expression lastDay() { 2025        ExpressionOperator anOperator = getOperator(ExpressionOperator.LastDay); 2026        return anOperator.expressionFor(this); 2027    } 2028 2029    /** 2030     * PUBLIC: 2031     * Function, returns the string padded with the substring to the size. 2032     */ 2033    public Expression leftPad(int size, Object substring) { 2034        return leftPad(new Integer (size), substring); 2035    } 2036 2037    /** 2038     * PUBLIC: 2039     * Function, returns the string padded with the substring to the size. 2040     */ 2041    public Expression leftPad(Object size, Object substring) { 2042        ExpressionOperator anOperator = getOperator(ExpressionOperator.LeftPad); 2043        Vector args = oracle.toplink.essentials.internal.helper.NonSynchronizedVector.newInstance(2); 2044        args.addElement(size); 2045        args.addElement(substring); 2046        return anOperator.expressionForArguments(this, args); 2047    } 2048 2049    /** 2050     * PUBLIC: 2051     * Function, returns the string left trimmed for white space. 2052     */ 2053    public Expression leftTrim() { 2054        ExpressionOperator anOperator = getOperator(ExpressionOperator.LeftTrim); 2055        return anOperator.expressionFor(this); 2056    } 2057     2058    /** 2059     * PUBLIC: 2060     * Function, returns the string with the substring trimed from the left. 2061     */ 2062    public Expression leftTrim(Object substring) { 2063        ExpressionOperator anOperator = getOperator(ExpressionOperator.LeftTrim2); 2064        return anOperator.expressionFor(this, substring); 2065    } 2066 2067    /** 2068     * PUBLIC: 2069     * Function, returns the size of the string. 2070     */ 2071    public Expression length() { 2072        ExpressionOperator anOperator = getOperator(ExpressionOperator.Length); 2073        return anOperator.expressionFor(this); 2074    } 2075 2076    /** 2077     * PUBLIC: 2078     * Return an expression that compares if the receivers value is less than the other value. 2079     * This is equivalent to the SQL "<" operator. 2080     */ 2081    public Expression lessThan(byte theValue) { 2082        return lessThan(new Byte (theValue)); 2083    } 2084 2085    /** 2086     * PUBLIC: 2087     * Return an expression that compares if the receivers value is less than the other value. 2088     * This is equivalent to the SQL "<" operator. 2089     */ 2090    public Expression lessThan(char theChar) { 2091        return lessThan(new Character (theChar)); 2092    } 2093 2094    /** 2095     * PUBLIC: 2096     * Return an expression that compares if the receivers value is less than the other value. 2097     * This is equivalent to the SQL "<" operator. 2098     */ 2099    public Expression lessThan(double theValue) { 2100        return lessThan(new Double (theValue)); 2101    } 2102 2103    /** 2104     * PUBLIC: 2105     * Return an expression that compares if the receivers value is less than the other value. 2106     * This is equivalent to the SQL "<" operator. 2107     */ 2108    public Expression lessThan(float theValue) { 2109        return lessThan(new Float (theValue)); 2110    } 2111 2112    /** 2113     * PUBLIC: 2114     * Return an expression that compares if the receivers value is less than the other value. 2115     * This is equivalent to the SQL "<" operator. 2116     */ 2117    public Expression lessThan(int theValue) { 2118        return lessThan(new Integer (theValue)); 2119    } 2120 2121    /** 2122     * PUBLIC: 2123     * Return an expression that compares if the receivers value is less than the other value. 2124     * This is equivalent to the SQL "<" operator. 2125     */ 2126    public Expression lessThan(long theValue) { 2127        return lessThan(new Long (theValue)); 2128    } 2129 2130    /** 2131     * PUBLIC: 2132     * Return an expression that compares if the receivers value is less than the other value. 2133     * This is equivalent to the SQL "<" operator. 2134     */ 2135    public Expression lessThan(Object theValue) { 2136        ExpressionOperator anOperator = getOperator(ExpressionOperator.LessThan); 2137        return anOperator.expressionFor(this, theValue); 2138    } 2139 2140    public Expression lessThan(Expression theValue) { 2141        ExpressionOperator anOperator = getOperator(ExpressionOperator.LessThan); 2142        return anOperator.expressionFor(this, theValue); 2143 2144    } 2145 2146    /** 2147     * PUBLIC: 2148     * Return an expression that compares if the receivers value is less than the other value. 2149     * This is equivalent to the SQL "<" operator. 2150     */ 2151    public Expression lessThan(short theValue) { 2152        return lessThan(new Short (theValue)); 2153    } 2154 2155    /** 2156     * PUBLIC: 2157     * Return an expression that compares if the receivers value is less than the other value. 2158     * This is equivalent to the SQL "<" operator. 2159     */ 2160    public Expression lessThan(boolean theBoolean) { 2161        return lessThan(new Boolean (theBoolean)); 2162    } 2163 2164    /** 2165     * PUBLIC: 2166     * Return an expression that compares if the receivers value is less than and equal to the other value. 2167     * This is equivalent to the SQL "<=" operator. 2168     */ 2169    public Expression lessThanEqual(byte theValue) { 2170        return lessThanEqual(new Byte (theValue)); 2171    } 2172 2173    /** 2174     * PUBLIC: 2175     * Return an expression that compares if the receivers value is less than and equal to the other value. 2176     * This is equivalent to the SQL "<=" operator. 2177     */ 2178    public Expression lessThanEqual(char theChar) { 2179        return lessThanEqual(new Character (theChar)); 2180    } 2181 2182    /** 2183     * PUBLIC: 2184     * Return an expression that compares if the receivers value is less than and equal to the other value. 2185     * This is equivalent to the SQL "<=" operator. 2186     */ 2187    public Expression lessThanEqual(double theValue) { 2188        return lessThanEqual(new Double (theValue)); 2189    } 2190 2191    /** 2192     * PUBLIC: 2193     * Return an expression that compares if the receivers value is less than and equal to the other value. 2194     * This is equivalent to the SQL "<=" operator. 2195     */ 2196    public Expression lessThanEqual(float theValue) { 2197        return lessThanEqual(new Float (theValue)); 2198    } 2199 2200    /** 2201     * PUBLIC: 2202     * Return an expression that compares if the receivers value is less than and equal to the other value. 2203     * This is equivalent to the SQL "<=" operator. 2204     */ 2205    public Expression lessThanEqual(int theValue) { 2206        return lessThanEqual(new Integer (theValue)); 2207    } 2208 2209    /** 2210     * PUBLIC: 2211     * Return an expression that compares if the receivers value is less than and equal to the other value. 2212     * This is equivalent to the SQL "<=" operator. 2213     */ 2214    public Expression lessThanEqual(long theValue) { 2215        return lessThanEqual(new Long (theValue)); 2216    } 2217 2218    /** 2219     * PUBLIC: 2220     * Return an expression that compares if the receivers value is less than and equal to the other value. 2221     * This is equivalent to the SQL "<=" operator. 2222     */ 2223    public Expression lessThanEqual(Object theValue) { 2224        ExpressionOperator anOperator = getOperator(ExpressionOperator.LessThanEqual); 2225        return anOperator.expressionFor(this, theValue); 2226    } 2227 2228    /** 2229     * PUBLIC: 2230     * Return an expression that compares if the receivers value is less than and equal to the other value. 2231     * This is equivalent to the SQL "<=" operator. 2232     */ 2233    public Expression lessThanEqual(Expression theValue) { 2234        ExpressionOperator anOperator = getOperator(ExpressionOperator.LessThanEqual); 2235        return anOperator.expressionFor(this, theValue); 2236 2237    } 2238 2239    /** 2240     * PUBLIC: 2241     * Return an expression that compares if the receivers value is less than and equal to the other value. 2242     * This is equivalent to the SQL "<=" operator. 2243     */ 2244    public Expression lessThanEqual(short theValue) { 2245        return lessThanEqual(new Short (theValue)); 2246    } 2247 2248    /** 2249     * PUBLIC: 2250     * Return an expression that compares if the receivers value is less than and equal to the other value. 2251     * This is equivalent to the SQL "<=" operator. 2252     */ 2253    public Expression lessThanEqual(boolean theBoolean) { 2254        return lessThanEqual(new Boolean (theBoolean)); 2255    } 2256 2257    /** 2258     * PUBLIC: 2259     * Return an expression that compares if the receivers value is like other value. 2260     * This is equivalent to the SQL "LIKE" operator that except wildcards. 2261     * The character "%" means any sequence of characters and the character "_" mean any character. 2262     * i.e. "B%" == "Bob", "B_B" == "BOB" 2263     * <p>Example: 2264     * <pre><blockquote> 2265     * TopLink: employee.get("firstName").like("B%") 2266     * Java: NA 2267     * SQL: F_NAME LIKE 'B%' 2268     * </blockquote></pre> 2269     */ 2270    public Expression like(String value) { 2271        return like(new ConstantExpression(value, this)); 2272    } 2273 2274    /** 2275     * PUBLIC: 2276     * Return an expression that compares if the receivers value is like other value. 2277     * This is equivalent to the SQL "LIKE ESCAPE" operator that except wildcards. 2278     * The character "%" means any sequence of characters and the character "_" mean any character. 2279     * i.e. "B%" == "Bob", "B_B" == "BOB" 2280     * The escape sequence specifies a set of characters the may be used to indicate that 2281     * an one of the wildcard characters should be interpretted literally. 2282     * <p>Example: 2283     * <pre><blockquote> 2284     * TopLink: employee.get("firstName").like("B\_SMITH", "\") 2285     * Java: NA 2286     * SQL: F_NAME LIKE 'B\_SMITH ESCAPE '\'' 2287     * </blockquote></pre> 2288     */ 2289    public Expression like(String value, String escapeSequence) { 2290        ExpressionOperator anOperator = getOperator(ExpressionOperator.LikeEscape); 2291        Vector args = oracle.toplink.essentials.internal.helper.NonSynchronizedVector.newInstance(); 2292        args.addElement(value); 2293        args.addElement(escapeSequence); 2294        return anOperator.expressionForArguments(this, args); 2295    } 2296 2297    /** 2298     * PUBLIC: 2299     * Return an expression that compares if the receivers value is like other value. 2300     * This is equivalent to the SQL "LIKE" operator that except wildcards. 2301     * The character "%" means any sequence of characters and the character "_" mean any character. 2302     * i.e. "B%" == "Bob", "B_B" == "BOB" 2303     * <p>Example: 2304     * <pre><blockquote> 2305     * TopLink: employee.get("firstName").like("B%") 2306     * Java: NA 2307     * SQL: F_NAME LIKE 'B%' 2308     * </pre></blockquote> 2309     */ 2310    public Expression like(Expression argument) { 2311        ExpressionOperator anOperator = getOperator(ExpressionOperator.Like); 2312        return anOperator.expressionFor(this, argument); 2313    } 2314 2315    /** 2316     * PUBLIC: 2317     * Return an expression that compares if the receivers value is like other value. 2318     * This is equivalent to the SQL "LIKE ESCAPE" operator that except wildcards. 2319     * The character "%" means any sequence of characters and the character "_" mean any character. 2320     * i.e. "B%" == "Bob", "B_B" == "BOB" 2321     * The escape sequence specifies a set of characters the may be used to indicate that 2322     * an one of the wildcard characters should be interpretted literally. 2323     * <p>Example: 2324     * <pre><blockquote> 2325     * TopLink: employee.get("firstName").like("B\_SMITH", "\") 2326     * Java: NA 2327     * SQL: F_NAME LIKE 'B\_SMITH ESCAPE '\'' 2328     * </blockquote></pre> 2329     */ 2330    public Expression like(Expression value, Expression escapeSequence) { 2331        ExpressionOperator anOperator = getOperator(ExpressionOperator.LikeEscape); 2332        Vector args = new Vector(); 2333        args.addElement(value); 2334        args.addElement(escapeSequence); 2335        return anOperator.expressionForArguments(this, args); 2336    } 2337 2338    /** 2339     * PUBLIC: 2340     * Return an expression that compares if the receivers value is like the other value, ignoring case. 2341     * This is a case in-sensitive like. 2342     * <p>Example: 2343     * <pre><blockquote> 2344     * TopLink: employee.get("firstName").likeIgnoreCase("%Bob%") 2345     * Java: none 2346     * SQL: UPPER(F_NAME) LIKE '%BOB%' 2347     * </pre></blockquote> 2348     */ 2349    public Expression likeIgnoreCase(String theValue) { 2350        return toUpperCase().like(theValue.toUpperCase()); 2351    } 2352 2353    /** 2354     * PUBLIC: 2355     * Return an expression that compares if the receivers value is like the other value, ignoring case. 2356     * This is a case in-sensitive like. 2357     */ 2358    public Expression likeIgnoreCase(Expression theValue) { 2359        return toUpperCase().like(theValue.toUpperCase()); 2360    } 2361 2362    /** 2363     * PUBLIC: 2364     * Function, returns the position of <code>str</code> in <code>this</code> 2365     * <p>Example: 2366     * <pre><blockquote> 2367     * TopLink: employee.get("firstName").locate("ob") 2368     * Java: employee.getFirstName().indexOf("ob") + 1 2369     * SQL: LOCATE('ob', t0.F_NAME) 2370     * </pre></blockquote> 2371     * <p> 2372     * Note that while in String.locate(str) -1 is returned if not found, and the 2373     * index starting at 0 if found, in SQL it is 0 if not found, and the index 2374     * starting at 1 if found. 2375     */ 2376    public Expression locate(Object str) { 2377        ExpressionOperator anOperator = getOperator(ExpressionOperator.Locate); 2378        Vector args = oracle.toplink.essentials.internal.helper.NonSynchronizedVector.newInstance(1); 2379        args.addElement(str); 2380        return anOperator.expressionForArguments(this, args); 2381    } 2382 2383    /** 2384     * PUBLIC: 2385     * Function, returns the position of <code>str</code> in <code>this</code>, 2386     * starting the search at <code>fromIndex</code>. 2387     * <p>Example: 2388     * <pre><blockquote> 2389     * TopLink: employee.get("firstName").locate("ob", 1) 2390     * Java: employee.getFirstName().indexOf("ob", 1) + 1 2391     * SQL: LOCATE('ob', t0.F_NAME, 1) 2392     * </pre></blockquote> 2393     * <p> 2394     * Note that while in String.locate(str) -1 is returned if not found, and the 2395     * index starting at 0 if found, in SQL it is 0 if not found, and the index 2396     * starting at 1 if found. 2397     */ 2398    public Expression locate(String str, int fromIndex) { 2399        return locate(str, new Integer (fromIndex)); 2400    } 2401 2402    /** 2403     * PUBLIC: 2404     * Function, returns the position of <code>str</code> in <code>this</code>, 2405     * starting the search at <code>fromIndex</code>. 2406     * <p>Example: 2407     * <pre><blockquote> 2408     * TopLink: employee.get("firstName").locate("ob", 1) 2409     * Java: employee.getFirstName().indexOf("ob", 1) + 1 2410     * SQL: LOCATE('ob', t0.F_NAME, 1) 2411     * </pre></blockquote> 2412     * <p> 2413     * Note that while in String.locate(str) -1 is returned if not found, and the 2414     * index starting at 0 if found, in SQL it is 0 if not found, and the index 2415     * starting at 1 if found. 2416     */ 2417    public Expression locate(Object str, Object fromIndex) { 2418        ExpressionOperator anOperator = getOperator(ExpressionOperator.Locate2); 2419        Vector args = oracle.toplink.essentials.internal.helper.NonSynchronizedVector.newInstance(2); 2420        args.addElement(str); 2421        args.addElement(fromIndex); 2422        return anOperator.expressionForArguments(this, args); 2423    } 2424 2425    /** 2426     * PUBLIC: 2427     * This represents the aggregate function Maximum. Can be used only within Report Queries. 2428     */ 2429    public Expression maximum() { 2430        return getFunction(ExpressionOperator.Maximum); 2431    } 2432 2433    /** 2434     * PUBLIC: 2435     * This represents the aggregate function Minimum. Can be used only within Report Queries. 2436     */ 2437    public Expression minimum() { 2438        return getFunction(ExpressionOperator.Minimum); 2439    } 2440 2441    /** 2442     * PUBLIC: 2443     * Function, returns the decimal number of months between the two dates. 2444     */ 2445    public Expression monthsBetween(Object otherDate) { 2446        ExpressionOperator anOperator = getOperator(ExpressionOperator.MonthsBetween); 2447        return anOperator.expressionFor(this, otherDate); 2448    } 2449 2450    /** 2451     * PUBLIC: 2452     * funcation return a date converted to a new timezone. Equivalent of the Oracle NEW_TIME function 2453     * <p>Example: 2454     * <pre><blockquote> 2455     * TopLink: employee.get("date").newTime("EST", "PST") 2456     * Java: NA 2457     * SQL: NEW_TIME(date, 'EST', 'PST') 2458     * </pre></blockquote> * 2459     */ 2460    public Expression newTime(String timeZoneFrom, String timeZoneTo) { 2461        ExpressionOperator anOperator = getOperator(ExpressionOperator.NewTime); 2462        Vector args = oracle.toplink.essentials.internal.helper.NonSynchronizedVector.newInstance(); 2463        args.addElement(timeZoneFrom); 2464        args.addElement(timeZoneTo); 2465        return anOperator.expressionForArguments(this, args); 2466    } 2467 2468    /** 2469     * PUBLIC: 2470     * Function, returns the date with the next day from the source date as the day name given. 2471     */ 2472    public Expression nextDay(Object dayName) { 2473        ExpressionOperator anOperator = getOperator(ExpressionOperator.NextDay); 2474        return anOperator.expressionFor(this, dayName); 2475    } 2476 2477    /** 2478     * PUBLIC: Returns an expression equivalent to none of <code>attributeName</code> 2479     * holding true for <code>criteria</code>. 2480     * <p> 2481     * For every expression with an anyOf, its negation has either an allOf or a 2482     * noneOf. The following two examples will illustrate as the second is the 2483     * negation of the first: 2484     * <p> 2485     * AnyOf Example: Employees with a '613' area code phone number. 2486     * <pre><blockquote> 2487     * ReadAllQuery query = new ReadAllQuery(Employee.class); 2488     * ExpressionBuilder employee = new ExpressionBuilder(); 2489     * Expression exp = employee.anyOf("phoneNumbers").get("areaCode").equal("613"); 2490     * </blockquote></pre> 2491     * <p> 2492     * NoneOf Example: Employees with no '613' area code phone numbers. 2493     * <pre><blockquote> 2494     * ExpressionBuilder employee = new ExpressionBuilder(); 2495     * ExpressionBuilder phones = new ExpressionBuilder(); 2496     * Expression exp = employee.noneOf("phoneNumbers", phones.get("areaCode").equal("613")); 2497     * SQL: 2498     * SELECT ... EMPLOYEE t0 WHERE NOT EXISTS (SELECT ... PHONE t1 WHERE 2499     * (t0.EMP_ID = t1.EMP_ID) AND (t1.AREACODE = '613')) 2500     * </blockquote></pre> 2501     * <p> 2502     * noneOf is the universal counterpart to the existential anyOf. To have the 2503     * condition evaluated for each instance it must be put inside of a subquery, 2504     * which can be expressed as not exists (any of attributeName some condition). 2505     * (All x such that !y = !Exist x such that y). 2506     * <p>Likewise the syntax employee.noneOf("phoneNumbers").get("areaCode").equal("613") 2507     * is not supported for the <code>equal</code> must go inside a subQuery. 2508     * <p> 2509     * This method saves you from writing the sub query yourself. The above is 2510     * equivalent to the following expression: 2511     * <pre><blockquote> 2512     * ExpressionBuilder employee = new ExpressionBuilder(); 2513     * ExpressionBuilder phone = new ExpressionBuilder(); 2514     * ReportQuery subQuery = new ReportQuery(Phone.class, phone); 2515     * subQuery.retreivePrimaryKeys(); 2516     * subQuery.setSelectionCriteria(phone.equal(employee.anyOf("phoneNumbers").and( 2517     * phone.get("areaCode").equal("613"))); 2518     * Expression exp = employee.notExists(subQuery); 2519     * </blockquote></pre> 2520     * @param criteria must have its own builder, as it will become the 2521     * seperate selection criteria of a subQuery. 2522     * @return a notExists subQuery expression 2523     */ 2524    public Expression noneOf(String attributeName, Expression criteria) { 2525        ReportQuery subQuery = new ReportQuery(); 2526        subQuery.setShouldRetrieveFirstPrimaryKey(true); 2527        Expression builder = criteria.getBuilder(); 2528        criteria = builder.equal(anyOf(attributeName)).and(criteria); 2529        subQuery.setSelectionCriteria(criteria); 2530        return notExists(subQuery); 2531    } 2532 2533    /** 2534     * INTERNAL: 2535     * Normalize into a structure that is printable. 2536     * Also compute printing information such as outer joins. 2537     */ 2538    public Expression normalize(ExpressionNormalizer normalizer) { 2539        //This class has no validation but we should still make the method call for consistency 2540 //bug # 2956674 2541 //validation is moved into normalize to ensure that expressions are valid before we attempt to work with them 2542 validateNode(); 2543        return this; 2544    } 2545 2546    /** 2547     * PUBLIC: 2548     * Return an expression that is the boolean logical negation of the expression. 2549     * This is equivalent to the SQL "NOT" operator and the Java "!" operator. 2550     * <p>Example: 2551     * <pre><blockquote> 2552     * TopLink: employee.get("age").equal(24).not() 2553     * Java: (! (employee.getAge() == 24)) 2554     * SQL: NOT (AGE = 24) 2555     * </blockquote></pre> 2556     */ 2557    public Expression not() { 2558        ExpressionOperator anOperator = getOperator(ExpressionOperator.Not); 2559        return anOperator.expressionFor(this); 2560    } 2561 2562    /** 2563     * PUBLIC: 2564     * Return an expression that compares if the receivers value is not between two other values. 2565     * Equivalent to between negated. 2566     * @see #between(Object, Object) 2567     */ 2568    public Expression notBetween(byte leftValue, byte rightValue) { 2569        return notBetween(new Byte (leftValue), new Byte (rightValue)); 2570    } 2571 2572    /** 2573     * PUBLIC: 2574     * Return an expression that compares if the receivers value is not between two other values. 2575     * Equivalent to between negated. 2576     * @see #between(Object, Object) 2577     */ 2578    public Expression notBetween(char leftChar, char rightChar) { 2579        return notBetween(new Character (leftChar), new Character (rightChar)); 2580    } 2581 2582    /** 2583     * PUBLIC: 2584     * Return an expression that compares if the receivers value is not between two other values. 2585     * Equivalent to between negated. 2586     * @see #between(Object, Object) 2587     */ 2588    public Expression notBetween(double leftValue, double rightValue) { 2589        return notBetween(new Double (leftValue), new Double (rightValue)); 2590    } 2591 2592    /** 2593     * PUBLIC: 2594     * Return an expression that compares if the receivers value is not between two other values. 2595     * Equivalent to between negated. 2596     * @see #between(Object, Object) 2597     */ 2598    public Expression notBetween(float leftValue, float rightValue) { 2599        return notBetween(new Float (leftValue), new Float (rightValue)); 2600    } 2601 2602    /** 2603     * PUBLIC: 2604     * Return an expression that compares if the receivers value is not between two other values. 2605     * Equivalent to between negated. 2606     * @see #between(Object, Object) 2607     */ 2608    public Expression notBetween(int leftValue, int rightValue) { 2609        return notBetween(new Integer (leftValue), new Integer (rightValue)); 2610    } 2611 2612    /** 2613     * PUBLIC: 2614     * Return an expression that compares if the receivers value is not between two other values. 2615     * Equivalent to between negated. 2616     * @see #between(Object, Object) 2617     */ 2618    public Expression notBetween(long leftValue, long rightValue) { 2619        return notBetween(new Long (leftValue), new Long (rightValue)); 2620    } 2621 2622    /** 2623     * PUBLIC: 2624     * Return an expression that compares if the receivers value is not between two other values. 2625     * Equivalent to between negated. 2626     * @see #between(Object, Object) 2627     */ 2628    public Expression notBetween(Object leftValue, Object rightValue) { 2629        return between(leftValue, rightValue).not(); 2630    } 2631 2632    /** 2633     * PUBLIC: 2634     * Return an expression that compares if the receivers value is not between two other values. 2635     * Equivalent to between negated. 2636     * @see #between(Object, Object) 2637     */ 2638    public Expression notBetween(Expression leftExpression, Expression rightExpression) { 2639        return between(leftExpression, rightExpression).not(); 2640    } 2641 2642    /** 2643     * PUBLIC: 2644     * Return an expression that compares if the receivers value is not between two other values. 2645     * Equivalent to between negated. 2646     * @see #between(Object, Object) 2647     */ 2648    public Expression notBetween(short leftValue, short rightValue) { 2649        return notBetween(new Short (leftValue), new Short (rightValue)); 2650    } 2651 2652    /** 2653     * PUBLIC: A logical expression for the collection <code>attributeName</code> 2654     * not being empty. 2655     * Equivalent to <code>size(attributeName).greaterThan(0)</code> 2656     * <p>Example: 2657     * <pre><blockquote> 2658     * TopLink: employee.notEmpty("phoneNumbers") 2659     * Java: employee.getPhoneNumbers().size() > 0 2660     * SQL: SELECT ... FROM EMP t0 WHERE ( 2661     * (SELECT COUNT(*) FROM PHONE t1 WHERE (t0.EMP_ID = t1.EMP_ID)) > 0) 2662     * </blockquote></pre> 2663     * This is a case where a fast operation in java does not translate to an 2664     * equally fast operation in SQL, requiring a correlated subselect. 2665     * @see #size(java.lang.String) 2666     */ 2667    public Expression notEmpty(String attributeName) { 2668        return size(attributeName).greaterThan(0); 2669    } 2670 2671    /** 2672     * PUBLIC: 2673     * Return an expression that compares if the receivers value is not equal to the other value. 2674     * This is equivalent to the SQL "<>" operator 2675     * 2676     * @see #equal(Object) 2677     */ 2678    public Expression notEqual(byte theValue) { 2679        return notEqual(new Byte (theValue)); 2680    } 2681 2682    /** 2683     * PUBLIC: 2684     * Return an expression that compares if the receivers value is not equal to the other value. 2685     * This is equivalent to the SQL "<>" operator 2686     * 2687     * @see #equal(Object) 2688     */ 2689    public Expression notEqual(char theChar) { 2690        return notEqual(new Character (theChar)); 2691    } 2692 2693    /** 2694     * PUBLIC: 2695     * Return an expression that compares if the receivers value is not equal to the other value. 2696     * This is equivalent to the SQL "<>" operator 2697     * 2698     * @see #equal(Object) 2699     */ 2700    public Expression notEqual(double theValue) { 2701        return notEqual(new Double (theValue)); 2702    } 2703 2704    /** 2705     * PUBLIC: 2706     * Return an expression that compares if the receivers value is not equal to the other value. 2707     * This is equivalent to the SQL "<>" operator 2708     * 2709     * @see #equal(Object) 2710     */ 2711    public Expression notEqual(float theValue) { 2712        return notEqual(new Float (theValue)); 2713    } 2714 2715    /** 2716     * PUBLIC: 2717     * Return an expression that compares if the receivers value is not equal to the other value. 2718     * This is equivalent to the SQL "<>" operator 2719     * 2720     * @see #equal(Object) 2721     */ 2722    public Expression notEqual(int theValue) { 2723        return notEqual(new Integer (theValue)); 2724    } 2725 2726    /** 2727     * PUBLIC: 2728     * Return an expression that compares if the receivers value is not equal to the other value. 2729     * This is equivalent to the SQL "<>" operator 2730     * 2731     * @see #equal(Object) 2732     */ 2733    public Expression notEqual(long theValue) { 2734        return notEqual(new Long (theValue)); 2735    } 2736 2737    /** 2738     * PUBLIC: 2739     * Return an expression that compares if the receivers value is not equal to the other value. 2740     * This is equivalent to the SQL "<>" operator 2741     * 2742     * @see #equal(Object) 2743     */ 2744    public Expression notEqual(Object theValue) { 2745        ExpressionOperator anOperator = getOperator(ExpressionOperator.NotEqual); 2746        return anOperator.expressionFor(this, theValue); 2747    } 2748 2749    /** 2750     * PUBLIC: 2751     * Return an expression that compares if the receivers value is not equal to the other value. 2752     * This is equivalent to the SQL "<>" operator 2753     * 2754     * @see #equal(Object) 2755     */ 2756    public Expression notEqual(Expression theValue) { 2757        ExpressionOperator anOperator = getOperator(ExpressionOperator.NotEqual); 2758        return anOperator.expressionFor(this, theValue); 2759    } 2760 2761    /** 2762     * PUBLIC: 2763     * Return an expression that compares if the receivers value is not equal to the other value. 2764     * This is equivalent to the SQL "<>" operator 2765     * 2766     * @see #equal(Object) 2767     */ 2768    public Expression notEqual(short theValue) { 2769        return notEqual(new Short (theValue)); 2770    } 2771 2772    /** 2773     * PUBLIC: 2774     * Return an expression that compares if the receivers value is not equal to the other value. 2775     * This is equivalent to the SQL "<>" operator 2776     * 2777     * @see #equal(Object) 2778     */ 2779    public Expression notEqual(boolean theBoolean) { 2780        return notEqual(new Boolean (theBoolean)); 2781    } 2782 2783    /** 2784     * PUBLIC: 2785     * Return a sub query expression. 2786     * A sub query using a report query to define a subselect within another queries expression or select's where clause. 2787     * The sub query (the report query) will use its own expression builder be can reference expressions from the base expression builder. 2788     * <p>Example: 2789     * <pre><blockquote> 2790     * ExpressionBuilder builder = new ExpressionBuilder(); 2791     * ReportQuery subQuery = new ReportQuery(Employee.class, new ExpressionBuilder()); 2792     * subQuery.setSelectionCriteria(subQuery.getExpressionBuilder().get("name").equal(builder.get("name"))); 2793     * builder.notExists(subQuery); 2794     * </blockquote></pre> 2795     */ 2796    public Expression notExists(ReportQuery subQuery) { 2797        ExpressionOperator anOperator = getOperator(ExpressionOperator.NotExists); 2798        return anOperator.expressionFor(subQuery(subQuery)); 2799    } 2800 2801    /** 2802     * PUBLIC: 2803     * Return an expression that checks if the receivers value is contained in the collection. 2804     * This is equivalent to the SQL "IN" operator and Java "contains" operator. 2805     */ 2806    public Expression notIn(byte[] theBytes) { 2807        Vector vector = oracle.toplink.essentials.internal.helper.NonSynchronizedVector.newInstance(); 2808 2809        for (int index = 0; index < theBytes.length; index++) { 2810            vector.addElement(new Byte (theBytes[index])); 2811        } 2812 2813        return notIn(vector); 2814    } 2815 2816    /** 2817     * PUBLIC: 2818     * Return an expression that checks if the receivers value is contained in the collection. 2819     * This is equivalent to the SQL "IN" operator and Java "contains" operator. 2820     */ 2821    public Expression notIn(char[] theChars) { 2822        Vector vector = oracle.toplink.essentials.internal.helper.NonSynchronizedVector.newInstance(); 2823 2824        for (int index = 0; index < theChars.length; index++) { 2825            vector.addElement(new Character (theChars[index])); 2826        } 2827 2828        return notIn(vector); 2829    } 2830 2831    /** 2832     * PUBLIC: 2833     * Return an expression that checks if the receivers value is contained in the collection. 2834     * This is equivalent to the SQL "IN" operator and Java "contains" operator. 2835     */ 2836    public Expression notIn(double[] theDoubles) { 2837        Vector vector = oracle.toplink.essentials.internal.helper.NonSynchronizedVector.newInstance(); 2838 2839        for (int index = 0; index < theDoubles.length; index++) { 2840            vector.addElement(new Double (theDoubles[index])); 2841        } 2842 2843        return notIn(vector); 2844    } 2845 2846    /** 2847     * PUBLIC: 2848     * Return an expression that checks if the receivers value is contained in the collection. 2849     * This is equivalent to the SQL "IN" operator and Java "contains" operator. 2850     */ 2851    public Expression notIn(float[] theFloats) { 2852        Vector vector = oracle.toplink.essentials.internal.helper.NonSynchronizedVector.newInstance(); 2853 2854        for (int index = 0; index < theFloats.length; index++) { 2855            vector.addElement(new Float (theFloats[index])); 2856        } 2857 2858        return notIn(vector); 2859    } 2860 2861    /** 2862     * PUBLIC: 2863     * Return an expression that checks if the receivers value is contained in the collection. 2864     * This is equivalent to the SQL "IN" operator and Java "contains" operator. 2865     */ 2866    public Expression notIn(int[] theInts) { 2867        Vector vector = oracle.toplink.essentials.internal.helper.NonSynchronizedVector.newInstance(); 2868 2869        for (int index = 0; index < theInts.length; index++) { 2870            vector.addElement(new Integer (theInts[index])); 2871        } 2872 2873        return notIn(vector); 2874    } 2875 2876    /** 2877     * PUBLIC: 2878     * Return an expression that checks if the receivers value is contained in the collection. 2879     * This is equivalent to the SQL "IN" operator and Java "contains" operator. 2880     */ 2881    public Expression notIn(long[] theLongs) { 2882        Vector vector = oracle.toplink.essentials.internal.helper.NonSynchronizedVector.newInstance(); 2883 2884        for (int index = 0; index < theLongs.length; index++) { 2885            vector.addElement(new Long (theLongs[index])); 2886        } 2887 2888        return notIn(vector); 2889    } 2890 2891    /** 2892     * PUBLIC: 2893     * Return an expression that checks if the receivers value is contained in the collection. 2894     * This is equivalent to the SQL "IN" operator and Java "contains" operator. 2895     */ 2896    public Expression notIn(Object [] theObjects) { 2897        Vector vector = oracle.toplink.essentials.internal.helper.NonSynchronizedVector.newInstance(); 2898 2899        for (int index = 0; index < theObjects.length; index++) { 2900            vector.addElement(theObjects[index]); 2901        } 2902 2903        return notIn(vector); 2904    } 2905 2906    public Expression notIn(ReportQuery subQuery) { 2907        return notIn(subQuery(subQuery)); 2908    } 2909 2910    /** 2911     * PUBLIC: 2912     * Return an expression that checks if the receivers value is contained in the collection. 2913     * This is equivalent to the SQL "IN" operator and Java "contains" operator. 2914     */ 2915    public Expression notIn(short[] theShorts) { 2916        Vector vector = oracle.toplink.essentials.internal.helper.NonSynchronizedVector.newInstance(); 2917 2918        for (int index = 0; index < theShorts.length; index++) { 2919            vector.addElement(new Short (theShorts[index])); 2920        } 2921 2922        return notIn(vector); 2923    } 2924 2925    /** 2926     * PUBLIC: 2927     * Return an expression that checks if the receivers value is contained in the collection. 2928     * This is equivalent to the SQL "IN" operator and Java "contains" operator. 2929     */ 2930    public Expression notIn(boolean[] theBooleans) { 2931        Vector vector = oracle.toplink.essentials.internal.helper.NonSynchronizedVector.newInstance(); 2932 2933        for (int index = 0; index < theBooleans.length; index++) { 2934            vector.addElement(new Boolean (theBooleans[index])); 2935        } 2936 2937        return notIn(vector); 2938    } 2939 2940    /** 2941     * PUBLIC: 2942     * Return an expression that checks if the receivers value is contained in the collection. 2943     * The collection can be a collection of constants or expressions. 2944     * This is equivalent to the SQL "IN" operator and Java "contains" operator. 2945     * <p>Example: 2946     * <pre><blockquote> 2947     * TopLink: employee.get("age").in(agesVector) 2948     * Java: agesVector.contains(employee.getAge()) 2949     * SQL: AGE IN (55, 18, 30) 2950     * </blockquote></pre> 2951     */ 2952    public Expression notIn(Vector theObjects) { 2953        //If none of the elements in theObjects is expression, build a ConstantExpression with theObjects. 2954 if (!detectExpression(theObjects)) { 2955            return notIn(new ConstantExpression(theObjects, this)); 2956        } 2957        //Otherwise build a collection of expressions. 2958 ExpressionOperator anOperator = getOperator(ExpressionOperator.NotIn); 2959        return anOperator.expressionForArguments(this, theObjects); 2960    } 2961 2962    public Expression notIn(Expression arguments) { 2963        ExpressionOperator anOperator = getOperator(ExpressionOperator.NotIn); 2964        return anOperator.expressionFor(this, arguments); 2965    } 2966 2967    /** 2968     * PUBLIC: 2969     * Return an expression that compares if the receivers value is not like the other value. 2970     * Equivalent to like negated. 2971     * @see #like(String) 2972     */ 2973    public Expression notLike(String aString) { 2974        return notLike(new ConstantExpression(aString, this)); 2975    } 2976 2977    /** 2978     * PUBLIC: 2979     * Return an expression that compares if the receivers value is not like the other value. 2980     * Equivalent to like negated. 2981     * @see #like(String) 2982     */ 2983    public Expression notLike(Expression arguments) { 2984        ExpressionOperator anOperator = getOperator(ExpressionOperator.NotLike); 2985        return anOperator.expressionFor(this, arguments); 2986    } 2987 2988    /** 2989     * PUBLIC: 2990     * Return an expression representing a comparison to null 2991     * <p>Example: 2992     * <pre><blockquote> 2993     * TopLink: employee.get("age").notNull() 2994     * Java: employee.getAge() != null 2995     * SQL: AGE IS NOT NULL 2996     * </blockquote></pre> 2997     */ 2998    public Expression notNull() { 2999        ExpressionOperator anOperator = getOperator(ExpressionOperator.NotNull); 3000        return anOperator.expressionFor(this); 3001    } 3002 3003    /** 3004     * PUBLIC: 3005     * Return an expression that is the boolean logical combination of both expressions. 3006     * This is equivalent to the SQL "OR" operator and the Java "||" operator. 3007     * <p>Example: 3008     * <pre><blockquote> 3009     * TopLink: employee.get("firstName").equal("Bob").OR(employee.get("lastName").equal("Smith")) 3010     * Java: (employee.getFirstName().equals("Bob")) || (employee.getLastName().equals("Smith")) 3011     * SQL: F_NAME = 'Bob' OR L_NAME = 'Smith' 3012     * </blockquote></pre> 3013     */ 3014    public Expression or(Expression theExpression) { 3015        // Allow ands with null. 3016 if (theExpression == null) { 3017            return this; 3018        } 3019 3020        ExpressionBuilder base = getBuilder(); 3021        Expression expressionToUse = theExpression; 3022 3023        // Ensure the same builder, unless a parralel query is used. 3024 if ((theExpression.getBuilder() != base) && (theExpression.getBuilder().getQueryClass() == null)) { 3025            expressionToUse = theExpression.rebuildOn(base); 3026        } 3027 3028        if (base == this) {// Allow and to be sent to the builder. 3029 return expressionToUse; 3030        } 3031 3032        ExpressionOperator anOperator = getOperator(ExpressionOperator.Or); 3033        return anOperator.expressionFor(this, expressionToUse); 3034    } 3035 3036    /** 3037     * INTERNAL: 3038     */ 3039    public Expression performOperator(ExpressionOperator anOperator, Vector args) { 3040        return anOperator.expressionForArguments(this, args); 3041    } 3042 3043    protected void postCopyIn(Dictionary alreadyDone) { 3044    } 3045 3046    /** 3047     * ADVANCED: 3048     * Inserts the SQL as is directly into the expression. 3049     * The sql will be printed immediately after (postfixed to) the sql for 3050     * <b>this</b>. 3051     */ 3052    public Expression postfixSQL(String sqlString) { 3053        ExpressionOperator anOperator = new ExpressionOperator(); 3054        anOperator.setType(ExpressionOperator.FunctionOperator); 3055        Vector v = oracle.toplink.essentials.internal.helper.NonSynchronizedVector.newInstance(1); 3056        v.addElement(sqlString); 3057        anOperator.printsAs(v); 3058        anOperator.bePostfix(); 3059        anOperator.setNodeClass(ClassConstants.FunctionExpression_Class); 3060 3061        return anOperator.expressionFor(this); 3062    } 3063 3064    /** 3065     * ADVANCED: 3066     * Insert the SQL as is directly into the expression. 3067     * The sql will be printed immediately before (prefixed to) the sql for 3068     * <b>this</b>. 3069     */ 3070    public Expression prefixSQL(String sqlString) { 3071        ExpressionOperator anOperator = new ExpressionOperator(); 3072        anOperator.setType(ExpressionOperator.FunctionOperator); 3073        Vector v = oracle.toplink.essentials.internal.helper.NonSynchronizedVector.newInstance(1); 3074        v.addElement(sqlString); 3075        anOperator.printsAs(v); 3076        anOperator.bePrefix(); 3077        anOperator.setNodeClass(ClassConstants.FunctionExpression_Class); 3078 3079        return anOperator.expressionFor(this); 3080    } 3081 3082    /** 3083     * INTERNAL: 3084     * Print SQL 3085     */ 3086    public abstract void printSQL(ExpressionSQLPrinter printer); 3087 3088    /** 3089     * INTERNAL: 3090     * Print java for project class generation 3091     */ 3092    public void printJava(ExpressionJavaPrinter printer) { 3093        //do nothing 3094 } 3095 3096    /** 3097     * INTERNAL: 3098     * Print SQL, this is called from functions, so must not be converted through the mapping. 3099     */ 3100    public void printSQLWithoutConversion(ExpressionSQLPrinter printer) { 3101        printSQL(printer); 3102    } 3103 3104    /** 3105     * INTERNAL: 3106     * This expression is built on a different base than the one we want. Rebuild it and 3107     * return the root of the new tree 3108     * If receiver is a complex expression, use cloneUsing(newBase) instead. 3109     * @see #cloneUsing(Expression newBase) 3110     */ 3111    public abstract Expression rebuildOn(Expression newBase); 3112 3113    /** 3114     * ADVANCED: 3115     * For Object-relational support. 3116     */ 3117    public Expression ref() { 3118        return getFunction(ExpressionOperator.Ref); 3119    } 3120 3121    protected Expression registerIn(Dictionary alreadyDone) { 3122        Expression copy = (Expression)shallowClone(); 3123        alreadyDone.put(this, copy); 3124        copy.postCopyIn(alreadyDone); 3125        return copy; 3126 3127    } 3128 3129    /** 3130     * PUBLIC: 3131     * Function, returns the string with occurances of the first substring replaced with the second substring. 3132     */ 3133    public Expression replace(Object stringToReplace, Object stringToReplaceWith) { 3134        ExpressionOperator anOperator = getOperator(ExpressionOperator.Replace); 3135        Vector args = oracle.toplink.essentials.internal.helper.NonSynchronizedVector.newInstance(2); 3136        args.addElement(stringToReplace); 3137        args.addElement(stringToReplaceWith); 3138        return anOperator.expressionForArguments(this, args); 3139    } 3140 3141    /** 3142     * PUBLIC: 3143     * return the result of this query repeated a given number of times. 3144     * Equivalent of the Sybase REPLICATE function 3145     * <p>Example: 3146     * <pre><blockquote> 3147     * TopLink: employee.get("name").replicate(2) 3148     * Java: NA 3149     * SQL: REPLICATE(name, 2) 3150     * </pre></blockquote> 3151     */ 3152    public Expression replicate(int constant) { 3153        return replicate(new Integer (constant)); 3154    } 3155 3156    /** 3157     * PUBLIC: 3158     * return the result of this query repeated a given number of times. 3159     * Equivalent of the Sybase REPLICATE function 3160     * <p>Example: 3161     * <pre><blockquote> 3162     * TopLink: employee.get("name").replicate(2) 3163     * Java: NA 3164     * SQL: REPLICATE(name, 2) 3165     * </pre></blockquote> 3166     */ 3167    public Expression replicate(Object theValue) { 3168        ExpressionOperator anOperator = getOperator(ExpressionOperator.Replicate); 3169        return anOperator.expressionFor(this, theValue); 3170    } 3171 3172    /** 3173     * Reset cached information here so that we can be sure we're accurate. 3174     */ 3175    protected void resetCache() { 3176    } 3177 3178    /** 3179     * PUBLIC: 3180     * Function return the reverse of the query result. Equivalent of the 3181     * Sybase REVERSE function 3182     * <p>Example: 3183     * <pre><blockquote> 3184     * TopLink: employee.get("name").reverse() 3185     * Java: NA 3186     * SQL: REVERSE(name) 3187     * </pre></blockquote> 3188     */ 3189    public Expression reverse() { 3190        return getFunction(ExpressionOperator.Reverse); 3191    } 3192 3193    /** 3194     * PUBLIC: 3195     * Function return a given number of characters starting at the 3196     * right of a string. Equivalent to the Sybase RIGHT function 3197     * <p>Example: 3198     * <pre><blockquote> 3199     * TopLink: employee.get("name").right(2) 3200     * Java: NA 3201     * SQL: RIGHT(name, 2) 3202     * </pre></blockquote> 3203     */ 3204    public Expression right(int characters) { 3205        return right(new Integer (characters)); 3206    } 3207 3208    /** 3209     * PUBLIC: 3210     * Function return a given number of characters starting at the 3211     * right of a string. Equivalent to the Sybase RIGHT function 3212     * <p>Example: 3213     * <pre><blockquote> 3214     * TopLink: employee.get("name").right(2) 3215     * Java: NA 3216     * SQL: RIGHT(name, 2) 3217     * </pre></blockquote> 3218     */ 3219    public Expression right(Object characters) { 3220        ExpressionOperator anOperator = getOperator(ExpressionOperator.Right); 3221        return anOperator.expressionFor(this, characters); 3222    } 3223 3224    /** 3225     * PUBLIC: 3226     * Function, returns the string padded with the substring to the size. 3227     */ 3228    public Expression rightPad(int size, Object substring) { 3229        return rightPad(new Integer (size), substring); 3230    } 3231 3232    /** 3233     * PUBLIC: 3234     * Function, returns the string padded with the substring to the size. 3235     */ 3236    public Expression rightPad(Object size, Object substring) { 3237        ExpressionOperator anOperator = getOperator(ExpressionOperator.RightPad); 3238        Vector args = oracle.toplink.essentials.internal.helper.NonSynchronizedVector.newInstance(2); 3239        args.addElement(size); 3240        args.addElement(substring); 3241        return anOperator.expressionForArguments(this, args); 3242    } 3243 3244    /** 3245     * PUBLIC: 3246     * Function, returns the string right trimmed for white space. 3247     */ 3248    public Expression rightTrim() { 3249        ExpressionOperator anOperator = getOperator(ExpressionOperator.RightTrim); 3250        return anOperator.expressionFor(this); 3251    } 3252 3253    /** 3254     * PUBLIC: 3255     * Function, returns the string with the substring trimed from the right. 3256     */ 3257    public Expression rightTrim(Object substring) { 3258        ExpressionOperator anOperator = getOperator(ExpressionOperator.RightTrim2); 3259        return anOperator.expressionFor(this, substring); 3260    } 3261 3262    /** 3263     * PUBLIC: 3264     * Function, returns the date rounded to the year, month or day. 3265     */ 3266    public Expression roundDate(Object yearOrMonthOrDayRoundToken) { 3267        ExpressionOperator anOperator = getOperator(ExpressionOperator.RoundDate); 3268        return anOperator.expressionFor(this, yearOrMonthOrDayRoundToken); 3269    } 3270 3271    /** 3272     * PUBLIC: 3273     * Return whether this expression should be included in the SELECT clause if it is used 3274     * in an ORDER BY clause 3275     */ 3276    public boolean selectIfOrderedBy() { 3277        return selectIfOrderedBy; 3278    } 3279 3280    /** 3281     * INTERNAL: 3282     * Set the local base expression, ie the one on the other side of the operator 3283     * Most types will ignore this, since they don't need it. 3284     */ 3285    public void setLocalBase(Expression exp) { 3286    } 3287 3288    /** 3289     * PUBLIC: 3290     * Set whether this expression should be included in the SELECT clause of a query 3291     * that uses it in the ORDER BY clause. 3292     * 3293     * @param selectIfOrderedBy 3294     */ 3295    public void setSelectIfOrderedBy(boolean selectIfOrderedBy) { 3296        this.selectIfOrderedBy = selectIfOrderedBy; 3297    } 3298 3299    /** 3300     * INTERNAL: 3301     */ 3302    public Expression shallowClone() { 3303        Expression result = null; 3304        try { 3305            result = (Expression)super.clone(); 3306        } catch (CloneNotSupportedException e) { 3307        } 3308        ; 3309        return result; 3310    } 3311 3312    /** 3313     * PUBLIC: A logical expression for the size of collection <code>attributeName</code>. 3314     * <p>Example: 3315     * <pre><blockquote> 3316     * TopLink: employee.size("phoneNumbers") 3317     * Java: employee.getPhoneNumbers().size() 3318     * SQL: SELECT ... FROM EMP t0 WHERE ... 3319     * (SELECT COUNT(*) FROM PHONE t1 WHERE (t0.EMP_ID = t1.EMP_ID)) 3320     * </blockquote></pre> 3321     * This is a case where a fast operation in java does not translate to an 3322     * equally fast operation in SQL, requiring a correlated subselect. 3323     */ 3324    public Expression size(String attributeName) { 3325        // Create an anoymous subquery that will get its reference class 3326 // set during SubSelectExpression.normalize. 3327 ReportQuery subQuery = new ReportQuery(); 3328        subQuery.addCount(); 3329        subQuery.setSelectionCriteria(subQuery.getExpressionBuilder().equal(this.anyOf(attributeName))); 3330        return subQuery(subQuery); 3331    } 3332 3333    /** 3334     * PUBLIC: 3335     * This represents the aggregate function StandardDeviation. Can be used only within Report Queries. 3336     */ 3337    public Expression standardDeviation() { 3338        return getFunction(ExpressionOperator.StandardDeviation); 3339    } 3340 3341    /** 3342     * PUBLIC: 3343     * Return a sub query expression. 3344     * A sub query using a report query to define a subselect within another queries expression or select's where clause. 3345     * The sub query (the report query) will use its own expression builder be can reference expressions from the base expression builder. 3346     * <p>Example: 3347     * <pre><blockquote> 3348     * ExpressionBuilder builder = new ExpressionBuilder(); 3349     * ReportQuery subQuery = new ReportQuery(Employee.class, new ExpressionBuilder()); 3350     * subQuery.addMaximum("salary"); 3351     * builder.get("salary").equal(builder.subQuery(subQuery)); 3352     * </blockquote></pre> 3353     */ 3354    public Expression subQuery(ReportQuery subQuery) { 3355        return new SubSelectExpression(subQuery, this); 3356    } 3357 3358    /** 3359     * PUBLIC: 3360     * Function, returns the substring from the souce string. 3361     */ 3362    public Expression substring(int startPosition, int size) { 3363        return substring(new Integer (startPosition), new Integer (size)); 3364    } 3365 3366    /** 3367     * PUBLIC: 3368     * Function, returns the substring from the souce string. 3369     */ 3370    public Expression substring(Object startPosition, Object size) { 3371        ExpressionOperator anOperator = getOperator(ExpressionOperator.Substring); 3372        Vector args = oracle.toplink.essentials.internal.helper.NonSynchronizedVector.newInstance(2); 3373        args.addElement(startPosition); 3374        args.addElement(size); 3375        return anOperator.expressionForArguments(this, args); 3376    } 3377 3378    /** 3379     * PUBLIC: 3380     * This represents the aggregate function Sum. Can be used only within Report Queries. 3381     */ 3382    public Expression sum() { 3383        return getFunction(ExpressionOperator.Sum); 3384    } 3385 3386    /** 3387     * PUBLIC: 3388     * Function, returns the single character string with the ascii or character set value. 3389     */ 3390    public Expression toCharacter() { 3391        ExpressionOperator anOperator = getOperator(ExpressionOperator.Chr); 3392        return anOperator.expressionFor(this); 3393    } 3394 3395    /** 3396     * PUBLIC: 3397     * Function, returns date from the string using the default format. 3398     */ 3399    public Expression toDate() { 3400        ExpressionOperator anOperator = getOperator(ExpressionOperator.ToDate); 3401        return anOperator.expressionFor(this); 3402    } 3403 3404    /** 3405     * PUBLIC: 3406     * Return an expression that represents the receiver value converted to a character string. 3407     * This is equivalent to the SQL "TO_CHAR" operator and Java "toString" method. 3408     * <p>Example: 3409     * <pre><blockquote> 3410     * TopLink: employee.get("salary").toChar().equal("100000") 3411     * Java: employee.getSalary().toString().equals("100000") 3412     * SQL: TO_CHAR(SALARY) = '100000' 3413     * </blockquote></pre> 3414     */ 3415    public Expression toChar() { 3416        ExpressionOperator anOperator = getOperator(ExpressionOperator.ToChar); 3417        return anOperator.expressionFor(this); 3418    } 3419 3420    /** 3421     * PUBLIC: 3422     * Return an expression that represents the receiver value converted to a character string, 3423     * with the database formating options (i.e. 'year', 'yyyy', 'day', etc.). 3424     * This is equivalent to the SQL "TO_CHAR" operator and Java Date API. 3425     * <p>Example: 3426     * <pre><blockquote> 3427     * TopLink: employee.get("startDate").toChar("day").equal("monday") 3428     * Java: employee.getStartDate().getDay().equals("monday") 3429     * SQL: TO_CHAR(START_DATE, 'day') = 'monday' 3430     * </blockquote></pre> 3431     */ 3432    public Expression toChar(String format) { 3433        ExpressionOperator anOperator = getOperator(ExpressionOperator.ToCharWithFormat); 3434        return anOperator.expressionFor(this, format); 3435    } 3436 3437    /** 3438     * PUBLIC: 3439     * Return an expression that represents the receiver value converted to lower case. 3440     * This is equivalent to the SQL "LOWER" operator and Java "toLowerCase" method. 3441     * This is only allowed for String attribute values. 3442     * <p>Example: 3443     * <pre><blockquote> 3444     * TopLink: employee.get("firstName").toLowerCase().equal("bob") 3445     * Java: employee.getFirstName().toLowerCase().equals("bob") 3446     * SQL: LOWER(F_NAME) = 'bob' 3447     * </blockquote></pre> 3448     */ 3449    public Expression toLowerCase() { 3450        ExpressionOperator anOperator = getOperator(ExpressionOperator.ToLowerCase); 3451        return anOperator.expressionFor(this); 3452    } 3453 3454    /** 3455     * PUBLIC: 3456     * Function, returns the number converted from the string. 3457     */ 3458    public Expression toNumber() { 3459        ExpressionOperator anOperator = getOperator(ExpressionOperator.ToNumber); 3460        return anOperator.expressionFor(this); 3461    } 3462 3463    /** 3464     * PUBLIC: 3465     * Print a debug form of the expression tree. 3466     */ 3467    public String toString() { 3468        try { 3469            StringWriter innerWriter = new StringWriter(); 3470            BufferedWriter outerWriter = new BufferedWriter(innerWriter); 3471            toString(outerWriter, 0); 3472            outerWriter.flush(); 3473            return innerWriter.toString(); 3474        } catch (IOException e) { 3475            return ToStringLocalization.buildMessage("error_printing_expression", (Object [])null); 3476        } 3477    } 3478 3479    /** 3480     * INTERNAL: 3481     * Print a debug form of the expression tree. 3482     */ 3483    public void toString(BufferedWriter writer, int indent) throws IOException { 3484        writer.newLine(); 3485        for (int i = 0; i < indent; i++) { 3486            writer.write(" "); 3487        } 3488        writer.write(descriptionOfNodeType()); 3489        writer.write(" "); 3490        writeDescriptionOn(writer); 3491        writeSubexpressionsTo(writer, indent + 1); 3492    } 3493 3494    /** 3495     * PUBLIC: 3496     * Return an expression that represents the receiver value converted to upper case. 3497     * This is equivalent to the SQL "UPPER" operator and Java "toUpperCase" method. 3498     * This is only allowed for String attribute values. 3499     * <p>Example: 3500     * <pre><blockquote> 3501     * TopLink: employee.get("firstName").toUpperCase().equal("BOB") 3502     * Java: employee.getFirstName().toUpperCase().equals("BOB") 3503     * SQL: UPPER(F_NAME) = 'BOB' 3504     * </blockquote></pre> 3505     */ 3506    public Expression toUpperCase() { 3507        ExpressionOperator anOperator = getOperator(ExpressionOperator.ToUpperCase); 3508        return anOperator.expressionFor(this); 3509    } 3510 3511    /** 3512     * PUBLIC: 3513     * Function, returns the string with the first letter of each word capitalized. 3514     */ 3515    public Expression toUppercaseCasedWords() { 3516        ExpressionOperator anOperator = getOperator(ExpressionOperator.Initcap); 3517        return anOperator.expressionFor(this); 3518    } 3519 3520    /** 3521     * PUBLIC: 3522     * Function, returns the string with each char from the from string converted to the char in the to string. 3523     */ 3524    public Expression translate(Object fromString, Object toString) { 3525        ExpressionOperator anOperator = getOperator(ExpressionOperator.Translate); 3526        Vector args = oracle.toplink.essentials.internal.helper.NonSynchronizedVector.newInstance(2); 3527        args.addElement(fromString); 3528        args.addElement(toString); 3529        return anOperator.expressionForArguments(this, args); 3530    } 3531 3532    /** 3533     * PUBLIC: 3534     * Function, returns the string trimmed for white space. 3535     */ 3536    public Expression trim() { 3537        ExpressionOperator anOperator = getOperator(ExpressionOperator.Trim); 3538        return anOperator.expressionFor(this); 3539    } 3540     3541    /** 3542     * PUBLIC: 3543     * Function, returns the string right and left trimmed for the substring. 3544     */ 3545    public Expression trim(Object substring) { 3546        ExpressionOperator anOperator = getOperator(ExpressionOperator.Trim2); 3547        return anOperator.expressionForWithBaseLast(this, substring); 3548    } 3549 3550    /** 3551     * PUBLIC: 3552     * XMLType Function, extracts a secton of XML from a larget XML document 3553     * @param String - xpath representing the node to be returned 3554     */ 3555    public Expression extract(String path) { 3556        ExpressionOperator anOperator = getOperator(ExpressionOperator.Extract); 3557        return anOperator.expressionFor(this, path); 3558    } 3559 3560    /** 3561     * PUBLIC: 3562     * XMLType Function, extracts a value from an XMLType field 3563     * @param String - xpath expression 3564     */ 3565    public Expression extractValue(String path) { 3566        ExpressionOperator anOperator = getOperator(ExpressionOperator.ExtractValue); 3567        return anOperator.expressionFor(this, path); 3568    } 3569 3570    /** 3571     * PUBLIC: 3572     * XMLType Function, gets the number of nodes returned by the given xpath expression 3573     * returns 0 if there are none 3574     * @param - Xpath expression 3575     */ 3576    public Expression existsNode(String path) { 3577        ExpressionOperator anOperator = getOperator(ExpressionOperator.ExistsNode); 3578        return anOperator.expressionFor(this, path); 3579    } 3580 3581    /** 3582     * PUBLIC: 3583     * XMLType Function - evaluates to 0 if the xml is a well formed document and 1 if the document 3584     * is a fragment 3585     */ 3586    public Expression isFragment() { 3587        ExpressionOperator anOperator = getOperator(ExpressionOperator.IsFragment); 3588        return anOperator.expressionFor(this); 3589    } 3590 3591    /** 3592     * PUBLIC: 3593     * XMLType Function - gets a string value from an XMLType 3594     */ 3595    public Expression getStringVal() { 3596        ExpressionOperator anOperator = getOperator(ExpressionOperator.GetStringVal); 3597        return anOperator.expressionFor(this); 3598    } 3599 3600    /** 3601     * PUBLIC: 3602     * XMLType Function - gets a number value from an XMLType 3603     */ 3604    public Expression getNumberVal() { 3605        ExpressionOperator anOperator = getOperator(ExpressionOperator.GetNumberVal); 3606        return anOperator.expressionFor(this); 3607    } 3608 3609    /** 3610     * PUBLIC: 3611     * return the date truncated to the indicated datePart. Equivalent 3612     * to the Sybase TRUNC function for dates 3613     * <p>Example: 3614     * <pre><blockquote> 3615     * TopLink: employee.get("date").truncDate(year) 3616     * Java: NA 3617     * SQL: TRUNC(date, year) 3618     * </pre></blockquote> */ 3619    public Expression truncateDate(String datePart) { 3620        ExpressionOperator anOperator = getOperator(ExpressionOperator.TruncateDate); 3621        return anOperator.expressionFor(this, datePart); 3622 3623    } 3624 3625    /** 3626     * INTERNAL: 3627     * We are given an expression that comes from a different context than the one in which this was built, 3628     * e.g. it is the selection criteria of a mapping, or the criteria on which multiple tables are joined in a descriptor. 3629     * We need to transform it so it refers to the objects we are dealing with, and AND it into the rest of our expression. 3630     * 3631     * We want to replace the original base expression with <newBase>, and any parameters will be given values based 3632     * on the context which <this> provides. 3633     * 3634     * For example, suppose that the main expression is 3635     * emp.address.streetName = 'something' 3636     * and we are trying to twist the selection criteria for the mapping 'address' in Employee. Because that mapping 3637     * selects addresses, we will use the 'address' node as the base. Values for any parameters will come from the 'emp' node, 3638     * which was the base of the original expression. Note that the values need not be constants, they can be fields. 3639     * 3640     * We do this by taking the tree we're trying to merge and traverse it more or less re-executing it 3641     * it with the appropriate initial receiver and context. 3642     * Return the root of the new expression tree. This will probably need to be AND'ed with the root of the old tree. 3643     */ 3644    public Expression twist(Expression expression, Expression newBase) { 3645        if (expression == null) { 3646            return null; 3647        } 3648        return expression.twistedForBaseAndContext(newBase, this); 3649 3650    } 3651 3652    /** 3653     * INTERNAL: 3654     * Rebuild myself against the base, with the values of parameters supplied by the context 3655     * expression. This is used for transforming a standalone expression (e.g. the join criteria of a mapping) 3656     * into part of some larger expression. You normally would not call this directly, instead calling twist 3657     * See the comment there for more details" 3658     */ 3659    public Expression twistedForBaseAndContext(Expression newBase, Expression context) { 3660        // Will be overridden by subclasses 3661 return this; 3662    } 3663 3664    /** 3665     * INTERNAL: 3666     * Do any required validation for this node. Throw an exception for any incorrect constructs. 3667     */ 3668    public void validateNode() { 3669    } 3670 3671    /** 3672     * PUBLIC: 3673     * Function, this represents the value function, used in nestedtable 3674     */ 3675    public Expression value() { 3676        ExpressionOperator anOperator = getOperator(ExpressionOperator.Value); 3677        return anOperator.expressionFor(this); 3678    } 3679 3680    /** 3681     * PUBLIC: 3682     * Return an expression on the constant. 3683     * <p>Example: 3684     * <pre><blockquote> 3685     * reportQuery.addItem("a constant", builder.value("a constant")); 3686     * </blockquote></pre> 3687     */ 3688    public Expression value(byte constant) { 3689        return value(new Byte (constant)); 3690    } 3691 3692    /** 3693     * PUBLIC: 3694     * Return an expression on the constant. 3695     * <p>Example: 3696     * <pre><blockquote> 3697     * reportQuery.addItem("a constant", builder.value("a constant")); 3698     * </blockquote></pre> 3699     */ 3700    public Expression value(char constant) { 3701        return value(new Character (constant)); 3702    } 3703 3704    /** 3705     * PUBLIC: 3706     * Return an expression on the constant. 3707     * <p>Example: 3708     * <pre><blockquote> 3709     * reportQuery.addItem("a constant", builder.value("a constant")); 3710     * </blockquote></pre> 3711     */ 3712    public Expression value(double constant) { 3713        return value(new Double (constant)); 3714    } 3715 3716    /** 3717     * PUBLIC: 3718     * Return an expression on the constant. 3719     * <p>Example: 3720     * <pre><blockquote> 3721     * reportQuery.addItem("a constant", builder.value("a constant")); 3722     * </blockquote></pre> 3723     */ 3724    public Expression value(float constant) { 3725        return value(new Float (constant)); 3726    } 3727 3728    /** 3729     * PUBLIC: 3730     * Return an expression on the constant. 3731     * <p>Example: 3732     * <pre><blockquote> 3733     * reportQuery.addItem("a constant", builder.value("a constant")); 3734     * </blockquote></pre> 3735     */ 3736    public Expression value(int constant) { 3737        return value(new Integer (constant)); 3738    } 3739 3740    /** 3741     * PUBLIC: 3742     * Return an expression on the constant. 3743     * <p>Example: 3744     * <pre><blockquote> 3745     * reportQuery.addItem("a constant", builder.value("a constant")); 3746     * </blockquote></pre> 3747     */ 3748    public Expression value(long constant) { 3749        return value(new Long (constant)); 3750    } 3751 3752    /** 3753     * PUBLIC: 3754     * Return an expression on the constant. 3755     * <p>Example: 3756     * <pre><blockquote> 3757     * reportQuery.addItem("a constant", builder.value("a constant")); 3758     * </blockquote></pre> 3759     */ 3760    public Expression value(Object constant) { 3761        return new ConstantExpression(constant, this); 3762    } 3763 3764    /** 3765     * PUBLIC: 3766     * Return an expression on the constant. 3767     * <p>Example: 3768     * <pre><blockquote> 3769     * reportQuery.addItem("a constant", builder.value("a constant")); 3770     * </blockquote></pre> 3771     */ 3772    public Expression value(short constant) { 3773        return value(new Short (constant)); 3774    } 3775 3776    /** 3777     * PUBLIC: 3778     * Return an expression on the constant. 3779     * <p>Example: 3780     * <pre><blockquote> 3781     * reportQuery.addItem("a constant", builder.value("a constant")); 3782     * </blockquote></pre> 3783     */ 3784    public Expression value(boolean constant) { 3785        return value(new Boolean (constant)); 3786    } 3787 3788    /** 3789     * ADVANCED: 3790     * Return an expression on the literal. 3791     * A literal is a specific SQL syntax string that will be printed as is without quotes in the SQL. 3792     * It can be useful for printing database key words or global variables. 3793     * <p>Example: 3794     * <pre><blockquote> 3795     * reportQuery.addItem("currentTime", builder.literal("SYSDATE")); 3796     * </blockquote></pre> 3797     */ 3798    public Expression literal(String literal) { 3799        return new LiteralExpression(literal, this); 3800    } 3801 3802    /** 3803     * INTERNAL: 3804     * Return the value for in memory comparison. 3805     * This is only valid for valueable expressions. 3806     * New parameter added for feature 2612601 3807     * @param isObjectRegistered true if object possibly not a clone, but is being 3808     * conformed against the unit of work cache. 3809     */ 3810    public Object valueFromObject(Object object, AbstractSession session, AbstractRecord translationRow, InMemoryQueryIndirectionPolicy valueHolderPolicy, boolean isObjectUnregistered) { 3811        throw QueryException.cannotConformExpression(); 3812    } 3813 3814    /** 3815     * INTERNAL: 3816     * Return the value for in memory comparison. 3817     * This is only valid for valueable expressions. 3818     */ 3819    public Object valueFromObject(Object object, AbstractSession session, AbstractRecord translationRow, InMemoryQueryIndirectionPolicy valueHolderPolicy) { 3820        return valueFromObject(object, session, translationRow, valueHolderPolicy, false); 3821    } 3822 3823    /** 3824     * PUBLIC: 3825     * Function, this represents the aggregate function Variance. Can be used only within Report Queries. 3826     */ 3827    public Expression variance() { 3828        return getFunction(ExpressionOperator.Variance); 3829    } 3830 3831    /** 3832     * INTERNAL: 3833     * Used to print a debug form of the expression tree. 3834     */ 3835    public void writeDescriptionOn(BufferedWriter writer) throws IOException { 3836        writer.write("some expression"); 3837    } 3838 3839    /** 3840     * INTERNAL: 3841     * Append the field name to the writer. Should be overriden for special operators such as functions. 3842     */ 3843    protected void writeField(ExpressionSQLPrinter printer, DatabaseField field, SQLSelectStatement statement) { 3844        //print ", " before each selected field except the first one 3845 if (printer.isFirstElementPrinted()) { 3846            printer.printString(", "); 3847        } else { 3848            printer.setIsFirstElementPrinted(true); 3849        } 3850 3851        if (statement.requiresAliases()) { 3852            if (field.getTable() != lastTable) { 3853                lastTable = field.getTable(); 3854                currentAlias = aliasForTable(lastTable); 3855            } 3856            printer.printString(currentAlias.getQualifiedName()); 3857            printer.printString("."); 3858            printer.printString(field.getName()); 3859        } else { 3860            printer.printString(field.getName()); 3861        } 3862    } 3863 3864    /** 3865     * INTERNAL: 3866     * called from SQLSelectStatement.writeFieldsFromExpression(...) 3867     */ 3868    public void writeFields(ExpressionSQLPrinter printer, Vector newFields, SQLSelectStatement statement) { 3869        for (Enumeration fieldsEnum = getFields().elements(); fieldsEnum.hasMoreElements();) { 3870            DatabaseField field = (DatabaseField)fieldsEnum.nextElement(); 3871            newFields.addElement(field); 3872            writeField(printer, field, statement); 3873        } 3874    } 3875 3876    /** 3877     * INTERNAL: 3878     * Used in SQL printing. 3879     */ 3880    public void writeSubexpressionsTo(BufferedWriter writer, int indent) throws IOException { 3881        // In general, there are no sub-expressions 3882 } 3883 3884    /** 3885     * 3886     * PUBLIC: 3887     * Return an expression that is used with a comparison expression. 3888     * The ANY keyword denotes that the search condition is TRUE if the comparison is TRUE 3889     * for at least one of the values that is returned. If the subquery returns no value, 3890     * the search condition is FALSE 3891     */ 3892    public Expression any(byte[] theBytes) { 3893        Vector vector = oracle.toplink.essentials.internal.helper.NonSynchronizedVector.newInstance(); 3894 3895        for (int index = 0; index < theBytes.length; index++) { 3896            vector.addElement(new Byte (theBytes[index])); 3897        } 3898 3899        return any(vector); 3900    } 3901 3902    /** 3903     * PUBLIC: 3904     * Return an expression that checks if the receivers value is contained in the collection. 3905     * This is equivalent to the SQL "IN" operator and Java "contains" operator. 3906     */ 3907    public Expression any(char[] theChars) { 3908        Vector vector = oracle.toplink.essentials.internal.helper.NonSynchronizedVector.newInstance(); 3909 3910        for (int index = 0; index < theChars.length; index++) { 3911            vector.addElement(new Character (theChars[index])); 3912        } 3913 3914        return any(vector); 3915    } 3916 3917    /** 3918     * PUBLIC: 3919     * Return an expression that checks if the receivers value is contained in the collection. 3920     * This is equivalent to the SQL "IN" operator and Java "contains" operator. 3921     */ 3922    public Expression any(double[] theDoubles) { 3923        Vector vector = oracle.toplink.essentials.internal.helper.NonSynchronizedVector.newInstance(); 3924 3925        for (int index = 0; index < theDoubles.length; index++) { 3926            vector.addElement(new Double (theDoubles[index])); 3927        } 3928 3929        return any(vector); 3930    } 3931 3932    /** 3933     * PUBLIC: 3934     * Return an expression that checks if the receivers value is contained in the collection. 3935     * This is equivalent to the SQL "IN" operator and Java "contains" operator. 3936     */ 3937    public Expression any(float[] theFloats) { 3938        Vector vector = oracle.toplink.essentials.internal.helper.NonSynchronizedVector.newInstance(); 3939 3940        for (int index = 0; index < theFloats.length; index++) { 3941            vector.addElement(new Float (theFloats[index])); 3942        } 3943 3944        return any(vector); 3945    } 3946 3947    /** 3948     * PUBLIC: 3949     * Return an expression that checks if the receivers value is contained in the collection. 3950     * This is equivalent to the SQL "IN" operator and Java "contains" operator. 3951     */ 3952    public Expression any(int[] theInts) { 3953        Vector vector = oracle.toplink.essentials.internal.helper.NonSynchronizedVector.newInstance(); 3954 3955        for (int index = 0; index < theInts.length; index++) { 3956            vector.addElement(new Integer (theInts[index])); 3957        } 3958 3959        return any(vector); 3960    } 3961 3962    /** 3963     * PUBLIC: 3964     * Return an expression that checks if the receivers value is contained in the collection. 3965     * This is equivalent to the SQL "IN" operator and Java "contains" operator. 3966     */ 3967    public Expression any(long[] theLongs) { 3968        Vector vector = oracle.toplink.essentials.internal.helper.NonSynchronizedVector.newInstance(); 3969 3970        for (int index = 0; index < theLongs.length; index++) { 3971            vector.addElement(new Long (theLongs[index])); 3972        } 3973 3974        return any(vector); 3975    } 3976 3977    /** 3978     * PUBLIC: 3979     * Return an expression that checks if the receivers value is contained in the collection. 3980     * This is equivalent to the SQL "IN" operator and Java "contains" operator. 3981     */ 3982    public Expression any(Object [] theObjects) { 3983        Vector vector = oracle.toplink.essentials.internal.helper.NonSynchronizedVector.newInstance(); 3984 3985        for (int index = 0; index < theObjects.length; index++) { 3986            vector.addElement(theObjects[index]); 3987        } 3988 3989        return any(vector); 3990    } 3991 3992    /** 3993     * PUBLIC: 3994     * Return an expression that checks if the receivers value is contained in the collection. 3995     * This is equivalent to the SQL "IN" operator and Java "contains" operator. 3996     */ 3997    public Expression any(short[] theShorts) { 3998        Vector vector = oracle.toplink.essentials.internal.helper.NonSynchronizedVector.newInstance(); 3999 4000        for (int index = 0; index < theShorts.length; index++) { 4001            vector.addElement(new Short (theShorts[index])); 4002        } 4003 4004        return any(vector); 4005    } 4006 4007    /** 4008     * PUBLIC: 4009     * Return an expression that checks if the receivers value is contained in the collection. 4010     * This is equivalent to the SQL "IN" operator and Java "contains" operator. 4011     */ 4012    public Expression any(boolean[] theBooleans) { 4013        Vector vector = oracle.toplink.essentials.internal.helper.NonSynchronizedVector.newInstance(); 4014 4015        for (int index = 0; index < theBooleans.length; index++) { 4016            vector.addElement(new Boolean (theBooleans[index])); 4017        } 4018 4019        return any(vector); 4020    } 4021 4022    /** 4023     * PUBLIC: 4024     * Return an expression that checks if the receivers value is contained in the collection. 4025     * This is equivalent to the SQL "IN" operator and Java "contains" operator. 4026     * <p>Example: 4027     * <pre><blockquote> 4028     * TopLink: employee.get("age").in(agesVector) 4029     * Java: agesVector.contains(employee.getAge()) 4030     * SQL: AGE IN (55, 18, 30) 4031     * </blockquote></pre> 4032     */ 4033    public Expression any(Vector theObjects) { 4034        return any(new ConstantExpression(theObjects, this)); 4035    } 4036 4037    public Expression any(Expression arguments) { 4038        ExpressionOperator anOperator = getOperator(ExpressionOperator.Any); 4039        return anOperator.expressionFor(this, arguments); 4040    } 4041 4042    public Expression any(ReportQuery subQuery) { 4043        return any(subQuery(subQuery)); 4044    } 4045 4046    /** 4047     * 4048     * PUBLIC: 4049     * Return an expression that is used with a comparison expression. 4050     * The SOME keyword denotes that the search condition is TRUE if the comparison is TRUE 4051     * for at least one of the values that is returned. If the subquery returns no value, 4052     * the search condition is FALSE 4053     */ 4054    public Expression some(byte[] theBytes) { 4055        Vector vector = oracle.toplink.essentials.internal.helper.NonSynchronizedVector.newInstance(); 4056 4057        for (int index = 0; index < theBytes.length; index++) { 4058            vector.addElement(new Byte (theBytes[index])); 4059        } 4060 4061        return some(vector); 4062    } 4063 4064    /** 4065     * PUBLIC: 4066     * Return an expression that checks if the receivers value is contained in the collection. 4067     * This is equivalent to the SQL "IN" operator and Java "contains" operator. 4068     */ 4069    public Expression some(char[] theChars) { 4070        Vector vector = oracle.toplink.essentials.internal.helper.NonSynchronizedVector.newInstance(); 4071 4072        for (int index = 0; index < theChars.length; index++) { 4073            vector.addElement(new Character (theChars[index])); 4074        } 4075 4076        return some(vector); 4077    } 4078 4079    /** 4080     * PUBLIC: 4081     * Return an expression that checks if the receivers value is contained in the collection. 4082     * This is equivalent to the SQL "IN" operator and Java "contains" operator. 4083     */ 4084    public Expression some(double[] theDoubles) { 4085        Vector vector = oracle.toplink.essentials.internal.helper.NonSynchronizedVector.newInstance(); 4086 4087        for (int index = 0; index < theDoubles.length; index++) { 4088            vector.addElement(new Double (theDoubles[index])); 4089        } 4090 4091        return some(vector); 4092    } 4093 4094    /** 4095     * PUBLIC: 4096     * Return an expression that checks if the receivers value is contained in the collection. 4097     * This is equivalent to the SQL "IN" operator and Java "contains" operator. 4098     */ 4099    public Expression some(float[] theFloats) { 4100        Vector vector = oracle.toplink.essentials.internal.helper.NonSynchronizedVector.newInstance(); 4101 4102        for (int index = 0; index < theFloats.length; index++) { 4103            vector.addElement(new Float (theFloats[index])); 4104        } 4105 4106        return some(vector); 4107    } 4108 4109    /** 4110     * PUBLIC: 4111     * Return an expression that checks if the receivers value is contained in the collection. 4112     * This is equivalent to the SQL "IN" operator and Java "contains" operator. 4113     */ 4114    public Expression some(int[] theInts) { 4115        Vector vector = oracle.toplink.essentials.internal.helper.NonSynchronizedVector.newInstance(); 4116 4117        for (int index = 0; index < theInts.length; index++) { 4118            vector.addElement(new Integer (theInts[index])); 4119        } 4120 4121        return some(vector); 4122    } 4123 4124    /** 4125     * PUBLIC: 4126     * Return an expression that checks if the receivers value is contained in the collection. 4127     * This is equivalent to the SQL "IN" operator and Java "contains" operator. 4128     */ 4129    public Expression some(long[] theLongs) { 4130        Vector vector = oracle.toplink.essentials.internal.helper.NonSynchronizedVector.newInstance(); 4131 4132        for (int index = 0; index < theLongs.length; index++) { 4133            vector.addElement(new Long (theLongs[index])); 4134        } 4135 4136        return some(vector); 4137    } 4138 4139    /** 4140     * PUBLIC: 4141     * Return an expression that checks if the receivers value is contained in the collection. 4142     * This is equivalent to the SQL "IN" operator and Java "contains" operator. 4143     */ 4144    public Expression some(Object [] theObjects) { 4145        Vector vector = oracle.toplink.essentials.internal.helper.NonSynchronizedVector.newInstance(); 4146 4147        for (int index = 0; index < theObjects.length; index++) { 4148            vector.addElement(theObjects[index]); 4149        } 4150 4151        return some(vector); 4152    } 4153 4154    /** 4155     * PUBLIC: 4156     * Return an expression that checks if the receivers value is contained in the collection. 4157     * This is equivalent to the SQL "IN" operator and Java "contains" operator. 4158     */ 4159    public Expression some(short[] theShorts) { 4160        Vector vector = oracle.toplink.essentials.internal.helper.NonSynchronizedVector.newInstance(); 4161 4162        for (int index = 0; index < theShorts.length; index++) { 4163            vector.addElement(new Short (theShorts[index])); 4164        } 4165 4166        return some(vector); 4167    } 4168 4169    /** 4170     * PUBLIC: 4171     * Return an expression that checks if the receivers value is contained in the collection. 4172     * This is equivalent to the SQL "IN" operator and Java "contains" operator. 4173     */ 4174    public Expression some(boolean[] theBooleans) { 4175        Vector vector = oracle.toplink.essentials.internal.helper.NonSynchronizedVector.newInstance(); 4176 4177        for (int index = 0; index < theBooleans.length; index++) { 4178            vector.addElement(new Boolean (theBooleans[index])); 4179        } 4180 4181        return some(vector); 4182    } 4183 4184    /** 4185     * PUBLIC: 4186     * Return an expression that checks if the receivers value is contained in the collection. 4187     * This is equivalent to the SQL "IN" operator and Java "contains" operator. 4188     * <p>Example: 4189     * <pre><blockquote> 4190     * TopLink: employee.get("age").in(agesVector) 4191     * Java: agesVector.contains(employee.getAge()) 4192     * SQL: AGE IN (55, 18, 30) 4193     * </blockquote></pre> 4194     */ 4195    public Expression some(Vector theObjects) { 4196        return some(new ConstantExpression(theObjects, this)); 4197    } 4198 4199    public Expression some(Expression arguments) { 4200        ExpressionOperator anOperator = getOperator(ExpressionOperator.Some); 4201        return anOperator.expressionFor(this, arguments); 4202    } 4203 4204    public Expression some(ReportQuery subQuery) { 4205        return some(subQuery(subQuery)); 4206    } 4207 4208    /** 4209     * 4210     * PUBLIC: 4211     * Return an expression that is used with a comparison expression. 4212     * The SOME keyword denotes that the search condition is TRUE if the comparison is TRUE 4213     * for at least one of the values that is returned. If the subquery returns no value, 4214     * the search condition is FALSE 4215     */ 4216    public Expression all(byte[] theBytes) { 4217        Vector vector = oracle.toplink.essentials.internal.helper.NonSynchronizedVector.newInstance(); 4218 4219        for (int index = 0; index < theBytes.length; index++) { 4220            vector.addElement(new Byte (theBytes[index])); 4221        } 4222 4223        return all(vector); 4224    } 4225 4226    /** 4227     * PUBLIC: 4228     * Return an expression that checks if the receivers value is contained in the collection. 4229     * This is equivalent to the SQL "IN" operator and Java "contains" operator. 4230     */ 4231    public Expression all(char[] theChars) { 4232        Vector vector = oracle.toplink.essentials.internal.helper.NonSynchronizedVector.newInstance(); 4233 4234        for (int index = 0; index < theChars.length; index++) { 4235            vector.addElement(new Character (theChars[index])); 4236        } 4237 4238        return all(vector); 4239    } 4240 4241    /** 4242     * PUBLIC: 4243     * Return an expression that checks if the receivers value is contained in the collection. 4244     * This is equivalent to the SQL "IN" operator and Java "contains" operator. 4245     */ 4246    public Expression all(double[] theDoubles) { 4247        Vector vector = oracle.toplink.essentials.internal.helper.NonSynchronizedVector.newInstance(); 4248 4249        for (int index = 0; index < theDoubles.length; index++) { 4250            vector.addElement(new Double (theDoubles[index])); 4251        } 4252 4253        return all(vector); 4254    } 4255 4256    /** 4257     * PUBLIC: 4258     * Return an expression that checks if the receivers value is contained in the collection. 4259     * This is equivalent to the SQL "IN" operator and Java "contains" operator. 4260     */ 4261    public Expression all(float[] theFloats) { 4262        Vector vector = oracle.toplink.essentials.internal.helper.NonSynchronizedVector.newInstance(); 4263 4264        for (int index = 0; index < theFloats.length; index++) { 4265            vector.addElement(new Float (theFloats[index])); 4266        } 4267 4268        return all(vector); 4269    } 4270 4271    /** 4272     * PUBLIC: 4273     * Return an expression that checks if the receivers value is contained in the collection. 4274     * This is equivalent to the SQL "IN" operator and Java "contains" operator. 4275     */ 4276    public Expression all(int[] theInts) { 4277        Vector vector = oracle.toplink.essentials.internal.helper.NonSynchronizedVector.newInstance(); 4278 4279        for (int index = 0; index < theInts.length; index++) { 4280            vector.addElement(new Integer (theInts[index])); 4281        } 4282 4283        return all(vector); 4284    } 4285 4286    /** 4287     * PUBLIC: 4288     * Return an expression that checks if the receivers value is contained in the collection. 4289     * This is equivalent to the SQL "IN" operator and Java "contains" operator. 4290     */ 4291    public Expression all(long[] theLongs) { 4292        Vector vector = oracle.toplink.essentials.internal.helper.NonSynchronizedVector.newInstance(); 4293 4294        for (int index = 0; index < theLongs.length; index++) { 4295            vector.addElement(new Long (theLongs[index])); 4296        } 4297 4298        return all(vector); 4299    } 4300 4301    /** 4302     * PUBLIC: 4303     * Return an expression that checks if the receivers value is contained in the collection. 4304     * This is equivalent to the SQL "IN" operator and Java "contains" operator. 4305     */ 4306    public Expression all(Object [] theObjects) { 4307        Vector vector = oracle.toplink.essentials.internal.helper.NonSynchronizedVector.newInstance(); 4308 4309        for (int index = 0; index < theObjects.length; index++) { 4310            vector.addElement(theObjects[index]); 4311        } 4312 4313        return all(vector); 4314    } 4315 4316    /** 4317     * PUBLIC: 4318     * Return an expression that checks if the receivers value is contained in the collection. 4319     * This is equivalent to the SQL "IN" operator and Java "contains" operator. 4320     */ 4321    public Expression all(short[] theShorts) { 4322        Vector vector = oracle.toplink.essentials.internal.helper.NonSynchronizedVector.newInstance(); 4323 4324        for (int index = 0; index < theShorts.length; index++) { 4325            vector.addElement(new Short (theShorts[index])); 4326        } 4327 4328        return all(vector); 4329    } 4330 4331    /** 4332     * PUBLIC: 4333     * Return an expression that checks if the receivers value is contained in the collection. 4334     * This is equivalent to the SQL "IN" operator and Java "contains" operator. 4335     */ 4336    public Expression all(boolean[] theBooleans) { 4337        Vector vector = oracle.toplink.essentials.internal.helper.NonSynchronizedVector.newInstance(); 4338 4339        for (int index = 0; index < theBooleans.length; index++) { 4340            vector.addElement(new Boolean (theBooleans[index])); 4341        } 4342 4343        return all(vector); 4344    } 4345 4346    /** 4347     * PUBLIC: 4348     * Return an expression that checks if the receivers value is contained in the collection. 4349     * This is equivalent to the SQL "IN" operator and Java "contains" operator. 4350     * <p>Example: 4351     * <pre><blockquote> 4352     * TopLink: employee.get("age").in(agesVector) 4353     * Java: agesVector.contains(employee.getAge()) 4354     * SQL: AGE IN (55, 18, 30) 4355     * </blockquote></pre> 4356     */ 4357    public Expression all(Vector theObjects) { 4358        return all(new ConstantExpression(theObjects, this)); 4359    } 4360 4361    public Expression all(Expression arguments) { 4362        ExpressionOperator anOperator = getOperator(ExpressionOperator.All); 4363        return anOperator.expressionFor(this, arguments); 4364    } 4365 4366    public Expression all(ReportQuery subQuery) { 4367        return all(subQuery(subQuery)); 4368    } 4369}

A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame Popular Tags