1. Expressions

op4j is used for implementing (mainly) auxiliary code as expressions. Expressions look like this:

output = Op.on(input).[ACTION].[ACTION]...[ACTION].get();
function = Fn.on(inputType).[ACTION].[ACTION]...[ACTION].get();

They start by calling either the Op.on(...) or the Fn.on(...) static methods, which receive the input object (Op.on) or input type (Fn.on) as a parameter. There are some variations of the "on(...)" methods with slightly different names, which are explained in the documentation sections for the specific types of input.

• Expressions starting with Op.on are called Op expressions or Operation expressions. They act on a specific input object/s and perform a set of chained actions on it before returning a result.

  String[] values = ...;
  List<String> upperStrs = Op.on(values).toList().map(FnString.toUpperCase()).get();
  

• Expressions starting with Fn.on are called Fn expressions or Function expressions. They allow the definition of functions as a set of chained actions of exactly the same kind as op expressions, returning as a result an executable Function object equivalent to the defined chain.

  Function<String[],List<String>> upperStrsFunc = 
      Fn.onArrayOf(Types.STRING).map(FnString.toUpperCase()).toList().get();
  ...
  String[] values = ...;
  List<String> upperStrs = upperStrsFunc.execute(values);
  

Expressions end with get(), which returns the output (op expressions) or the defined function (fn expressions).

2. Actions

An action is a chained method executed in an expression, between the "on(...)" and the "get()" methods.

For example:

String[] values = ...;
List<Integer> intValueList = Op.on(values).toList().forEach().exec(FnString.toInteger()).get();

Here we can see three chained actions: toList, forEach and exec.

3. Operators

Operators are the objects representing each of the states of an expression. They are the objects resulting from the execution of actions (or on(...)).

• Op.on(...) and Fn.on(...) return operators.
• Each action method chained after these "on" methods returns a different operator.
• get() methods stop the action/operator chains and return results.

Looking again at our example:

List<Integer> intValueList = Op.on(values).toList().forEach().exec(FnString.toInteger()).get();

We can explain it as:

1. The on(...) method returns operator1.
2. The toList() method (or action) is called on operator1, which returns operator2.
3. The forEach() method (or action) is called on operator2, which returns operator3.
4. The exec(...) method (or action) is called on operator3, which returns operator4.
5. The get() method is called on operator4, which returns the expression result.

All operators are immutable. When an action is executed on them, they return a new and different operator representing the new state, instead of changing their own internal state.

4. Targets

The "target" or "targets" of an operator are the objects that the operator's actions (methods) will execute on.

As operators are linked together by actions in the shape of chains, an operator's target is the result of the execution of an action on the previous operator.

Following the previous example:

List<Integer> intValueList = Op.on(values).toList().forEach().exec(FnString.toInteger()).get();

1. The on(...) method creates operator1.
   • Operator1: TARGET = input (a String[] object called values)
2. The toList() method (or action) is called on operator1, which returns operator2.
   • Operator2: TARGET = a List<String> object created from the original array.
3. The forEach() method (or action) is called on operator2, which returns operator3.
   • Operator3: TARGET = each of the elements of List<String> (an iterating list)
4. The exec(...) method (or action) is called on operator3, which returns operator4.
   • Operator4: TARGET (for each execution) = one of the elements of List<String>
5. The get() method is called on operator4, which returns the expression result (List<Integer>).

5. The operators as a state machine

The behaviour of operators in op4j allows the operator system to be thought of as a state machine where operators represent states, and actions represent state changes. Thanks to this:

Each operator offers only the actions (methods) that can effectively be executed in the specific state it represents.

What does this mean? It means for example that, if you execute Op.on(...) on a Set<String> object, you will be offered a forEach() method for iterating it (because Sets can be iterated), but you will not be offered a distinct() method for removing duplicates as would have been offered if your object was a List (because Sets can never contain duplicates).

Another example, the following sentence will not compile:

List<Integer> intValueList = Op.on(values).forEach().forEach()...

After the first forEach(), you are already iterating the input array, so there is no point in iterating it again!

Flowing code: the advantage of the state machine

op4j's state machine makes it easy for you to create your expressions by just using the Content assist feature in your IDE (usually by pressing Ctrl+Space after ".") and going through the list of actions (methods) available to you at a specific point in the chain, selecting the one that fits your needs.

6. Functions

Functions are a key concept in op4j. A quick definition:

An op4j function is an object of a class which implements the org.op4j.functions.IFunction interface

The IFunction interface is defined as IFunction<T,R>, being T the type of the function input, and R the type of the function result.

IFunction only has one method, R execute(T input, ExecCtx ctx), which receives a T object and a context (an internal structure containing iteration information) and returns an R object.

All op4j predefined functions, as well as all functions returned by Fn.on expressions extend a special implementation of IFunction<T,R> called Function<T,R>. This class adds a simpler R execute(T input) method, useful for the isolated (not inside an expression) execution of a Function object.

function = Fn.on(...)...get();
output = function.execute(input); 

7. Types

op4j is tightly integrated with the javaRuntype project, which in fact was born as a part of op4j (later separated as a project on its own during development).

javaRuntype offers a runtime type system which fits perfectly the need op4j has for being able to specify types (for example, of a list's elements) including their type parameters (the so-called generics), which is something not covered by the standard java.lang.Class objects.

javaRuntype's Type objects are extremely easy to use, and are created and managed by means of the org.javaruntype.type.Types class, which in fact contains many useful predefined constants for the most used types.