Module io.ebean.api
Package io.ebean

Class Pairs

java.lang.Object
io.ebean.Pairs
public final class Pairs extends Object
Holds a list of value object pairs.

This feature is to enable use of L2 cache with complex natural keys with findList() queries in cases where the IN clause is not a single property but instead a pair of properties.

These queries can have predicates that can be translated into a list of complex natural keys such that the L2 cache can be hit with these keys to obtain some or all of the beans from L2 cache rather than the DB. 



   // where a bean is annotated with a complex
   // natural key made of several properties
   @Cache(naturalKey = {"store","code","sku"})


   Pairs pairs = new Pairs("sku", "code");
   pairs.add("sj2", 1000);
   pairs.add("sj2", 1001);
   pairs.add("pf3", 1000);

   List<OCachedNatKeyBean3> list = DB.find(OCachedNatKeyBean3.class)
   .where()
   .eq("store", "def")
   .inPairs(pairs)       // IN clause with 'pairs' of values
   .order("sku desc")

   // query expressions cover the natural key properties
   // so we can choose to hit the L2 bean cache if we want
   .setUseCache(true)
   .findList();

Important implementation Note

When binding many pairs of values we want to be able to utilise a DB index (as this type of query usually means the pairs are a unique key/index or part of a unique key/index and highly selective). Currently we know we can do this on any DB that supports expression/formula based indexes. using a DB string concatenation formula

This means, the implementation converts the list of pairs into a list of strings via concatenation and we use a DB concatenation formula to match. We see SQL like: 

sql

   ...
   where t0.store = ?  and (t0.sku||'-'||t0.code) in (?, ? )

   // bind values like: "sj2-1000", "pf3-1000"

We often create a DB expression index to match the DB concat formula like: 

sql

   create index ix_name on table_name (sku || '-' || code);

  • Constructor Details

    • Pairs

      public Pairs(String property0, String property1)
      Create with 2 property names.
      Parameters:
      property0 - The property of the first value
      property1 - The property of the second value

  • Method Details

    • add

      public Pairs add(Object a, Object b)
      Add a pair of value objects.

      Both values are expected to be immutable with equals and hashCode implementations.

      Parameters:
      a - Value of the first property
      b - Value of the second property

    • property0

      public String property0()
      Return the first property name.

    • property1

      public String property1()
      Return the second property name.

    • entries

      public List<Pairs.Entry> entries()
      Return all the value pairs.

    • concatSeparator

      public String concatSeparator()
      Return the separator character used with DB varchar concatenation to combine the 2 values.

    • concatSeparator

      public Pairs concatSeparator(String concatSeparator)
      Set the separator character used with DB varchar concatenation to combine the 2 values.

    • concatSuffix

      public String concatSuffix()
      Return a suffix used with DB varchar concatenation to combine the 2 values.

    • concatSuffix

      public Pairs concatSuffix(String concatSuffix)
      Add a suffix used with DB varchar concatenation to combine the 2 values.

    • toString

      public String toString()
      Overrides:
      toString in class Object