Overview | Package | Class | Tree | Deprecated | Index | Help
| © 2002 BEA Systems, Inc.
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.bea.p13n.content.expression
Class ExpressionHelper

    java.lang.Object
      |
      +--com.bea.p13n.content.expression.ExpressionHelper

public class ExpressionHelper
extends java.lang.Object

Helper class to handle dealing with content Expressions.

For details on what content expression should look like, see `parse`.

Inner Class Summary
`static interface` | `ExpressionHelper.ParseException` Exception to report an error while parsing a query expression.

Field Summary
`static java.lang.String` | `AND` Syntax textual and logical operator.
`static java.lang.String` | `CONTAINS` Syntax textual contains operator.
`static java.lang.String` | `CONTAINS_ALL` Syntax textual contains all operator.
`static java.text.DateFormat` | `defDateFormat` The default date formatter.
`static java.lang.String` | `defDateFormatStr` The default datetime format string in the content expression syntax ("MM/dd/yyyy HH:mm:ss z").
`static java.lang.String` | `EQUALS` Syntax textual equals operator.
`static java.lang.String` | `GREATER_THAN` Syntax textual greater than operator.
`static java.lang.String` | `GREATER_THAN_EQUALS` Syntax textual greater than or equals operator.
`static java.lang.String` | `LESS_THAN` Syntax textual less than operator.
`static java.lang.String` | `LESS_THAN_EQUALS` Syntax textual less than or equals operator.
`static java.lang.String` | `LIKE` Syntax textual like operator.
`static java.lang.String` | `LIKE_IGNORECASE` Syntax textual case-insensitive like operator.
`static java.lang.String` | `NOT_EQUALS` Syntax textual not equals operator.
`static java.lang.String` | `OR` Syntax textual or logical operator.

Constructor Summary
`ExpressionHelper()`

Method Summary
`static ExpressionHelper.ParseException` | `convertException(java.lang.Exception excep)` Convert a generic exception into a ParseException.
`static java.lang.String` | `fromStringLiteral(java.lang.String in)` Convert a String literal (which may contain quoted characters) into a corresponding String value.
`static java.lang.String` | `getComparator(Expression expr)` Get the syntax comparator textual operator for the given leaf node.
`static java.lang.String` | `getContentId(Expression expr)` Return the content id from the expression, if it's an expression for a single content object based upon identifier.
`static Search` | `getContentIdSearch(java.lang.String contentId)` Get a search object for a single content based upon the supplied id.
`static PropertyRef` | `getLeftHandSide(Expression expr)` Get the left-hand-side of a valid leaf node, which should be a PropertyRef
`static java.lang.String` | `getLogicalComparator(Expression expr)` Get the syntax logical comparator textual operator for the given branch node.
`static int` | `getOrdinalValue(char ch)` Get the ordinal (Unicode) value of a character.
`static java.lang.Object` | `getRightHandSide(Expression expr)` Get the right-hand-side of a valid leaf node.
`static Expression` | `getSubExpression(Expression expr, int count)`
`static boolean` | `isHexString(java.lang.String str)` Determine if a string contains only ASCII hexidecimal characters ([0-9a-fA-F]).
`static Expression` | `isLogicalNot(Expression expr)` Tell if an expression is really a logical not and, if so, returned the contained expression.
`static boolean` | `isValidBranchNode(Expression expr)` Tell if an expression is a valid content branch node type.
`static boolean` | `isValidLeafNode(Expression expr)` Tell if an expression is a valid content leaf node type.
`static LogicalAnd` | `join(Expression expr1, Expression expr2)` Join together two expression via an AND expression.
`static Expression` | `normalize(Expression expr)` Normalize an Expression.
`static Expression` | `parse(java.lang.String queryStr)` Convert a query expression string into an Expression object.
`static void` | `print(java.io.PrintWriter out, Expression expr)` Print a string representation of the given expression.
`static void` | `printBranchNode(java.io.PrintWriter out, Expression expr)` Return a string representation of the given expression branch.
`static void` | `printLeafNode(java.io.PrintWriter out, Expression expr)` Return a string representation of the given leaf expression node.
`static void` | `printTree(int depth, java.io.PrintWriter out, Expression expr)` For debug purposes, print the given expression as a tree at the given depth.
`static void` | `printTree(java.io.PrintWriter out, Expression expr)` For debug purposes, print the given expression as a tree.
`static java.lang.String` | `toString(Expression expr)` Get a string representation of the given expression.
`static java.lang.String` | `toStringLiteral(java.lang.String in)` Get an ASCII String literal from a Java string.
`static java.lang.String` | `toTree(Expression expr)` For debug purposes, return a tree representation of the given expression.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### defDateFormatStr

    public static final java.lang.String defDateFormatStr

  The default datetime format string in the content expression syntax ("MM/dd/yyyy HH:mm:ss z").

### defDateFormat

    public static final java.text.DateFormat defDateFormat

  The default date formatter.

### EQUALS

    public static final java.lang.String EQUALS

  Syntax textual equals operator.

### NOT_EQUALS

    public static final java.lang.String NOT_EQUALS

  Syntax textual not equals operator.

### GREATER_THAN

    public static final java.lang.String GREATER_THAN

  Syntax textual greater than operator.

### LESS_THAN

    public static final java.lang.String LESS_THAN

  Syntax textual less than operator.

### GREATER_THAN_EQUALS

    public static final java.lang.String GREATER_THAN_EQUALS

  Syntax textual greater than or equals operator.

### LESS_THAN_EQUALS

    public static final java.lang.String LESS_THAN_EQUALS

  Syntax textual less than or equals operator.

### LIKE

    public static final java.lang.String LIKE

  Syntax textual like operator.

### LIKE_IGNORECASE

    public static final java.lang.String LIKE_IGNORECASE

  Syntax textual case-insensitive like operator.

### CONTAINS

    public static final java.lang.String CONTAINS

  Syntax textual contains operator.

### CONTAINS_ALL

    public static final java.lang.String CONTAINS_ALL

  Syntax textual contains all operator.

### AND

    public static final java.lang.String AND

  Syntax textual and logical operator.

### OR

    public static final java.lang.String OR

  Syntax textual or logical operator.

Constructor Detail

### ExpressionHelper

    public ExpressionHelper()

Method Detail

### parse

    public static Expression parse(java.lang.String queryStr)
                            throws ExpressionHelper.ParseException,
                                   java.lang.IllegalArgumentException

  Convert a query expression string into an Expression object.

  The string should follow the query syntax specified in the Personalization Server documentation. The expression syntax is tree-based, with each leaf in the tree beinging of the form "property comparator value" (e.g. "`identifier == '1234'`").

  Property (LHS)

    This specifies the object property to match against. To specify a property name which contains non-identifier characters (e.g. whitespace, double quotes, dashes), you can use the "`toProperty('property name')`" form in the left-hand-side. To specify property set names as part of the property name, either use the "`properyset.name`" form or the "`toProperty('propertyset', 'property')`" form in the left-hand-side.

  Comparators

  The valid comparision operators are `=` (or `==`), `!=`, `<`, `>`, `<=`, `>=`, "`like`", "`likeignorecase`" and "`contains`". The "`like`" and "`likeignorecase`" operator expects the pattern (which is the value of the leaf) to use `*` (match all) and `?` (match any); "`like`" and "`likeignorecase`" also is only expected to work against String values, although it might work with other datatypes depending upon the search implementation. "`like`" operator does case-sensitive pattern match, while "`likeignorecase`" operator does case- insensitive pattern match. The "`contains`" operator is only expected to work against multi-valued properties, although it might work with other datatypes depending upon the search implementation.

Value (RHS)
  - String literal values are enclosed in single quotes (back-slash is the quoting character, unicode characters not supported). Additionally, unicode (e.g. "`\u6565`"), octal (e.g. "`\7`", "`\65`", "`\377`"), and standard Java escape sequences (e.g. "`\n`", "`\r`", "`\b`") are allowed in the string literals.
  - Boolean literals are either the "`true`" or "`false`" keyword (without quotes).
  - Number literals are Java form (scientific notation is supported).
  - Time literals are presented in "`toDate(['formatStr'], 'dateStr')`" format. `formatStr` must be a valid `SimpleDateFormat` format string; if omitted, '`MM/dd/yyyy HH:mm:ss z`' is used. Also, the "`now`" keyword specifies the time at which the expression was created.
  - Collections cannot be represented in the expression syntax.

Each branch in the tree is comprised of 1 or more leafs or branches separated by either "`&&`" (boolean AND) or "`||`" (boolean OR). They can be enclosed in parenthesis for clearity and ordering (AND has precendance over OR). Additionally, "`!`" marks a branch as using negative logic (boolean NOT). The "`!`" operator can only be used preceding an open parenthesis.

Examples of valid expression strings: ``

- identifier == '00099abv48932ds'
- ((UserAge <= 35 && colors contains 'red') || (UserAge > 35 && !(colors contains 'black')) && mimeType == 'text/html'
- toProperty('MyApp', 'Launch Date') < now && !(MyApp.expireDate > toDate('HH:mm:ss MM-dd-yyyy', '12:12:12 12/12/2002'))

In the resulting expression tree, the following caveats apply for it to be valid for the ContentManager:

- Each branch node can only be a LogicalAnd, LogicalOr, LogicalMulitAnd, or LogicalMultiOr. Any other branch node type is invalid.
- Each leaf node can only be an Equals, GreaterOrEquals, GreaterThan, LessOrEquals, LessThan, NotEquals, StringLike, CollectionContains, or CollectionsContainsAll. Any other branch node type is invalid.
- Any valid branch or leaf node may be contained in a LogicalNot node.
- In each leaf node, the left-hand-side will always be a PropertyRef node, which must contain Strings for getPropertySet() and getPropertyName().
- The right-hand-side of Equals, NotEquals, GreaterOrEquals, GreaterThan, LessOrEquals, LessThan, or CollectionContains leaf nodes can be a Collection, Long, Double, String, or Timestamp.
- The right-hand-side of StringLike leaf nodes can be a String. Anything else is invalid.
- The right-hand-side of CollectionsContainsAll leaf nodes can be a Collection. Anything else is invalid.

  Parameters:
    `queryStr` - the query expression string
  Returns:
    an Expression object representing (null if queryStr is a null expression).
  Throws:
    ExpressionHelper.ParseException - thrown on a an invalid expression query or a parser error.
    java.lang.IllegalArgumentException - thrown on a general error.
  See Also:
    `convertException(java.lang.Exception)`, `normalize(com.bea.p13n.expression.Expression)`

### join

    public static LogicalAnd join(Expression expr1,
                                  Expression expr2)

  Join together two expression via an AND expression.

  Parameters:
    `expr1` - the first expression.
    `expr2` - the second expression.
  Returns:
    a LogicalAnd of the two expressions.

### getContentIdSearch

    public static Search getContentIdSearch(java.lang.String contentId)

  Get a search object for a single content based upon the supplied id.

### getContentId

    public static java.lang.String getContentId(Expression expr)

  Return the content id from the expression, if it's an expression for a single content object based upon identifier.

  Returns:
    the content id, or null if it's not a identifier equality expression.

### normalize

    public static Expression normalize(Expression expr)
                                throws java.lang.IllegalArgumentException

  Normalize an Expression.

  This will recursively remove branches that contain only one Expression (which are boolean equivelant to the one child expression) or that contain no children (which are considered empty).

  Parameters:
    `expr` - the incoming expression.
  Returns:
    the normalized expression, null if normalized to nothing.
  Throws:
    java.lang.IllegalArgumentException - thrown if the expression is not a valid content expression.

### isLogicalNot

    public static Expression isLogicalNot(Expression expr)

  Tell if an expression is really a logical not and, if so, returned the contained expression.

  Parameters:
    `expr` - the expression.
  Returns:
    the contained expressions if expr is a logical not, null otherwise.

### isValidLeafNode

    public static boolean isValidLeafNode(Expression expr)

  Tell if an expression is a valid content leaf node type.

### isValidBranchNode

    public static boolean isValidBranchNode(Expression expr)

  Tell if an expression is a valid content branch node type.

### toString

    public static java.lang.String toString(Expression expr)
                                     throws java.lang.IllegalArgumentException

  Get a string representation of the given expression.

  Pretty much, a string generated from this method can be parse()'ed into the equivalent (not neccessarily identical) expression tree.

  Parameters:
    `expr` - the expression.
  Returns:
    the query syntax representation of the expression.
  Throws:
    java.lang.IllegalArgumentException - thrown if the given expression is not a valid content expression.

### print

    public static void print(java.io.PrintWriter out,
                             Expression expr)
                      throws java.lang.IllegalArgumentException

  Print a string representation of the given expression.

  Pretty much, a string generated from this method can be parse()'ed into the equivalent (not neccessarily identical) expression tree.

  Parameters:
    `out` - the output writer.
    `expr` - the expression.
  Throws:
    java.lang.IllegalArgumentException - thrown if the given expression is not a valid content expression.

### printLeafNode

    public static void printLeafNode(java.io.PrintWriter out,
                                     Expression expr)
                              throws java.lang.IllegalArgumentException

  Return a string representation of the given leaf expression node.

### getLeftHandSide

    public static PropertyRef getLeftHandSide(Expression expr)
                                       throws java.lang.IllegalArgumentException

  Get the left-hand-side of a valid leaf node, which should be a PropertyRef

### getComparator

    public static java.lang.String getComparator(Expression expr)
                                          throws java.lang.IllegalArgumentException

  Get the syntax comparator textual operator for the given leaf node.

### getRightHandSide

    public static java.lang.Object getRightHandSide(Expression expr)
                                             throws java.lang.IllegalArgumentException

  Get the right-hand-side of a valid leaf node.

### printBranchNode

    public static void printBranchNode(java.io.PrintWriter out,
                                       Expression expr)

  Return a string representation of the given expression branch.

### getLogicalComparator

    public static java.lang.String getLogicalComparator(Expression expr)
                                                 throws java.lang.IllegalArgumentException

  Get the syntax logical comparator textual operator for the given branch node.

### getSubExpression

    public static Expression getSubExpression(Expression expr,
                                              int count)
                                       throws java.lang.IllegalArgumentException

### toTree

    public static java.lang.String toTree(Expression expr)

  For debug purposes, return a tree representation of the given expression.

### printTree

    public static void printTree(java.io.PrintWriter out,
                                 Expression expr)

  For debug purposes, print the given expression as a tree.

  Parameters:
    `out` - the output stream to print on.
    `expr` - the expression.

### printTree

    public static void printTree(int depth,
                                 java.io.PrintWriter out,
                                 Expression expr)

  For debug purposes, print the given expression as a tree at the given depth.

  Parameters:
    `depth` - the depth of this expression in the tree.
    `out` - the output stream to print on.
    `expr` - the expression.

### fromStringLiteral

    public static java.lang.String fromStringLiteral(java.lang.String in)

  Convert a String literal (which may contain quoted characters) into a corresponding String value.

  This supports the standard Java Language Specification escape sequences.

  Parameters:
    `in` - the input string literal.
  Returns:
    the string value.

### isHexString

    public static boolean isHexString(java.lang.String str)

  Determine if a string contains only ASCII hexidecimal characters ([0-9a-fA-F]).

### toStringLiteral

    public static java.lang.String toStringLiteral(java.lang.String in)

  Get an ASCII String literal from a Java string.

  This will quote some special characters with back-slashes.

  The output of this can be sent through `fromStringLiteral(java.lang.String)` to result in the original String.

### getOrdinalValue

    public static int getOrdinalValue(char ch)

  Get the ordinal (Unicode) value of a character.

### convertException

    public static ExpressionHelper.ParseException convertException(java.lang.Exception excep)

  Convert a generic exception into a ParseException.

Overview | Package | Class | Tree | Deprecated | Index | Help
| © 2002 BEA Systems, Inc.
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2002 BEA Systems, Inc. All Rights Reserved