Module com.darkcollective.relix.function
Package com.darkcollective.relix.function

Interface Blocking

public interface Blocking
A two-argument function's promise about which pairs of values a comparison of its result could accept, in a form a join can index.

A join on F(left.x, right.y) >= t indexes one input under indexKeys(com.darkcollective.relix.value.Value) and, for each row of the other, looks up its probeKeys(com.darkcollective.relix.value.Value). Only the rows found that way are candidates, and every candidate is still confirmed by the join's own condition, so the keys only ever remove pairs from consideration and never decide a match.

The contract

For every pair of values a, b for which F(a, b) satisfies the comparison the blocking was offered for, both probeKeys(a) ∩ indexKeys(b) and probeKeys(b) ∩ indexKeys(a) are non-empty. The join picks which input to index, so the promise has to hold whichever argument ends up probing. Keys are compared with Object.equals(java.lang.Object).

A blocking may be loose. A key shared by pairs that fail the comparison costs a call to F. A missing key loses a row from the answer.

A NULL value is asked for its keys like any other. A function whose call is NULL whenever an argument is NULL — so the comparison is UNKNOWN and the pair is never kept — answers no keys for it. A value the blocking cannot read, NULL included, may be refused with an IllegalArgumentException: its row is then compared with every row of the other input, as it would be without a blocking, and the function itself decides what each of those pairs means.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static enum 
    Blocking.Bound
    How a call's result is compared with its threshold, read with the call on the left: F(a, b) >= t is Blocking.Bound.AT_LEAST.

  • Method Summary

    Modifier and Type
    Method
    Description
    Collection<?>
    indexKeys(Value value)
    The keys a value of the indexed input is filed under.
    Collection<?>
    probeKeys(Value value)
    The keys a value of the probing input looks up.

  • Method Details

    • indexKeys

      Collection<?> indexKeys(Value value)
      The keys a value of the indexed input is filed under.
      Parameters:
      value - an argument value, possibly NULL
      Returns:
      its keys; empty when no row of the other input could match it
      Throws:
      IllegalArgumentException - if the value is not one the function reads

    • probeKeys

      Collection<?> probeKeys(Value value)
      The keys a value of the probing input looks up.
      Parameters:
      value - an argument value, possibly NULL
      Returns:
      its keys; empty when no row of the other input could match it
      Throws:
      IllegalArgumentException - if the value is not one the function reads