Package org.synchronoss.cpo.core

Class CpoWhereBuilder

java.lang.Object
org.synchronoss.cpo.core.CpoWhereBuilder
public final class CpoWhereBuilder extends Object
A fluent builder for assembling CpoWhere trees, including nested AND/OR groups, without hand-placing Logical operators on leaves and group containers.

Building a CpoWhere tree by hand requires knowing that a leaf's Logical joins it to the *previous sibling*, while a group container's Logical joins the *whole group* to its previous sibling in the parent chain — an easy detail to invert with no compile-time protection. This builder derives the correct placement from the order methods are called: 


 CpoWhere where = cpoAdapter.whereBuilder()
     .where("id", Comparison.EQ, valObj)
     .and(g -> g.where("id", Comparison.EQ, valObj2).or("id", Comparison.EQ, valObj3))
     .build();

CpoAdapter.whereBuilder() is the usual entry point; create(org.synchronoss.cpo.core.CpoAdapter) is the underlying static factory it delegates to.

where() must be the first condition in a chain; and()/or() add subsequent conditions or nested groups. Modifier methods (compareToAttribute(java.lang.String), attributeFunction(java.lang.String), rightAttributeFunction(java.lang.String), valueFunction(java.lang.String), staticValue(java.lang.String)) apply to the condition most recently added. Misuse (calling a modifier before any condition exists, calling where() more than once, or calling build() with no conditions) throws IllegalStateException, since these are programmer sequencing errors rather than datastore failures.

Some function groups' own native expression already supplies a base WHERE clause (or an always-true placeholder condition), and a run-time where must be interleaved onto it with an explicit AND/OR rather than starting fresh. For that case, start the chain with and(String, Comparison, Object)/or(String, Comparison, Object) (or their group-taking overloads) instead of where(): 


 CpoWhere where = cpoAdapter.whereBuilder().and("id", Comparison.EQ, valObj).build();
A chain started this way must contain exactly that one top-level condition or group (nest further conditions inside the group instead) — build() then returns it directly, without the wrapping container that a normal where()-started chain uses to render its own leading WHERE, since that wrapper would otherwise duplicate the base clause already baked into the query.

Instances are not thread-safe and are meant to be built up and discarded once build() is called.

Author:
david berry

  • Method Details

    • create

      public static CpoWhereBuilder create(CpoAdapter adapter) throws CpoException
      Creates a new CpoWhereBuilder. Most callers should use CpoAdapter.whereBuilder() instead, which delegates here.
      Parameters:
      adapter - the adapter used to create the underlying CpoWhere nodes
      Returns:
      a new builder with no conditions yet
      Throws:
      CpoException - if the underlying where clause cannot be created

    • where

      public <T> CpoWhereBuilder where(String attr, Comparison comp, T value) throws CpoException
      Starts the chain with a comparison of the named attribute to a value.
      Type Parameters:
      T - the type of the comparison value
      Parameters:
      attr - the name of the bean attribute to compare
      comp - the comparison operator to apply
      value - the value to compare the attribute against
      Returns:
      this builder
      Throws:
      CpoException - if the condition cannot be created
      IllegalStateException - if this builder already has a condition

    • where

      public <T> CpoWhereBuilder where(String attr, Comparison comp, T value, boolean not) throws CpoException
      Starts the chain with a comparison of the named attribute to a value, optionally negated.
      Type Parameters:
      T - the type of the comparison value
      Parameters:
      attr - the name of the bean attribute to compare
      comp - the comparison operator to apply
      value - the value to compare the attribute against
      not - true to negate the comparison
      Returns:
      this builder
      Throws:
      CpoException - if the condition cannot be created
      IllegalStateException - if this builder already has a condition

    • and

      public <T> CpoWhereBuilder and(String attr, Comparison comp, T value) throws CpoException
      Adds a condition joined to the previous condition with AND.
      Type Parameters:
      T - the type of the comparison value
      Parameters:
      attr - the name of the bean attribute to compare
      comp - the comparison operator to apply
      value - the value to compare the attribute against
      Returns:
      this builder
      Throws:
      CpoException - if the condition cannot be created

    • and

      public <T> CpoWhereBuilder and(String attr, Comparison comp, T value, boolean not) throws CpoException
      Adds a condition joined to the previous condition with AND, optionally negated.
      Type Parameters:
      T - the type of the comparison value
      Parameters:
      attr - the name of the bean attribute to compare
      comp - the comparison operator to apply
      value - the value to compare the attribute against
      not - true to negate the comparison
      Returns:
      this builder
      Throws:
      CpoException - if the condition cannot be created

    • or

      public <T> CpoWhereBuilder or(String attr, Comparison comp, T value) throws CpoException
      Adds a condition joined to the previous condition with OR.
      Type Parameters:
      T - the type of the comparison value
      Parameters:
      attr - the name of the bean attribute to compare
      comp - the comparison operator to apply
      value - the value to compare the attribute against
      Returns:
      this builder
      Throws:
      CpoException - if the condition cannot be created

    • or

      public <T> CpoWhereBuilder or(String attr, Comparison comp, T value, boolean not) throws CpoException
      Adds a condition joined to the previous condition with OR, optionally negated.
      Type Parameters:
      T - the type of the comparison value
      Parameters:
      attr - the name of the bean attribute to compare
      comp - the comparison operator to apply
      value - the value to compare the attribute against
      not - true to negate the comparison
      Returns:
      this builder
      Throws:
      CpoException - if the condition cannot be created

    • and

      public CpoWhereBuilder and(CpoWhereGroup group) throws CpoException
      Adds a nested group of conditions, joined to the previous condition with AND.
      Parameters:
      group - populates the nested group's conditions
      Returns:
      this builder
      Throws:
      CpoException - if the group or its conditions cannot be created
      IllegalStateException - if the group adds no conditions

    • or

      public CpoWhereBuilder or(CpoWhereGroup group) throws CpoException
      Adds a nested group of conditions, joined to the previous condition with OR.
      Parameters:
      group - populates the nested group's conditions
      Returns:
      this builder
      Throws:
      CpoException - if the group or its conditions cannot be created
      IllegalStateException - if the group adds no conditions

    • compareToAttribute

      public CpoWhereBuilder compareToAttribute(String rightAttr)
      Compares the condition just added against another attribute instead of a literal value.
      Parameters:
      rightAttr - the name of the right-hand bean attribute to compare against
      Returns:
      this builder
      Throws:
      IllegalStateException - if no condition has been added yet

    • attributeFunction

      public CpoWhereBuilder attributeFunction(String fn)
      Applies a native datastore function to the left-hand attribute of the condition just added.
      Parameters:
      fn - the function expression to apply
      Returns:
      this builder
      Throws:
      IllegalStateException - if no condition has been added yet

    • rightAttributeFunction

      public CpoWhereBuilder rightAttributeFunction(String fn)
      Applies a native datastore function to the right-hand attribute of the condition just added.
      Parameters:
      fn - the function expression to apply
      Returns:
      this builder
      Throws:
      IllegalStateException - if no condition has been added yet

    • valueFunction

      public CpoWhereBuilder valueFunction(String fn)
      Applies a native datastore function to the comparison value of the condition just added.
      Parameters:
      fn - the function expression to apply
      Returns:
      this builder
      Throws:
      IllegalStateException - if no condition has been added yet

    • staticValue

      public CpoWhereBuilder staticValue(String literal)
      Sets a literal, unescaped value on the condition just added, in place of a bound value.
      Parameters:
      literal - the static (literal) value text
      Returns:
      this builder
      Throws:
      IllegalStateException - if no condition has been added yet

    • build

      public CpoWhere build()
      Builds the CpoWhere tree assembled so far.

      If the chain was started with and(String, Comparison, Object)/or(String, Comparison, Object) (or a group overload) rather than where(), and it contains only that one top-level condition/group, the returned value is that condition/group itself rather than the internal wrapping container — so its own AND/OR renders directly, without a duplicated leading WHERE.

      Returns:
      the built where clause
      Throws:
      IllegalStateException - if no conditions were added