Single-row function classes have no further requirement then provide a public static method.

The following sample single-row function simply computes a percentage value based on two number values.

This sample class provides a public static method by name computePercent to return a percentage value:

public class MyUtilityClass {
  public static double computePercent(double amount, double total) {
    return amount / total * 100;
  }
}

The class name of the class, the method name and the function name of the new single-row function must be added to the compiler configuration. The configuration shown below is XML however the same options are available through the configuration API:

<esper-configuration xmlns="http://www.espertech.com/schema/esper">
  <compiler>
    <plugin-singlerow-function name="percent" function-class="mycompany.MyUtilityClass" function-method="computePercent" />
  </compiler>
</esper-configuration>

Note that the function name and method name need not be the same.

The new single-row function is now ready to use in a statement:

select percent(fulfilled,total) from MyEvent

When selecting from a single stream, you may also pass wildcard to the single-row function and the function receives the underlying event:

select percent(*) from MyEvent

If the single-row function returns an object that provides further functions, you may chain function calls.

The following demonstrates a chained single-row function. The example assumes that a single-row function by name calculator returns an object that provides the add function which accepts two parameters:

select calculator().add(5, amount) from MyEvent

When your application registers a subquery, join or on-action query or executes a fire-and-forget query against a virtual data window the runtime interacts with the virtual data window. The interaction is a two-step process.

At time of deployment (once), the runtime uses the information the compiler collected by analyzing the EPL where-clause, if present. It then creates a list of hash-index and binary tree (btree, i.e. sorted) index properties. It passes the property names that are queried as well as the operators (i.e. =, >, range etc.) to the virtual data window. The virtual data window returns a lookup strategy object to the runtime.

At time of statement execution (repeatedly as triggered), the runtime uses that lookup strategy object to execute a lookup. It passes to the lookup all actual key values (hash, btree including ranges) to make fast and efficient lookup achievable.

To explain in detail, assume that your application creates a statement with a subquery as follows:

select (select * from MySampleWindow where key1 = 'A1') from OtherEvent

At the time of compilation of the statement above the compiler analyzes the statement. It determines that the subquery queries a virtual data window. It determines from the where-clause that the lookup uses property key1 and hash-equals semantics. The runtime then provides this information as part of VirtualDataWindowLookupContext passed to the getLookup method. Your application may inspect hash and btree properties and may determine the appropriate store access method to use.

The hash and btree property lookup information is for informational purposes, to enable fast and performant queries that return the smallest number of rows possible. Your implementation classes may use some or none of the information provided and may also instead return some or perhaps even all rows, as is practical to your implementation. The where-clause still remains in effect and gets evaluated on all rows that are returned by the lookup strategy.

Following the above example, the sub-query executes once when a OtherEvent event arrives. At time of execution the runtime delivers the string value A1 to the VirtualDataWindowLookup lookup implementation provided by your application. The lookup object queries the store and returns store rows as EventBean instances.

As a second example, consider an EPL join statement as follows:

select * from MySampleWindow, MyTriggerEvent where key1 = trigger1 and key2 = trigger2

The compiler analyzes the statement and the runtime passes to the virtual data window the information that the lookup occurs on properties key1 and key2 under hash-equals semantics. When a MyTriggerEvent arrives, it passes the actual value of the trigger1 and trigger2 properties of the current MyTriggerEvent to the lookup.

As a last example, consider a fire-and-forget query as follows:

select * from MySampleWindow key1 = 'A2' and value1 between 0 and 1000

The compiler analyzes the statement and the runtime passes to the virtual data window the lookup information. The lookup occurs on property key1 under hash-equals semantics and on property value1 under btree-open-range semantics. When your application executes the fire-and-forget query the runtime passes A2 and the range endpoints 0 and 1000 to the lookup.

For more information, please consult the JavaDoc API documentation for class VirtualDataWindow, VirtualDataWindowLookupContext or VirtualDataWindowLookupFieldDesc.

An aggregation function forge class is only used at compile-time and is responsible for the following functions:

Aggregation forge classes implement the interface AggregationFunctionForge:

public class MyConcatAggregationFunctionForge implements AggregationFunctionForge { ...

The compiler constructs one instance of the aggregation function forge class for each time the function is listed in a statement, however the compiler may decide to reduce the number of aggregation forge instances if it finds equivalent aggregations.

The aggregation function forge instance receives the aggregation function name via set setFunctionName method.

The sample concatenation function forge provides an empty setFunctionName method:

public void setFunctionName(String functionName) {
  // no action taken
}

An aggregation function forge must provide an implementation of the validate method that is passed a AggregationFunctionValidationContext validation context object. Within the validation context you find the result type of each of the parameters expressions to the aggregation function as well as information about constant values and data window use. Please see the JavaDoc API documentation for a comprehensive list of validation context information.

Since the example concatenation function requires string types it implements a type check:

public void validate(AggregationValidationContext validationContext) {
  if (validationContext.getParameterTypes().length != 1 || !JavaClassHelper.isTypeString(validationContext.getParameterTypes()[0])) {
    throw new IllegalArgumentException("Concat aggregation requires a single parameter of type String");
  }
}

In order for the compiler to validate the type returned by the aggregation function against the types expected by enclosing expressions, the getValueType must return the result type of any values produced by the aggregation function:

public EPTypeClass getValueType() {
  return EPTypePremade.STRING.getEPType();
}

Finally the forge implementation must provide a getAggregationFunctionMode method that returns information about the factory. The compiler uses this information to build the aggregation function factory.

public AggregationFunctionMode getAggregationFunctionMode() {
    // Inject a factory by using "new"
    InjectionStrategy injectionStrategy = new InjectionStrategyClassNewInstance(MyConcatAggregationFunctionFactory.class);
    
    // The managed mode means there is no need to write code that generates code
    AggregationFunctionModeManaged mode = new AggregationFunctionModeManaged();
    mode.setInjectionStrategyAggregationFunctionFactory(injectionStrategy);
        
    return mode;
}

An aggregation function factory class is responsible for the following functions:

Aggregation function factory classes implement the interface AggregationFunctionFactory:

public class MyConcatAggregationFunctionFactory implements AggregationFunctionFactory { ...

The runtime constructs the aggregation function factory at time of deployment.

The factory must provide a newAggregator method that returns instances of AggregationFunction. The runtime invokes this method for each new aggregation state to be allocated.

public AggregationFunction newAggregator() {
  return new MyConcatAggregationFunction();
}

An aggregation function class is responsible for the following functions:

Aggregation function classes implement the interface AggregationFunction:

public class MyConcatAggregationFunction implements AggregationFunction { ...

The class that provides the aggregation and implements AggregationFunction does not have to be threadsafe.

The constructor initializes the aggregation function:

public class MyConcatAggregationFunction implements AggregationFunction {
  private final static char DELIMITER = ' ';
  private StringBuilder builder;
  private String delimiter;

  public MyConcatAggregationFunction() {
    builder = new StringBuilder();
    delimiter = "";
  }
  ...

The enter method adds a datapoint to the current aggregation value. The example enter method shown below adds a delimiter and the string value to a string buffer:

public void enter(Object value) {
  if (value != null) {
    builder.append(delimiter);
    builder.append(value.toString());
    delimiter = String.valueOf(DELIMITER);
  }
}

Conversly, the leave method removes a datapoint from the current aggregation value. The example leave method removes from the string buffer:

public void leave(Object value) {
  if (value != null) {
    builder.delete(0, value.toString().length() + 1);
  }
}

Finally, the runtime obtains the current aggregation value by means of the getValue method:

public Object getValue() {
  return builder.toString();
}

For on-demand queries the aggregation function must support resetting its value to empty or start values. Implement the clear function to reset the value as shown below:

public void clear() {
  builder = new StringBuilder();
  delimiter = "";
}

You may use an inline class that is part of the EPL modules to provide an aggregation function. For more information on inline classes see Chapter 18, Inlined Classes. Using an inline class does not require any compiler configuration.

Specify the ExtensionAggregationFunction annotation on the class level of the AggregationFunctionForge implementation class and the name (the EPL aggregation function name). This annotation instructs the compiler that the inlined class exposes an aggregation function.

This sample EPL includes an inlined class by name ConcatAggForge that provides a concat aggregation function that concatenates:

inlined_class """
import com.espertech.esper.common.client.hook.aggfunc.*;
import com.espertech.esper.common.client.hook.forgeinject.*;
import com.espertech.esper.common.client.serde.*;
import java.io.*;
import com.espertech.esper.common.internal.epl.expression.core.*;
@ExtensionAggregationFunction(name="concat")
public class ConcatAggForge implements AggregationFunctionForge {
  public void validate(AggregationFunctionValidationContext validationContext) throws ExprValidationException {
    EPType paramType = validationContext.getParameterTypes()[0];
    if (paramType == EPTypeNull.INSTANCE || ((EPTypeClass) paramType).getType() != String.class) {
      throw new ExprValidationException("Invalid parameter type '" + paramType + "'");
    }
  }

  public EPTypeClass getValueType() {
    return new EPTypeClass(String.class);
  }

  public AggregationFunctionMode getAggregationFunctionMode() {
    AggregationFunctionModeManaged mode = new AggregationFunctionModeManaged();
    mode.setHasHA(true);
    mode.setSerde(ConcatAggSerde.class);
    mode.setInjectionStrategyAggregationFunctionFactory(new InjectionStrategyClassNewInstance(ConcatAggFactory.class.getName()));
    return mode;
  }

  public static class ConcatAggFactory implements AggregationFunctionFactory {
    public AggregationFunction newAggregator(AggregationFunctionFactoryContext ctx) {
      return new ConcatAggFunction();
    }
  }

  public static class ConcatAggFunction implements AggregationFunction {
    private final static String DELIMITER = ",";
    private StringBuilder builder;
    private String delimiter;

    public ConcatAggFunction() {
      super();
      builder = new StringBuilder();
      delimiter = "";
    }

    public void enter(Object value) {
      if (value != null) {
        builder.append(delimiter);
        builder.append(value.toString());
        delimiter = DELIMITER;
      }
    }

    public void leave(Object value) {
      if (value != null) {
        builder.delete(0, value.toString().length() + 1);
      }
    }
  
    public String getValue() {
      return builder.toString();
    }
  
    public void clear() {
      builder = new StringBuilder();
      delimiter = "";
    }
  }
  
  // the serializer-deserializer is only for high availability and is not required otherwise
  public static class ConcatAggSerde {
    public static void write(DataOutput output, AggregationFunction value) throws IOException {
      ConcatAggFunction agg = (ConcatAggFunction) value;
      output.writeUTF(agg.getValue());
    }

    public static AggregationFunction read(DataInput input) throws IOException {
      ConcatAggFunction concatAggFunction = new ConcatAggFunction();
      String current = input.readUTF();
      if (!current.isEmpty()) {
        concatAggFunction.enter(current);
      }
      return concatAggFunction;
    }
  }
}
""" 
select concat(personName) from PersonEvent

Only one ExtensionAggregationFunction annotation can be specified per class and the annotation is only for use with inlined classes. Using an inline class does not require any compiler configuration.

When using create inlined_class the runtime resolves dependencies on EPL objects at time of deployment (the same as for all EPL objects).

The aggregation function class name as well as the function name for the new aggregation function must be added to the compiler configuration. The configuration shown below is XML however the same options are available through the configuration API. Configuring the function is not necessary when using inlined classes as discussed before.

<esper-configuration xmlns="http://www.espertech.com/schema/esper">
  <compiler>
    <plugin-aggregation-function name="concat" 
      forge-class="com.espertech.esper.example.runtimeconfig.MyConcatAggregationFunctionFactory" />
  </compiler>
</esper-configuration>

The new aggregation function is now ready to use in a statement:

select concat(symbol) from StockTick#length(3)

Your plug-in aggregation function may accept multiple parameters. You must provide a different mode however:

    public AggregationFunctionMode getAggregationFunctionMode() {
        InjectionStrategy injectionStrategy = new InjectionStrategyClassNewInstance(SupportCountBackAggregationFunctionFactory.class);

        AggregationFunctionModeMultiParam multiParam = new AggregationFunctionModeMultiParam();
        multiParam.setInjectionStrategyAggregationFunctionFactory(injectionStrategy);
        
        return multiParam;
    }

For instance, assume an aggregation function rangeCount that counts all values that fall into a range of values. The EPL that calls this function and provides a lower and upper bounds of 1 and 10 is:

select rangeCount(1, 10, myValue) from MyEvent

The enter method of the plug-in aggregation function may look as follows:

public void enter(Object value)  {
  Object[] params = (Object[]) value;
  int lower = (Integer) params[0];
  int upper = (Integer) params[1];
  int val = (Integer) params[2];
  if ((val >= lower) && (val <= upper)) {
    count++;
  }
}

Your plug-in aggregation function may want to validate parameter types or may want to know which parameters are constant-value expressions. Constant-value expressions are evaluated only once by the runtime and could therefore be cached by your aggregation function for performance reasons. The runtime provides constant-value information as part of the AggregationValidationContext passed to the validate method.

When using AggregationFunctionModeManaged the runtime already takes care of filters.

When using AggregationFunctionModeMultiParam, the compiler takes the filter named parameter filter expression as a boolean-type value and the runtime provides the value to your enter method as the last value in the parameter array.

For instance, assume an aggregation function concat that receives a word value and that has a filter expression as parameters:

select concat(word, filter: word not like '%jim%') from MyWordEvent

The enter method of the plug-in aggregation function may look as follows:

public void enter(Object value)  {
  Object[] arr = (Object[]) value;
  Boolean pass = (Boolean) arr[1];
  if (pass != null && pass) {
    buffer.append(arr[0].toString());
  }
}

Your code can obtain the actual filter expression from the AggregationValidationContext that is passed to the validate method and that returns the named parameters via getNamedParameters.

When using AggregationFunctionModeManaged the runtime already takes care of distinct.

When using AggregationFunctionModeMultiParam your application code must determine and process distinct.

When the custom aggregation function returns an object as a return value, the EPL can use parenthesis and the dot-operator to invoke methods on the return value.

The following example assumes that the myAggregation custom aggregation function returns an object that has getValueOne and getValueTwo methods:

select (myAggregation(myValue)).getValueOne(),  (myAggregation(myValue)).getValueTwo() from MyEvent

Since the above EPL aggregates the same value, the runtime internally uses a single aggregation to represent the current value of myAggregation (and not two instances of the aggregation, even though myAggregation is listed twice).

An aggregation multi-function forge class is a compile-time class responsible for the following functions:

Aggregation multi-function factory classes implement the interface AggregationMultiFunctionForge:

public class CycleDetectorAggregationForge implements AggregationMultiFunctionForge { ...

The compiler constructs a single instance of the aggregation multi-function forge class that is shared for all aggregation function expressions in a statement that have one of the function names provided in the configuration object.

The compiler invokes the addAggregationFunction method at the time it compiles a statement. The method receives a declaration-time context object that provides the function name as well as additional information.

The sample Cycle-Detect factory class provides an empty addAggregationFunction method:

public void addAggregationFunction(AggregationMultiFunctionDeclarationContext declarationContext) {
    // provides an opportunity to inspect where used
}

The compiler invokes the validateGetHandler method at the time of expression validation. It passes a AggregationMultiFunctionValidationContext validation context object that contains actual parameters expressions. Please see the JavaDoc API documentation for a comprehensive list of validation context information.

The validateGetHandler method must return a handler object the implements the AggregationMultiFunctionHandler interface. Return a handler object for each aggregation function expression according to the aggregation function name and its parameters that are provided in the validation context.

The example cycledetect function takes two parameters that provide the cycle edge (from-account and to-account):

public AggregationMultiFunctionHandler validateGetHandler(AggregationMultiFunctionValidationContext validationContext) {
  if (validationContext.getParameterExpressions().length == 2) {
    fromExpression = validationContext.getParameterExpressions()[0];
    toExpression = validationContext.getParameterExpressions()[1];
  }
  return new CycleDetectorAggregationHandler(this, validationContext);
}

An aggregation multi-function handler class is a compile-time class that must implement the AggregationMultiFunctionHandler interface and is responsible for the following functions:

In the Cycle-Detect example, the class CycleDetectorAggregationHandler is the handler for all aggregation functions.

public class CycleDetectorAggregationHandler implements AggregationMultiFunctionHandler { ...

The getReturnType method provided by the handler instructs the compiler about the return type of each aggregation accessor. The class EPChainableType holds return type information.

In the Cycle-Detect example the cycledetected function returns a single boolean value. The cycleoutput returns a collection of vertices:

public EPChainableType getReturnType() {
    if (validationContext.getFunctionName().toLowerCase(Locale.ENGLISH).equals(CycleDetectorConstant.CYCLEOUTPUT_NAME)) {
        return EPChainableTypeHelper.collectionOfSingleValue((EPTypeClass) forge.getFromExpression().getForge().getEvaluationType());
    }
    return EPChainableTypeHelper.singleValue(Boolean.class);
}

The compiler invokes the getAggregationStateUniqueKey method to determine whether multiple aggregation function expressions in the same statement can share the same aggregation state or should receive different aggregation state instances.

The getAggregationStateUniqueKey method must return an instance of AggregationMultiFunctionStateKey. The compiler uses equals-semantics (the hashCode and equals methods) to determine whether multiple aggregation function share the state object. If the key object returned for each aggregation function by the handler is an equal key object then the compiler shares aggregation state between such aggregation functions for the same statement and context partition.

In the Cycle-Detect example the state is shared, which it achieves by simply returning the same key instance:

private static final AggregationMultiFunctionStateKey CYCLE_KEY = new AggregationMultiFunctionStateKey() {};

public AggregationMultiFunctionStateKey getAggregationStateUniqueKey() {
    return CYCLE_KEY;
}

The compiler invokes the getStateMode method to obtain an instance of AggregationMultiFunctionStateMode. The state mode is responsible to obtaining and configuring an aggregation state factory instance at time of deployment.

In the Cycle-Detect example the method passes the expression evaluators providing the from-account and to-account expressions to the state factory:

public AggregationMultiFunctionStateMode getStateMode() {
    AggregationMultiFunctionStateModeManaged managed = new AggregationMultiFunctionStateModeManaged();
    InjectionStrategyClassNewInstance injection = new InjectionStrategyClassNewInstance(CycleDetectorAggregationStateFactory.class);
    injection.addExpression("from", forge.getFromExpression());
    injection.addExpression("to", forge.getToExpression());
    managed.setInjectionStrategyAggregationStateFactory(injection);
    return managed;
}

The compiler invokes the getAccessorMode method to obtain an instance of AggregationMultiFunctionAccessorMode. The accessor mode is responsible to obtaining and configuring an accessor factory instance at time of deployment.

The getAccessorMode method provides information about the accessor factories according to whether the aggregation function name is cycledetected or cycleoutput:

public AggregationMultiFunctionAccessorMode getAccessorMode() {
    Class accessor;
    if (validationContext.getFunctionName().toLowerCase(Locale.ENGLISH).equals(CycleDetectorConstant.CYCLEOUTPUT_NAME)) {
        accessor = CycleDetectorAggregationAccessorOutputFactory.class;
    }
    else {
        accessor = CycleDetectorAggregationAccessorDetectFactory.class;
    }
    AggregationMultiFunctionAccessorModeManaged managed = new AggregationMultiFunctionAccessorModeManaged();
    InjectionStrategyClassNewInstance injection = new InjectionStrategyClassNewInstance(accessor);
    managed.setInjectionStrategyAggregationAccessorFactory(injection);
    return managed;
}

An aggregation multi-function state factory class must implement the AggregationMultiFunctionStateFactory interface and is responsible for the following functions:

The runtime invokes the newState method to obtain a new aggregation state instance before applying aggregation state. If using group by in your statement, the runtime invokes the newState method to obtain a state holder for each group.

In the Cycle-Detect example, the class CycleDetectorAggregationStateFactory is the state factory for all aggregation functions:

public class CycleDetectorAggregationStateFactory implements AggregationMultiFunctionStateFactory {

    private ExprEvaluator from;
    private ExprEvaluator to;

    public AggregationMultiFunctionState newState(AggregationMultiFunctionStateFactoryContext ctx) {
        return new CycleDetectorAggregationState(this);
    }

    public void setFrom(ExprEvaluator from) {
        this.from = from;
    }

    public void setTo(ExprEvaluator to) {
        this.to = to;
    }

    public ExprEvaluator getFrom() {
        return from;
    }

    public ExprEvaluator getTo() {
        return to;
    }
}

An aggregation multi-function state class must implement the AggregationMultiFunctionState interface and is responsible for the following functions:

In the Cycle-Detect example, the class CycleDetectorAggregationState is the state for all aggregation functions. Please review the example for more information.

An aggregation multi-function accessor factory class must implement the AggregationMultiFunctionAccessorFactory interface and is responsible for the following functions:

In the Cycle-Detect example, the class CycleDetectorAggregationAccessorDetectFactory returns the accessor like so:

public class CycleDetectorAggregationAccessorDetectFactory implements AggregationMultiFunctionAccessorFactory {
    public AggregationMultiFunctionAccessor newAccessor(AggregationMultiFunctionAccessorFactoryContext ctx) {
        return new CycleDetectorAggregationAccessorDetect();
    }
}

An aggregation multi-function accessor class must implement the AggregationMultiFunctionAccessor interface and is responsible for the following functions:

In the Cycle-Detect example, the class CycleDetectorAggregationAccessorDetect returns state for the cycledetected aggregation function and the CycleDetectorAggregationAccessorOutput returns the state for the cycleoutput aggregation function.

An aggregation multi-function configuration can receive one or multiple function names. You must also set a factory class name.

The sample XML snippet below configures an aggregation multi-function that is associated with the function names func1 and func2.

<esper-configuration xmlns="http://www.espertech.com/schema/esper">
  <compiler>
    <plugin-aggregation-multifunction 
        function-names="cycledetected,cycleoutput"
        forge-class="com.espertech.esper.example.cycledetect.CycleDetectorAggregationFactory"/>
  </compiler>
</esper-configuration>

The next example uses the configuration API to register the same:

String[] functionNames = new String[] {"cycledetected", "cycleoutput"};
ConfigurationPlugInAggregationMultiFunction config = new ConfigurationPlugInAggregationMultiFunction(functionNames, CycleDetectorAggregationFactory.class.getName());
Configuration configuration = new Configuration();
configuration.getCompiler().addPlugInAggregationMultiFunction(config);

You may use an inline class that is part of the EPL modules to provide an aggregation multi-function. For more information on inline classes see Chapter 18, Inlined Classes. Using an inline class does not require any compiler configuration.

Specify the ExtensionAggregationMultiFunction annotation on the class level of the AggregationMultiFunctionForge implementation class and the function names (names of states and aggregation methods). This annotation instructs the compiler that the inlined class exposes an aggregation multi-function.

This sample EPL includes an inlined class by name TrieAggForge that uses a Trie data structures to store person names. A trie is a tree-like data structure whose nodes store the letters of an alphabet. Here, the Trie stores person names. The implementation uses the Trie provided by the Apache Commons Collections library.

The following sample EPL uses the Trie to store persons by person name and return a prefix-map, which is a sorted map of all persons that have the same prefix:

// The PersonEvent provides a person name and person id			
@public @buseventtype create schema PersonEvent(name string, id string);

// This provides the aggregation multi-function 
create inlined_class """
import com.espertech.esper.common.client.*;
import com.espertech.esper.common.client.type.*;
import com.espertech.esper.common.client.hook.aggmultifunc.*;
import com.espertech.esper.common.client.hook.forgeinject.*;
import com.espertech.esper.common.internal.epl.expression.core.*;
import com.espertech.esper.common.internal.rettype.*;
import com.espertech.esper.common.internal.epl.agg.core.*;
import org.apache.commons.collections4.Trie;
import org.apache.commons.collections4.trie.PatriciaTrie;
import java.util.*;
import java.util.function.*;

// We have 3 function names: 
// - "trieState" for use with create-table to hold the Trie
// - "trieEnter" for entering person events into the Trie by person name, for use with into-table aggregation
// - "triePrefixMap" for returning a prefix map of all persons with the same prefix as provided by its parameter
@ExtensionAggregationMultiFunction(names="trieState,trieEnter,triePrefixMap")
/**
 * The trie aggregation forge is the entry point for providing the multi-function aggregation.
 */
public class TrieAggForge implements AggregationMultiFunctionForge {
  public AggregationMultiFunctionHandler validateGetHandler(AggregationMultiFunctionValidationContext validationContext) {
    String name = validationContext.getFunctionName();
    if (name.equals("trieState")) {
      return new TrieAggHandlerTrieState();
    } else if (name.equals("trieEnter")) {
      return new TrieAggHandlerTrieEnter(validationContext.getParameterExpressions());
    } else if (name.equals("triePrefixMap")) {
      return new TrieAggHandlerTriePrefixMap();
    }
    throw new IllegalStateException("Unrecognized name '" + name + "' for use with trie");
  }
  
  /**
   * This handler handles the "trieState"-type table column, for use with create-table.
   */
  public static class TrieAggHandlerTrieState implements AggregationMultiFunctionHandler {
    public EPChainableType getReturnType() {
      return EPChainableTypeHelper.singleValue(Trie.class);
    }

    public AggregationMultiFunctionStateKey getAggregationStateUniqueKey() {
      return new AggregationMultiFunctionStateKey() {};
    }

    public AggregationMultiFunctionStateMode getStateMode() {
      InjectionStrategyClassNewInstance injection = new InjectionStrategyClassNewInstance(TrieAggStateFactory.class);
      return new AggregationMultiFunctionStateModeManaged(injection);
    }

    public AggregationMultiFunctionAccessorMode getAccessorMode() {
      // accessor that returns the trie itself
      InjectionStrategyClassNewInstance injection = new InjectionStrategyClassNewInstance(TrieAggAccessorFactory.class);
      return new AggregationMultiFunctionAccessorModeManaged(injection);
    }

    public AggregationMultiFunctionAgentMode getAgentMode() {
      throw new UnsupportedOperationException("Trie aggregation access is only by the 'triePrefixMap' method");
    }

    public AggregationMultiFunctionAggregationMethodMode getAggregationMethodMode(AggregationMultiFunctionAggregationMethodContext ctx) {
      throw new UnsupportedOperationException("Trie aggregation access is only by the 'triePrefixMap' method");
    }
  }
  
  /**
   * This handler handles the "trieEnter"-operation that updates trie state, for use with into-table aggregation
   */
  public static class TrieAggHandlerTrieEnter implements AggregationMultiFunctionHandler {
    private final ExprNode[] parameters;
    
    public TrieAggHandlerTrieEnter(ExprNode[] parameters) {
      this.parameters = parameters;
    }

    public EPChainableType getReturnType() {
      return EPChainableTypeHelper.singleValue(Trie.class); // we return the Trie itself
    }

    public AggregationMultiFunctionStateKey getAggregationStateUniqueKey() {
      throw new UnsupportedOperationException("Not a trie state");
    }

    public AggregationMultiFunctionStateMode getStateMode() {
      throw new UnsupportedOperationException("Not a trie state");
    }

    public AggregationMultiFunctionAccessorMode getAccessorMode() {
      // accessor that returns the trie itself
      InjectionStrategyClassNewInstance injection = new InjectionStrategyClassNewInstance(TrieAggAccessorFactory.class);
      return new AggregationMultiFunctionAccessorModeManaged(injection);
    }

    public AggregationMultiFunctionAgentMode getAgentMode() {
      if (parameters.length != 1 || ((EPTypeClass) parameters[0].getForge().getEvaluationType()).getType() != String.class) {
        throw new IllegalArgumentException("Requires a single parameter returing a string value");
      }
      InjectionStrategyClassNewInstance injection = new InjectionStrategyClassNewInstance(TrieAggAgentFactory.class);
      injection.addExpression("keyExpression", parameters[0]);
      return new AggregationMultiFunctionAgentModeManaged(injection);
    }

    public AggregationMultiFunctionAggregationMethodMode getAggregationMethodMode(AggregationMultiFunctionAggregationMethodContext ctx) {
      throw new UnsupportedOperationException("Trie aggregation access is only by the 'triePrefixMap' method");
    }
  }
  
  /**
   * This handler handles the "triePrefixMap" accessor for returning a prefix map of same-prefix person events
   */
  public static class TrieAggHandlerTriePrefixMap implements AggregationMultiFunctionHandler {
    public EPChainableType getReturnType() {
      return EPChainableTypeHelper.singleValue(Map.class);
    }
    
    public AggregationMultiFunctionStateKey getAggregationStateUniqueKey() {
      throw new UnsupportedOperationException("Not implemented for 'triePrefixMap' trie method");
    }

    public AggregationMultiFunctionStateMode getStateMode() {
      throw new UnsupportedOperationException("Not implemented for 'triePrefixMap' trie method");
    }

    public AggregationMultiFunctionAccessorMode getAccessorMode() {
      throw new UnsupportedOperationException("Not implemented for 'triePrefixMap' trie method");
    }

    public AggregationMultiFunctionAgentMode getAgentMode() {
      throw new UnsupportedOperationException("Not implemented for 'triePrefixMap' trie method");
    }

    public AggregationMultiFunctionAggregationMethodMode getAggregationMethodMode(AggregationMultiFunctionAggregationMethodContext ctx) {
      if (ctx.getParameters().length != 1 || ((EPTypeClass) ctx.getParameters()[0].getForge().getEvaluationType()).getType() != String.class) {
        throw new IllegalArgumentException("Requires a single parameter returning a string value");
      }
      InjectionStrategyClassNewInstance injection = new InjectionStrategyClassNewInstance(TrieAggMethodFactoryPrefixMap.class);
      injection.addExpression("keyExpression", ctx.getParameters()[0]);
      return new AggregationMultiFunctionAggregationMethodModeManaged(injection);
    }
  }
  
  /**
   * The agent state factory is responsible for producing a state holder that holds the trie state
   */
  public static class TrieAggStateFactory implements AggregationMultiFunctionStateFactory {
    public AggregationMultiFunctionState newState(AggregationMultiFunctionStateFactoryContext ctx) {
      return new TrieAggState();
    }
  }
  
  /**
   * The agent state is the state holder that holds the trie state
   */
  public static class TrieAggState implements AggregationMultiFunctionState {
    private final Trie<String, List<Object>> trie = new PatriciaTrie<>();
    
    public void applyEnter(EventBean[] eventsPerStream, ExprEvaluatorContext exprEvaluatorContext) {
      throw new UnsupportedOperationException("Not used since the agent updates the table");
    }
    
    public void applyLeave(EventBean[] eventsPerStream, ExprEvaluatorContext exprEvaluatorContext) {
      throw new UnsupportedOperationException("Not used since the agent updates the table");
    }
    
    public void clear() {
      trie.clear();
    }

    public void add(String key, Object underlying) {
      List<Object> existing = (List<Object>) trie.get(key);
      if (existing != null) {
        existing.add(underlying);
        return;
      }
      List<Object> events = new ArrayList<>(2);
      events.add(underlying);
      trie.put(key, events);
    }
    
    public void remove(String key, Object underlying) {
      List<Object> existing = (List<Object>) trie.get(key);
      if (existing != null) {
        existing.remove(underlying);
        if (existing.isEmpty()) {
          trie.remove(key);
        }
      }
    }
  }
  
  /**
   * The accessor factory is responsible for producing an accessor that returns the result of the trie table column when accessed without an aggregation method
   */
  public static class TrieAggAccessorFactory implements AggregationMultiFunctionAccessorFactory {
    public AggregationMultiFunctionAccessor newAccessor(AggregationMultiFunctionAccessorFactoryContext ctx) {
      return new TrieAggAccessor();
    }
  }
  
  /**
   * The accessor returns the result of the trie table column when accessed without an aggregation method
   */
  public static class TrieAggAccessor implements AggregationMultiFunctionAccessor {
    // This is the value return when just referring to the trie table column by itself without a method name such as "prefixMap".
    public Object getValue(AggregationMultiFunctionState state, EventBean[] eventsPerStream, boolean isNewData, ExprEvaluatorContext exprEvaluatorContext) {
      TrieAggState trie = (TrieAggState) state;
      return trie.trie;
    }
  }
  
  /**
   * The agent factory is responsible for producing an agent that handles all changes to the trie table column.
   */
  public static class TrieAggAgentFactory implements AggregationMultiFunctionAgentFactory {
    private ExprEvaluator keyExpression;
    
    public void setKeyExpression(ExprEvaluator keyExpression) {
      this.keyExpression = keyExpression;
    }
    
    public AggregationMultiFunctionAgent newAgent(AggregationMultiFunctionAgentFactoryContext ctx) {
      return new TrieAggAgent(this);
    }
  }
  
  /**
   * The agent is responsible for all changes to the trie table column.
   */
  public static class TrieAggAgent implements AggregationMultiFunctionAgent {
    private final TrieAggAgentFactory factory;
    
    public TrieAggAgent(TrieAggAgentFactory factory) {
      this.factory = factory;
    }
    
    public void applyEnter(EventBean[] eventsPerStream, ExprEvaluatorContext exprEvaluatorContext, AggregationRow row, int column) {
      String key = (String) factory.keyExpression.evaluate(eventsPerStream, true, exprEvaluatorContext);
      TrieAggState trie = (TrieAggState) row.getAccessState(column);
      trie.add(key, eventsPerStream[0].getUnderlying());
    }

    public void applyLeave(EventBean[] eventsPerStream, ExprEvaluatorContext exprEvaluatorContext, AggregationRow row, int column) {
      String key = (String) factory.keyExpression.evaluate(eventsPerStream, false, exprEvaluatorContext);
      TrieAggState trie = (TrieAggState) row.getAccessState(column);
      trie.remove(key, eventsPerStream[0].getUnderlying());
    }
  }
  
  /**
   * The aggregation method factory is responsible for producing an aggregation method for the "trie" return result of the trie table column.
   */
  public static class TrieAggMethodFactoryTrieColumn implements AggregationMultiFunctionAggregationMethodFactory {
    public AggregationMultiFunctionAggregationMethod newMethod(AggregationMultiFunctionAggregationMethodFactoryContext context) {
      return new AggregationMultiFunctionAggregationMethod() {
        public Object getValue(int aggColNum, AggregationRow row, EventBean[] eventsPerStream, boolean isNewData, ExprEvaluatorContext exprEvaluatorContext) {
          TrieAggState trie = (TrieAggState) row.getAccessState(aggColNum);
          return trie.trie;
        }
      };
    }
  }
  
  /**
   * The aggregation method factory is responsible for producing an aggregation method for the "triePrefixMap" expression of the trie table column.
   */
  public static class TrieAggMethodFactoryPrefixMap implements AggregationMultiFunctionAggregationMethodFactory {
    private ExprEvaluator keyExpression;
    
    public void setKeyExpression(ExprEvaluator keyExpression) {
      this.keyExpression = keyExpression;
    }

    public AggregationMultiFunctionAggregationMethod newMethod(AggregationMultiFunctionAggregationMethodFactoryContext context) {
      return new TrieAggMethodPrefixMap(this);
    }
  }
  
  /**
   * The aggregation method is responsible for the "triePrefixMap" expression result of the trie table column.
   */
  public static class TrieAggMethodPrefixMap implements AggregationMultiFunctionAggregationMethod {
    private final TrieAggMethodFactoryPrefixMap factory;
    
    public TrieAggMethodPrefixMap(TrieAggMethodFactoryPrefixMap factory) {
      this.factory = factory;
    }
    
    public Object getValue(int aggColNum, AggregationRow row, EventBean[] eventsPerStream, boolean isNewData, ExprEvaluatorContext exprEvaluatorContext) {
      String key = (String) factory.keyExpression.evaluate(eventsPerStream, false, exprEvaluatorContext);
      TrieAggState trie = (TrieAggState) row.getAccessState(aggColNum);
      return trie.trie.prefixMap(key);
    }
  }
}
""";

// We use a table to store the Trie. The Trie is effectively a Trie<String, List<PersonEvent>> holding a list of person events in branch and leaf nodes.
@name('table') create table TableWithTrie(nameTrie trieState(string));

// We aggregate directly into the table using the person name as the Trie key and the event as value
@Priority(1) into table TableWithTrie select trieEnter(name) as nameTrie from PersonEvent;

// For each person output the prefix map, a sorted map (SortedMap<String, List<PersonEvent>>) with the same prefixes as the person name
@Priority(0) @name('s0') select TableWithTrie.nameTrie.triePrefixMap(name) from PersonEvent;

Only one ExtensionAggregationMultiFunction annotation can be specified per class and the annotation is only for use with inlined classes. Using an inline class does not require any compiler configuration.

When using create inlined_class the runtime resolves dependencies on EPL objects at time of deployment (the same as for all EPL objects).

The runtime shares an AggregationAccessor instance between threads. The accessor should be designed stateless and should not use any locking of any kind in the AggregationAccessor implementation unless your implementation uses other state. Since the runtime passes an aggregation state instance to the accessor it is thread-safe as long as it relies only on the aggregation state passed to it.

The runtime does not share an AggregationState instance between threads. There is no need to use locking of any kind in the AggregationState implementation unless your implementation uses other state.

Tables allow columns to hold aggregation state including the state for multi-function aggregations. This section provides API pointers.

When a statement accesses a table column that declares aggregation state of a multi-function aggregation, the AggregationMultiFunctionValidationContext contains an optionalTableColumnRead field that provides information about the table column.

To find out the statement type, such as to determine whether the current statement is a create-table statement, use context.getValidationContext().getExprEvaluatorContext().getStatementType().

To find out whether the statement aggregates into a table, use context.getValidationContext().getIntoTableName() that returns the table name or null if not aggregating into a table.

The compiler uses AggregationMultiFunctionStateKey to determine whether an aggregation function listed with into table is compatible with the aggregation type that a table column declares. The equals method of the object must return true for compatible and false for incompatible.

Your handler may provide a agent and aggregation method modes. Please follow the JavaDoc or inspect the regression test suite.

The filter expression is passed to you in PlugInAggregationMultiFunctionValidationContext as part of getNamedParameters under the name filter. When use with tables the filter expression is part of PlugInAggregationMultiFunctionAgentContext.

Your application must invoke the filter expression as the runtime does not evaluate the filter expression for you. For example:

ExprEvaluator filterEval = validationContext.getNamedParameters().get("filter").get(0).getExprEvaluator();

public void applyEnter(EventBean[] eventsPerStream, ExprEvaluatorContext exprEvaluatorContext) {
  Boolean pass = (Boolean) filterEval.evaluate(eventsPerStream, true, exprEvaluatorContext); // note: pass "false" for applyLeave
  if (pass != null && pass) {
    Object value = valueEval.evaluate(eventsPerStream, true, exprEvaluatorContext); // note: pass "false" for applyLeave
    // do something
  }
}