jContractor

> Home
> Documentation
> Download
> Git Repository
> Project page
> Links

Hosted by
SourceForge

What is JaQuaL?

JaQuaL, the Java Quantification Library, provides predicate logic quantifiers for Java. JaQuaL provides high level abstractions for expressing boolean statements that apply to a collection of objects.

Using quantifiers

Construct jContractor Pattern and Description
ForAll ForAll.in(collection).ensure(assertion)
Ensures that all elements of a collection meet an assertion.
Exists Exists.in(collection).suchThat(assertion)
Ensures that at least one element of a collection meets an assertion.
Elements Elements.in(collection).suchThat(assertion)
Returns a java.util.Vector containing all the elements of a collection meet an assertion.
Implies Logical.implies(A, B)
Evaluates true if A and B are both true, or if A is false. The logical equivalent of !A || B.

Suppose that we have a graph data structure. A graph consists of a collection of nodes, each of which may be linked to other nodes. We would like to find out if there is any node that is not linked to any other. We could write this query using a loop: 

  java.util.Collection nodes;
  ...
  java.util.Iterator i = nodes.iterator();
  while (i.hasNext()) {
    if (((Node) i.next()).connections < 1)
      return false;
  }

However, JaQuaL offers a higher level of abstraction. We want to experss "for each node n in the graph, n is connected to at least one other". Using JaQuaL's ForAll quantifier, the experssion can be written like this: 

  java.util.Collection nodes;
  ...
  Assertion connected = new Assertion () {
     boolean eval (Object o) {
      return ((Node) o).connections >= 1;
     }
   };
  return ForAll.in(nodes).ensure(connected);

This new form uses just as many lines of code, but the logic is simpler. Most of the lines are used to define the connected assertion. Once defined, this assertion can be used any number of times. Several common assertions are provided with the library.

Using the implies operator

JaQuaL provides an implies operator as a static method of the Logical class, allowing programmers to write excodessions of the form A implies B, where A and B are of type boolean. Such an excodession is the logical equivalent of !A || B. Using jContractor syntax, the excodession would be written Logical.implies(A, B).

Using the standard assertions

Several commonly used assertions are provided with JaQuaL. These are

AssertionDescription
InstanceOf Asserts that objects are of a certain runtime type.
Equal Asserts that objects are equal. The programmer specifies if the comparison should be by reference or by value.
InRange Asserts that a number fall between minimum and maximum bounds.
Not Used to negate another assertion, as in new Not(new Equal(Foo)).

For example, it is very simple to ensure that every element of a Collection conforms to certain runtime type: 

ForAll.in(elements).ensure(new InstanceOf(Integer.class));

This type of assertion is very useful for controlling the type of objects that can be stored in a data structure.

Using Operators

The Assertion interface describes a test that evaluates to a boolean. An Assertion should not modify the elements of a collection. The Operator interface describes a transformation to apply to each element. An Operator can be used with the ForAll quantifier: 

  java.util.Collection elements;
  ...
  Operator initialize = new Operator () {
         boolean execute (Object o) {
          return ((Node) o).connections >= 1;
         }
       };
  ForAll.in(elements).execute(initialize);

For more information

More detailed information is available in the JaQuaL API.