Package org.apache.cayenne.exp

## Class Property<E>

- java.lang.Object
- - org.apache.cayenne.exp.Property<E>

- Type Parameters:
    `E` - The type this property returns.

      public class Property<E>
      extends Object

  A property in a `DataObject`.

  Used to construct Expressions quickly and with type-safety, and to construct Orderings.

  Instances of this class are immutable.

  Must be created via factory methods `Property.create(..)`

  Since:
    4.0
  See Also:
    `create(String, Class)`, `create(Expression, Class)`, `create(String, Expression, Class)`

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static Property<Long>` | `COUNT` | Property that can be used in COUNT(*) queries

  - ### Constructor Summary

    Constructors
    Modifier | Constructor | Description
    --- | --- | ---
    `protected` | `Property​(String name, Class<? super E> type)` | Constructs a new property with the given name and type.
    `protected` | `Property​(String name, Expression expression, Class<? super E> type)` | Constructs a new property with the given name and expression

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `Property<E>` | `abs()` |
    `Property<E>` | `alias​(String alias)` | Creates alias with different name for this property
    `Ordering` | `asc()` |
    `Ordering` | `ascInsensitive()` |
    `Orderings` | `ascInsensitives()` |
    `Orderings` | `ascs()` |
    `Property<E>` | `avg()` |
    `Expression` | `between​(E lower, E upper)` |
    `Property<String>` | `concat​(Object... args)` | Arguments will be converted as follows: if argument is a `Property` than its expression will be used if argument is a `Expression` than it will be used as is all other values will be converted to String
    `Expression` | `contains​(String substring)` | Creates an expression for a database "LIKE" query with the value converted to a pattern matching anywhere in the String.
    `Expression` | `containsIgnoreCase​(String value)` | Same as `contains(String)`, only using case-insensitive comparison.
    `Property<Long>` | `count()` |
    `Property<Long>` | `countDistinct()` |
    `static <T> Property<T>` | `create​(String name, Class<? super T> type)` | Creates property with name and type
    `static <T> Property<T>` | `create​(String name, Expression expression, Class<? super T> type)` | Creates property with name, expression and type
    `static <T> Property<T>` | `create​(Expression expression, Class<? super T> type)` | Creates property with expression and type
    `static <T extends Persistent> Property<T>` | `createSelf​(Class<? super T> type)` | Creates "self" Property for persistent class.
    `Ordering` | `desc()` |
    `Ordering` | `descInsensitive()` |
    `Orderings` | `descInsensitives()` |
    `Orderings` | `descs()` |
    `PrefetchTreeNode` | `disjoint()` | Returns a prefetch tree that follows this property path, potentially spanning a number of phantom nodes, and having a single leaf with "disjoint" prefetch semantics.
    `PrefetchTreeNode` | `disjointById()` | Returns a prefetch tree that follows this property path, potentially spanning a number of phantom nodes, and having a single leaf with "disjoint by id" prefetch semantics.
    `Property<Object>` | `dot​(String property)` | Constructs a property path by appending the argument to the existing property separated by a dot.
    `<T> Property<T>` | `dot​(Property<T> property)` | Constructs a new property path by appending the argument to the existing property separated by a dot.
    `Expression` | `endsWith​(String value)` | Creates an expression for a database "LIKE" query with the value converted to a pattern matching the tail of a String.
    `Expression` | `endsWithIgnoreCase​(String value)` | Same as `endsWith(String)`, only using case-insensitive comparison.
    `Expression` | `eq​(E value)` |
    `Expression` | `eq​(Property<?> value)` |
    `boolean` | `equals​(Object o)` |
    `<T extends Persistent> Property<T>` | `flat​(Class<? super T> tClass)` | Create new "flat" property for toMany relationship.
    `String` | `getAlias()` |
    `Expression` | `getExpression()` | This method returns fresh copy of the expression for each call.
    `E` | `getFrom​(Object bean)` | Extracts property value from an object using JavaBean-compatible introspection with one addition - a property can be a dot-separated property name path.
    `List<E>` | `getFromAll​(Collection<?> beans)` | Extracts property value from a collection of objects using JavaBean-compatible introspection with one addition - a property can be a dot-separated property name path.
    `String` | `getName()` |
    `Class<? super E>` | `getType()` |
    `Expression` | `gt​(E value)` |
    `Expression` | `gt​(Property<?> value)` |
    `Expression` | `gte​(E value)` |
    `Expression` | `gte​(Property<?> value)` |
    `int` | `hashCode()` |
    `Expression` | `in​(E firstValue, E... moreValues)` |
    `Expression` | `in​(Collection<E> values)` |
    `Expression` | `isFalse()` |
    `Expression` | `isNotNull()` |
    `Expression` | `isNull()` |
    `Expression` | `isTrue()` |
    `PrefetchTreeNode` | `joint()` | Returns a prefetch tree that follows this property path, potentially spanning a number of phantom nodes, and having a single leaf with "joint" prefetch semantics.
    `Property<Integer>` | `length()` |
    `Expression` | `like​(String pattern)` |
    `Expression` | `like​(String pattern, char escapeChar)` |
    `Expression` | `likeIgnoreCase​(String pattern)` |
    `Property<Integer>` | `locate​(String string)` |
    `Property<Integer>` | `locate​(Property<? extends String> property)` |
    `Property<String>` | `lower()` |
    `Expression` | `lt​(E value)` |
    `Expression` | `lt​(Property<?> value)` |
    `Expression` | `lte​(E value)` |
    `Expression` | `lte​(Property<?> value)` |
    `Property<E>` | `max()` |
    `Property<E>` | `min()` |
    `Property<E>` | `mod​(Number number)` |
    `Expression` | `ne​(E value)` |
    `Expression` | `ne​(Property<?> value)` |
    `Expression` | `nin​(E firstValue, E... moreValues)` |
    `Expression` | `nin​(Collection<E> values)` |
    `Expression` | `nlike​(String value)` |
    `Expression` | `nlikeIgnoreCase​(String value)` |
    `Property<E>` | `outer()` | Returns a version of this property that represents an OUTER join.
    `Expression` | `path()` | Converts this property to a path expression.
    `void` | `setIn​(Object bean, E value)` | Sets a property value in 'obj' using JavaBean-compatible introspection with one addition - a property can be a dot-separated property name path.
    `void` | `setInAll​(Collection<?> beans, E value)` | Sets a property value in a collection of objects using JavaBean-compatible introspection with one addition - a property can be a dot-separated property name path.
    `Property<E>` | `sqrt()` |
    `Expression` | `startsWith​(String value)` | Creates an expression for a database "LIKE" query with the value converted to a pattern matching the beginning of a String.
    `Expression` | `startsWithIgnoreCase​(String value)` | Same as `startsWith(String)`, only using case-insensitive comparison.
    `Property<String>` | `substring​(int offset, int length)` |
    `Property<E>` | `sum()` |
    `Property<String>` | `trim()` |
    `Property<String>` | `upper()` |

    - ### Methods inherited from class java.lang.Object

      `clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### COUNT

          public static final Property<Long> COUNT

      Property that can be used in COUNT(*) queries

           List<Object[]> result = ObjectSelect
                   .columnQuery(Artist.class, Property.COUNT, Artist.ARTIST_NAME)
                   .having(Property.COUNT.gt(1L))
                   .select(context);

  - ### Constructor Detail

    - #### Property

          protected Property​(String name,
                             Class<? super E> type)

      Constructs a new property with the given name and type.
      Parameters:
        `name` - of the property (usually it's obj path)
        `type` - of the property
      See Also:
        `create(String, Class)`

    - #### Property

          protected Property​(String name,
                             Expression expression,
                             Class<? super E> type)

      Constructs a new property with the given name and expression
      Parameters:
        `name` - of the property (will be used as alias for the expression)
        `expression` - expression for property
        `type` - of the property
      See Also:
        `create(String, Expression, Class)`

  - ### Method Detail

    - #### getName

          public String getName()

      Returns:
        Name of the property in the object.

    - #### getAlias

          public String getAlias()

      Returns:
        alias for this property

    - #### getExpression

          public Expression getExpression()

      This method returns fresh copy of the expression for each call.
      Returns:
        expression that represents this Property

    - #### hashCode

          public int hashCode()

      Overrides:
        `hashCode` in class `Object`

    - #### equals

          public boolean equals​(Object o)

      Overrides:
        `equals` in class `Object`

    - #### dot

          public Property<Object> dot​(String property)

      Constructs a property path by appending the argument to the existing property separated by a dot.
      Returns:
        a newly created Property object.

    - #### dot

          public <T> Property<T> dot​(Property<T> property)

      Constructs a new property path by appending the argument to the existing property separated by a dot.
      Returns:
        a newly created Property object.

    - #### outer

          public Property<E> outer()

      Returns a version of this property that represents an OUTER join. It is up to caller to ensure that the property corresponds to a relationship, as "outer" attributes make no sense.

    - #### path

          public Expression path()

      Converts this property to a path expression. This method is equivalent of getExpression() which is preferred as more generic.
      Returns:
        a newly created expression.
      See Also:
        `getExpression()`

    - #### isNull

          public Expression isNull()

      Returns:
        An expression representing null.

    - #### isNotNull

          public Expression isNotNull()

      Returns:
        An expression representing a non-null value.

    - #### isTrue

          public Expression isTrue()

      Returns:
        An expression representing equality to TRUE.

    - #### isFalse

          public Expression isFalse()

      Returns:
        An expression representing equality to FALSE.

    - #### eq

          public Expression eq​(E value)

      Returns:
        An expression representing equality to a value.

    - #### eq

          public Expression eq​(Property<?> value)

      Returns:
        An expression representing equality between two attributes (columns).

    - #### ne

          public Expression ne​(E value)

      Returns:
        An expression representing inequality to a value.

    - #### ne

          public Expression ne​(Property<?> value)

      Returns:
        An expression representing inequality between two attributes (columns).

    - #### like

          public Expression like​(String pattern)

      Parameters:
        `pattern` - a pattern matching property value. Pattern may include "_" and "%" wildcard symbols to match any single character or a sequence of characters. To prevent "_" and "%" from being treated as wildcards, they need to be escaped and escape char passed with `like(String, char)` method.
      Returns:
        An expression for a Database "LIKE" query.

    - #### like

          public Expression like​(String pattern,
                                 char escapeChar)

      Parameters:
        `pattern` - a properly escaped pattern matching property value. Pattern may include "_" and "%" wildcard symbols to match any single character or a sequence of characters.
        `escapeChar` - an escape character used in the pattern to escape "%" and "_".
      Returns:
        An expression for a Database "LIKE" query.

    - #### likeIgnoreCase

          public Expression likeIgnoreCase​(String pattern)

      Returns:
        An expression for a case insensitive "LIKE" query.

    - #### nlike

          public Expression nlike​(String value)

      Returns:
        An expression for a Database "NOT LIKE" query.

    - #### nlikeIgnoreCase

          public Expression nlikeIgnoreCase​(String value)

      Returns:
        An expression for a case insensitive "NOT LIKE" query.

    - #### contains

          public Expression contains​(String substring)

      Creates an expression for a database "LIKE" query with the value converted to a pattern matching anywhere in the String.
      Parameters:
        `substring` - a String to match against property value. "_" and "%" symbols are NOT treated as wildcards and are escaped when converted to a LIKE expression.
      Returns:
        a newly created expression.

    - #### startsWith

          public Expression startsWith​(String value)

      Creates an expression for a database "LIKE" query with the value converted to a pattern matching the beginning of a String.
      Parameters:
        `value` - a String to match against property value. "_" and "%" symbols are NOT treated as wildcards and are escaped when converted to a LIKE expression.
      Returns:
        a newly created expression.

    - #### endsWith

          public Expression endsWith​(String value)

      Creates an expression for a database "LIKE" query with the value converted to a pattern matching the tail of a String.
      Parameters:
        `value` - a String to match against property value. "_" and "%" symbols are NOT treated as wildcards and are escaped when converted to a LIKE expression.
      Returns:
        a newly created expression.

    - #### containsIgnoreCase

          public Expression containsIgnoreCase​(String value)

      Same as `contains(String)`, only using case-insensitive comparison.

    - #### startsWithIgnoreCase

          public Expression startsWithIgnoreCase​(String value)

      Same as `startsWith(String)`, only using case-insensitive comparison.

    - #### endsWithIgnoreCase

          public Expression endsWithIgnoreCase​(String value)

      Same as `endsWith(String)`, only using case-insensitive comparison.

    - #### between

          public Expression between​(E lower,
                                    E upper)

      Parameters:
        `lower` - The lower bound.
        `upper` - The upper bound.
      Returns:
        An expression checking for objects between a lower and upper bound inclusive

    - #### in

          public Expression in​(E firstValue,
                               E... moreValues)

      Returns:
        An expression for finding objects with values in the given set.

    - #### nin

          public Expression nin​(E firstValue,
                                E... moreValues)

      Returns:
        An expression for finding objects with values not in the given set.

    - #### in

          public Expression in​(Collection<E> values)

      Returns:
        An expression for finding objects with values in the given set.

    - #### nin

          public Expression nin​(Collection<E> values)

      Returns:
        An expression for finding objects with values not in the given set.

    - #### gt

          public Expression gt​(E value)

      Returns:
        A greater than Expression.

    - #### gt

          public Expression gt​(Property<?> value)

      Returns:
        Represents a greater than relationship between two attributes (columns).

    - #### gte

          public Expression gte​(E value)

      Returns:
        A greater than or equal to Expression.

    - #### gte

          public Expression gte​(Property<?> value)

      Returns:
        Represents a greater than or equal relationship between two attributes (columns).

    - #### lt

          public Expression lt​(E value)

      Returns:
        A less than Expression.

    - #### lt

          public Expression lt​(Property<?> value)

      Returns:
        Represents a less than relationship between two attributes (columns).

    - #### lte

          public Expression lte​(E value)

      Returns:
        A less than or equal to Expression.

    - #### lte

          public Expression lte​(Property<?> value)

      Returns:
        Represents a less than or equal relationship between two attributes (columns).

    - #### asc

          public Ordering asc()

      Returns:
        Ascending sort orderings on this property.

    - #### ascs

          public Orderings ascs()

      Returns:
        Ascending sort orderings on this property.

    - #### ascInsensitive

          public Ordering ascInsensitive()

      Returns:
        Ascending case insensitive sort orderings on this property.

    - #### ascInsensitives

          public Orderings ascInsensitives()

      Returns:
        Ascending case insensitive sort orderings on this property.

    - #### desc

          public Ordering desc()

      Returns:
        Descending sort orderings on this property.

    - #### descs

          public Orderings descs()

      Returns:
        Descending sort orderings on this property.

    - #### descInsensitive

          public Ordering descInsensitive()

      Returns:
        Descending case insensitive sort orderings on this property.

    - #### descInsensitives

          public Orderings descInsensitives()

      Returns:
        Descending case insensitive sort orderings on this property.

    - #### joint

          public PrefetchTreeNode joint()

      Returns a prefetch tree that follows this property path, potentially spanning a number of phantom nodes, and having a single leaf with "joint" prefetch semantics.

    - #### disjoint

          public PrefetchTreeNode disjoint()

      Returns a prefetch tree that follows this property path, potentially spanning a number of phantom nodes, and having a single leaf with "disjoint" prefetch semantics.

    - #### disjointById

          public PrefetchTreeNode disjointById()

      Returns a prefetch tree that follows this property path, potentially spanning a number of phantom nodes, and having a single leaf with "disjoint by id" prefetch semantics.

    - #### getFrom

          public E getFrom​(Object bean)

      Extracts property value from an object using JavaBean-compatible introspection with one addition - a property can be a dot-separated property name path.

    - #### getFromAll

          public List<E> getFromAll​(Collection<?> beans)

      Extracts property value from a collection of objects using JavaBean-compatible introspection with one addition - a property can be a dot-separated property name path.

    - #### setIn

          public void setIn​(Object bean,
                            E value)

      Sets a property value in 'obj' using JavaBean-compatible introspection with one addition - a property can be a dot-separated property name path.

    - #### setInAll

          public void setInAll​(Collection<?> beans,
                               E value)

      Sets a property value in a collection of objects using JavaBean-compatible introspection with one addition - a property can be a dot-separated property name path.

    - #### count

          public Property<Long> count()

      See Also:
        `FunctionExpressionFactory.countExp(Expression)`

    - #### countDistinct

          public Property<Long> countDistinct()

      Since:
        4.1
      See Also:
        `FunctionExpressionFactory.countDistinctExp(Expression)`

    - #### max

          public Property<E> max()

      See Also:
        `FunctionExpressionFactory.maxExp(Expression)`

    - #### min

          public Property<E> min()

      See Also:
        `FunctionExpressionFactory.minExp(Expression)`

    - #### avg

          public Property<E> avg()

      See Also:
        `FunctionExpressionFactory.avgExp(Expression)`

    - #### sum

          public Property<E> sum()

      See Also:
        `FunctionExpressionFactory.sumExp(Expression)`

    - #### mod

          public Property<E> mod​(Number number)

      See Also:
        `FunctionExpressionFactory.modExp(Expression, Number)`

    - #### abs

          public Property<E> abs()

      See Also:
        `FunctionExpressionFactory.absExp(Expression)`

    - #### sqrt

          public Property<E> sqrt()

      See Also:
        `FunctionExpressionFactory.sqrtExp(Expression)`

    - #### length

          public Property<Integer> length()

      See Also:
        `FunctionExpressionFactory.lengthExp(Expression)`

    - #### locate

          public Property<Integer> locate​(String string)

      See Also:
        `FunctionExpressionFactory.locateExp(String, Expression)`

    - #### locate

          public Property<Integer> locate​(Property<? extends String> property)

      See Also:
        `FunctionExpressionFactory.locateExp(Expression, Expression)`

    - #### trim

          public Property<String> trim()

      See Also:
        `FunctionExpressionFactory.trimExp(Expression)`

    - #### upper

          public Property<String> upper()

      See Also:
        `FunctionExpressionFactory.upperExp(Expression)`

    - #### lower

          public Property<String> lower()

      See Also:
        `FunctionExpressionFactory.lowerExp(Expression)`

    - #### concat

          public Property<String> concat​(Object... args)

      Arguments will be converted as follows:

      - if argument is a `Property` than its expression will be used
      - if argument is a `Expression` than it will be used as is
      - all other values will be converted to String

      Usage:

               Property<String> fullName = Artist.FIRST_NAME.concat(" ", Artist.SECOND_NAME);

      See Also:
        `FunctionExpressionFactory.concatExp(Expression...)`

    - #### substring

          public Property<String> substring​(int offset,
                                            int length)

      See Also:
        `FunctionExpressionFactory.substringExp(Expression, int, int)`

    - #### alias

          public Property<E> alias​(String alias)

      Creates alias with different name for this property

    - #### flat

          public <T extends Persistent> Property<T> flat​(Class<? super T> tClass)

      Create new "flat" property for toMany relationship.

      Example:

               List<Object[]> result = ObjectSelect
                    .columnQuery(Artist.class, Artist.ARTIST_NAME, Artist.PAINTING_ARRAY.flat(Painting.class))
                    .select(context);

    - #### getType

          public Class<? super E> getType()

    - #### create

          public static <T> Property<T> create​(String name,
                                               Class<? super T> type)

      Creates property with name and type
      See Also:
        `create(Expression, Class)`, `create(String, Expression, Class)`

    - #### create

          public static <T> Property<T> create​(Expression expression,
                                               Class<? super T> type)

      Creates property with expression and type
      See Also:
        `create(String, Class)`, `create(String, Expression, Class)`

    - #### create

          public static <T> Property<T> create​(String name,
                                               Expression expression,
                                               Class<? super T> type)

      Creates property with name, expression and type
      See Also:
        `create(String, Class)`, `create(Expression, Class)`

    - #### createSelf

          public static <T extends Persistent> Property<T> createSelf​(Class<? super T> type)

      Creates "self" Property for persistent class. This property can be used to select full object along with some of it properties (or properties that can be resolved against query root)

      Here is sample code, that will select all Artists and count of their Paintings:

               Property<Artist> artistFull = Property.createSelf(Artist.class);
               List<Object[]> result = ObjectSelect
                    .columnQuery(Artist.class, artistFull, Artist.PAINTING_ARRAY.count())
                    .select(context);