anchor.diff:  
   [source,java,linenums]
   ----
  -List<Task> tasks = taskService.createTaskQuery()
  -    .taskAssignee("kermit")
  -    .processVariableValueEquals("orderId", "0815")
  -    .orderByDueDate().asc()
  +List<DmnDeployment> dmnDeployments = dmnRepositoryService.createDeploymentQuery()
  +    .deploymentNameLike("deployment%")
  +    .orderByDeployTime()
       .list();
   ----
   
  -Sometimes you need more powerful queries, e.g. queries using an OR operator or restrictions you cannot express using the Query API. For these cases, we introduced native queries, which allow you to write your own SQL queries. The return type is defined by the Query object you use and the data is mapped into the correct objects, e.g. Task, ProcessInstance, Execution, etc.... Since the query will be fired at the database you have to use table and column names as they are defined in the database; this requires some knowledge about the internal data structure and it is recommended to use native queries with care. The table names can be retrieved via the API to keep the dependency as small as possible.
  -
  -[source,java,linenums]
  -----
  -List<Task> tasks = taskService.createNativeTaskQuery()
  -  .sql("SELECT count(*) FROM " + managementService.getTableName(Task.class) + " T WHERE T.NAME_ = #{taskName}")
  -  .parameter("taskName", "gonzoTask")
  -  .list();
  -
  -long count = taskService.createNativeTaskQuery()
  -  .sql("SELECT count(*) FROM " + managementService.getTableName(Task.class) + " T1, "
  -    + managementService.getTableName(VariableInstanceEntity.class) + " V1 WHERE V1.TASK_ID_ = T1.ID_")
  -  .count();
  +Sometimes you need more powerful queries, e.g. queries using an OR operator or restrictions you cannot express using the Query API. For these cases, we introduced native queries, which allow you to write your own SQL queries. The return type is defined by the Query object you use and the data is mapped into the correct objects, e.g. Deployment, ProcessInstance, Execution, etc.... Since the query will be fired at the database you have to use table and column names as they are defined in the database; this requires some knowledge about the internal data structure and it is recommended to use native queries with care. The table names can be retrieved via the API to keep the dependency as small as possible.
  +
  +[source,java,linenums]
  +----
  +
  +long count = dmnRepositoryService.createNativeDeploymentQuery()
  +    .sql("SELECT count(*) FROM " + dmnManagementService.getTableName(DmnDeploymentEntity.class) + " D1, "
  +        + dmnManagementService.getTableName(DecisionTableEntity.class) + " D2 "
  +        + "WHERE D1.ID_ = D2.DEPLOYMENT_ID_ "
  +        + "AND D1.ID_ = #{deploymentId}")
  +    .parameter("deploymentId", deployment.getId())
  +    .count();
   ----
   
   [[apiVariables]]
   
  -=== Variables
  -
  -Every process instance needs and uses data to execute the steps it exists of. In Flowable, this data is called _variables_, which are stored in the database. Variables can be used in expressions (for example to select the correct outgoing sequence flow in an exclusive gateway), in java service tasks when calling external services (for example to provide the input or store the result of the service call), etc.
  -
  -A process instance can have variables (called _process variables_), but also _executions_ (which are specific pointers to where the process is active) and user tasks can have variables. A process instance can have any number of variables. Each variable is stored in a row in the _ACT_RU_VARIABLE_ database table.
  -
  -Any of the _startProcessInstanceXXX_ methods have an optional parameters to provide the variables when the process instance is created and started. For example, from the _RuntimeService_:
  -
  -[source,java,linenums]
  -----
  -ProcessInstance startProcessInstanceByKey(String processDefinitionKey, Map<String, Object> variables);
  -----
  -
  -Variables can be added during process execution. For example (_RuntimeService_):
  -
  -[source,java,linenums]
  -----
  -void setVariable(String executionId, String variableName, Object value);
  -void setVariableLocal(String executionId, String variableName, Object value);
  -void setVariables(String executionId, Map<String, ? extends Object> variables);
  -void setVariablesLocal(String executionId, Map<String, ? extends Object> variables);
  -----
  -
  -Note that variables can be set _local_ for a given execution (remember a process instance consists of a tree of executions). The variable will only be visible on that execution, and not higher in the tree of executions. This can be useful if data shouldn't be propagated to the process instance level, or the variable has a new value for a certain path in the process instance (for example when using parallel paths).
  -
  -Variables can also be fetched again, as shown below. Note that similar methods exist on the _TaskService_. This means that tasks, like executions, can have local variables that are 'alive' just for the duration of the task.
  -
  -[source,java,linenums]
  -----
  -Map<String, Object> getVariables(String executionId);
  -Map<String, Object> getVariablesLocal(String executionId);
  -Map<String, Object> getVariables(String executionId, Collection<String> variableNames);
  -Map<String, Object> getVariablesLocal(String executionId, Collection<String> variableNames);
  -Object getVariable(String executionId, String variableName);
  -<T> T getVariable(String executionId, String variableName, Class<T> variableClass);
  -----
  -
  -Variables are often used in <<bpmnJavaServiceTask, Java delegates>>, <<apiExpressions, expressions>>, execution- or tasklisteners, scripts, etc. In those constructs, the current _execution_ or _task_ object is available and it can be used for variable setting and/or retrieval. The simplest methods are these:
  -
  -[source,java,linenums]
  -----
  -execution.getVariables();
  -execution.getVariables(Collection<String> variableNames);
  -execution.getVariable(String variableName);
  -
  -execution.setVariables(Map<String, object> variables);
  -execution.setVariable(String variableName, Object value);
  -----
  -
  -Note that a variant with _local_ is also available for all of the above.
  -
  -For historical (and backwards compatible reasons), when doing any of the calls above, behind the scenes actually *all* variables will be fetched from the database. This means that if you have 10 variables, and only get one through _getVariable("myVariable")_, behind the scenes the other 9 will be fetched and cached. This is not bad, as subsequent calls will not hit the database again.  For example, when your process definition has three sequential service tasks (and thus one database transaction), using one call to fetch all variables in the first service task might be better then fetching the variables needed in each service task separately. Note that this applies *both* for getting and setting variables.
  -
  -Of course, when using a lot of variables or simply when you want tight control on the database query and traffic, this is not appropriate. Additional methods have been introduced to give a tighter control on this, by adding in new methods that have an optional parameter that tells the engine whether or not behind the scenes all variables need to be fetched and cached:
  -
  -[source,java,linenums]
  -----
  -Map<String, Object> getVariables(Collection<String> variableNames, boolean fetchAllVariables);
  -Object getVariable(String variableName, boolean fetchAllVariables);
  -void setVariable(String variableName, Object value, boolean fetchAllVariables);
  -----
  -
  -When using _true_ for the parameter _fetchAllVariables_, the behaviour will be exactly as described above: when getting or setting a variable, all other variables will be fetched and cached.
  -
  -However, when using _false_ as value, a specific query will be used and no other variables will be fetched nor cached. Only the value of the variable in question here will be cached for subsequent use.
  -
  -[[apiTransientVariables]]
  -
  -=== Transient variables
  -
  -Transient variables are variables that behave like regular variables, but are not persisted. Typically, transient variables are used for advanced use cases (i.e. when in doubt, use a regular process variable).
  -
  -The following applies for transient variables:
  -
  -* There is no history stored at all for transient variables.
  -* Like _regular_ variables, transient variables are put on the _highest parent_ when set. This means that when setting a variable on an execution, the transient variable is actually stored on the process instance execution. Like regular variables, a _local_ variant of the method exists if the variable should be set on the specific execution or task.
  -* A transient variable can only be accessed until the next 'wait state' in the process definition. After that, they are gone. The wait state means here the point in the process instance where it is persisted to the data store. Note that an _async_ activity also is a 'wait state' in this definition!
  -* Transient variables can only be set by the _setTransientVariable(name, value)_, but transient variables are also returned when calling _getVariable(name)_ (a _getTransientVariable(name)_ also exists, that only checks the transient variables). The reason for this is to make the writing of expressions easy and existing logic using variables works for both types.
  -* A transient variable _shadows_ a persistent variable with the same name. This means that when both a persistent and transient variable is set on a process instance and the _getVariable("someVariable")_ is used, the transient variable value will be returned.
  -
  -Transient variables can be got and/or set in most places where regular variables are exposed:
  -
  -* On _DelegateExecution_ in _JavaDelegate_ implementations
  -* On _DelegateExecution_ in _ExecutionListener_ implementations and on _DelegateTask_ on _TaskListener_ implementations
  -* In script task via the _execution_ object
  -* When starting a process instance via the runtime service
  -* When completing a task
  -* When calling the _runtimeService.trigger_ method
  -
  -The methods follow the naming convention of the regular process variables:
  -
  -[source,java,linenums]
  -----
  -void setTransientVariable(String variableName, Object variableValue);
  -void setTransientVariableLocal(String variableName, Object variableValue);
  -void setTransientVariables(Map<String, Object> transientVariables);
  -void setTransientVariablesLocal(Map<String, Object> transientVariables);
  -
  -Object getTransientVariable(String variableName);
  -Object getTransientVariableLocal(String variableName);
  -
  -Map<String, Object> getTransientVariables();
  -Map<String, Object> getTransientVariablesLocal();
  -
  -void removeTransientVariable(String variableName);
  -void removeTransientVariableLocal(String variableName);
  -----
  -
  -Following BPMN diagram shows a typical example:
  -
  -image::images/api.transient.variable.example.png[align="center"]
  -
  -Let's assume the 'Fetch Data' service task calls some remote service (for example using REST). Let's also assume some config parameters are needed and need to be provided when starting the process instance. Also, these config parameters are not important for historical audit purposes, so we pass them as transient variables:
  -
  -[source,java,linenums]
  -----
  -ProcessInstance processInstance = runtimeService.createProcessInstanceBuilder()
  -       .processDefinitionKey("someKey")
  -       .transientVariable("configParam01", "A")
  -       .transientVariable("configParam02", "B")
  -       .transientVariable("configParam03", "C")
  -       .start();
  -----
  -
  -Note that the variables will be available until the user task is reached and persisted to the database. For example, in the 'Additional Work' user task they are not available anymore. Also note that if 'Fetch Data' would have been asynchronous, they won't be available after that step too.
  -
  -The 'Fetch Data' (simplified) could be something like
  -
  -[source,java,linenums]
  -----
  -public static class FetchDataServiceTask implements JavaDelegate {
  -  public void execute(DelegateExecution execution) {
  -    String configParam01 = (String) execution.getVariable(configParam01);
  -    // ...
  -
  -    RestReponse restResponse = executeRestCall();
  -    execution.setTransientVariable("response", restResponse.getBody());
  -    execution.setTransientVariable("status", restResponse.getStatus());
  +
  +[[apiUnitTesting]]
  +
  +
  +=== Unit testing
  +
  +Since Flowable DMN is an embeddable Java engine, writing unit tests for DMN definitions is as simple as writing regular unit tests.
  +
  +Flowable supports both JUnit versions 3 and 4 styles of unit testing. In the JUnit 3 style, the +org.flowable.dmn.engine.test.AbstractFlowableDmnTestCase+ must be extended. This will make the DmnEngine and the services available through protected member fields. In the +setup()+ of the test, the DmnEngine will be initialized by default with the +flowable.dmn.cfg.xml+ resource on the classpath.  To specify a different configuration file, override the _getConfigurationResource()_ method. DMN engines are cached statically over multiple unit tests when the configuration resource is the same.
  +
  +By extending +AbstractFlowableDmnTestCase+, you can annotate test methods with +org.flowable.dmn.engine.test.DmnDeploymentAnnotation+. Before the test is run, a resource file of the form +testClassName.testMethod.dmn+ in the same package as the test class, will be deployed. At the end of the test, the deployment will be deleted, including all decision tables. The +DmnDeploymentAnnotation+ annotation also supports setting the resource location explicitly. See the class itself for more information.
  +
  +Taking all that in account, a JUnit 3 style test looks as follows.
  +
  +[source,java,linenums]
  +----
  +public class MyDmnDeploymentTest extends AbstractFlowableDmnTestCase {
  +
  +  @DmnDeploymentAnnotation
  +  public void simpleDeploymentTest() {
  +      DmnDeployment deployment = repositoryService.createDeploymentQuery().singleResult();
  +      assertNotNull(deployment);
     }
   }
   ----
   
  -The 'Process Data' would get the response transient variable, parse it and store the relevant data in real process variables as we need them later.
  -
  -The condition on the sequence flow leaving the exclusive gateway are oblivious to whether persistent or transient variables are used (in this case the _status_ transient variable):
  -
  -[source,xml,linenums]
  -----
  -<conditionExpression xsi:type="tFormalExpression">${status == 200}</conditionExpression>
  -----
  -
  -[[apiExpressions]]
  -
  -
  -=== Expressions
  -
  -Flowable uses UEL for expression-resolving. UEL stands for _Unified Expression Language_ and is part of the EE6 specification (see link:$$http://docs.oracle.com/javaee/6/tutorial/doc/gjddd.html$$[ the EE6 specification] for detailed information).footnote:[To support all features of latest UEL spec on ALL environments, we use a modified version of JUEL for the Version 5 compatibility engine.]
  -
  -Expressions can be used in for example <<bpmnJavaServiceTaskXML,Java Service tasks>>, <<executionListeners,Execution Listeners>>, <<taskListeners,Task Listeners>> and <<conditionalSequenceFlowXml,Conditional sequence flows>>. Although there are 2 types of expressions, value-expression and method-expression, Flowable abstracts  this so they can both be used where an +expression+ is needed.
  -
  -* *Value expression*: resolves to a value. By default, all process variables are available to use. Also all spring-beans (if using Spring) are available to use in expressions. Some examples:
  -
  -----
  -${myVar}
  -${myBean.myProperty}
  -----
  -
  -
  -* *Method expression*: invokes a method, with or without parameters. *When invoking a method without parameters, be sure to add empty parentheses after the method-name (as this distinguishes the expression from a value expression).* The passed parameters can be literal values or expressions that are resolved themselves. Examples:
  -
  -----
  -${printer.print()}
  -${myBean.addNewOrder('orderName')}
  -${myBean.doSomething(myVar, execution)}
  -----
  -
  -Note that these expressions support resolving primitives (incl. comparing them), beans, lists, arrays and maps.
  -
  -On top of all process variables, there are a few default objects available to be used in expressions:
  -
  -* ++execution++: The +DelegateExecution+ that holds additional information about the ongoing execution.
  -* ++task++: The +DelegateTask+ that holds additional information about the current Task. *Note: Only works in expressions evaluated from task listeners.*
  -* ++authenticatedUserId++: The id of the user that is currently authenticated. If no user is authenticated, the variable is not available.
  -
  -For more concrete usage and examples, check out <<springExpressions,Expressions in Spring>>, <<bpmnJavaServiceTaskXML,Java Service tasks>>, <<executionListeners,Execution Listeners>>,  <<taskListeners,Task Listeners>> or <<conditionalSequenceFlowXml,Conditional sequence flows>>.
  -
  -
  -[[apiUnitTesting]]
  -
  -
  -=== Unit testing
  -
  -Business processes are an integral part of software projects and they should be tested in the same way normal application logic is tested: with unit tests. Since Flowable is an embeddable Java engine, writing unit tests for business processes is as simple as writing regular unit tests.
  -
  -Flowable supports both JUnit versions 3 and 4 styles of unit testing. In the JUnit 3 style, the +org.flowable.engine.test.FlowableTestCase+ must be extended. This will make the ProcessEngine and the services available through protected member fields. In the +setup()+ of the test,  the processEngine will be initialized by default with the +flowable.cfg.xml+ resource on the classpath.  To specify a different configuration file, override the _getConfigurationResource()_ method. Process engines are cached statically over multiple unit tests when the configuration resource is the same.
  -
  -By extending +FlowableTestCase+, you can annotate test methods with +org.flowable.engine.test.Deployment+. Before the test is run, a resource file of the form +testClassName.testMethod.bpmn20.xml+ in the same package as the test class, will be deployed. At the end of the test, the deployment will be deleted, including all related process instances, tasks, etc. The +Deployment+ annotation also supports setting the resource location explicitly. See the class itself for more information.
  -
  -Taking all that in account, a JUnit 3 style test looks as follows.
  -
  -[source,java,linenums]
  -----
  -public class MyBusinessProcessTest extends FlowableTestCase {
  -
  -  @Deployment
  -  public void testSimpleProcess() {
  -    runtimeService.startProcessInstanceByKey("simpleProcess");
  -
  -    Task task = taskService.createTaskQuery().singleResult();
  -    assertEquals("My Task", task.getName());
  -
  -    taskService.complete(task.getId());
  -    assertEquals(0, runtimeService.createProcessInstanceQuery().count());
  +To get the same functionality when using the JUnit 4 style of writing unit tests, the +org.flowable.dmn.engine.test.FlowableDmnRule+ Rule must be used. Through this rule, the DMN engine and services are available through getters. As with the +AbstractFlowableDmnTestCase+ (see above), including this +Rule+ will enable the use of the +org.flowable.dmn.engine.test.DmnDeploymentAnnotation+ annotation (see above for an explanation of its use and configuration) and it will look for the default configuration file on the classpath. DMN engines are statically cached over multiple unit tests when using the same configuration resource.
  +
  +The following code snippet shows an example of using the JUnit 4 style of testing and the usage of the +FlowableDmnRule+.
  +
  +[source,java,linenums]
  +----
  +public class MyDecisionTableTest {
  +
  +  @Rule
  +  public FlowableDmnRule flowableDmnRule = new FlowableDmnRule();
  +
  +  @Test
  +  @DmnDeploymentAnnotation
  +  public void ruleUsageExample() {
  +    DmnEngine dmnEngine = flowableDmnRule.getDmnEngine();
  +    DmnRuleService dmnRuleService = dmnEngine.getDmnRuleService();
  +
  +    Map<String, Object> inputVariables = new HashMap<>();
  +    inputVariables.put("inputVariable1", 2);
  +    inputVariables.put("inputVariable2", "test2");
  +
  +    RuleEngineExecutionResult result = dmnRuleService.executeDecisionByKey("decision1", inputVariables);
  +
  +    Assert.assertEquals("result2", result.getResultVariables().get("outputVariable1"));
     }
   }
   ----
   
  -To get the same functionality when using the JUnit 4 style of writing unit tests, the +org.flowable.engine.test.FlowableRule+ Rule must be used. Through this rule, the process engine and services are available through getters. As with the +FlowableTestCase+ (see above), including this +Rule+ will enable the use of the +org.flowable.engine.test.Deployment+ annotation (see above for an explanation of its use and configuration) and it will look for the default configuration file on the classpath. Process engines are statically cached over multiple unit tests when using the same configuration resource.
  -
  -The following code snippet shows an example of using the JUnit 4 style of testing and the usage of the +FlowableRule+.
  -
  -[source,java,linenums]
  -----
  -public class MyBusinessProcessTest {
  -
  -  @Rule
  -  public FlowableRule FlowableRule = new FlowableRule();
  -
  -  @Test
  -  @Deployment
  -  public void ruleUsageExample() {
  -    RuntimeService runtimeService = FlowableRule.getRuntimeService();
  -    runtimeService.startProcessInstanceByKey("ruleUsage");
  -
  -    TaskService taskService = FlowableRule.getTaskService();
  -    Task task = taskService.createTaskQuery().singleResult();
  -    assertEquals("My Task", task.getName());
  -
  -    taskService.complete(task.getId());
  -    assertEquals(0, runtimeService.createProcessInstanceQuery().count());
  -  }
  +[[apiDebuggingUnitTest]]
  +
  +
  +=== Debugging unit tests
  +
  +//TODO
  +
  +When using the in-memory H2 database for unit tests, the following instructions allow to easily inspect the data in the Flowable DMN database during a debugging session. The screenshots here are taken in Eclipse, but the mechanism should be similar for other IDEs.
  +
  +Suppose we have put a _breakpoint_ somewhere in our unit test. In Eclipse this is done by double-clicking in the left border next to the code:
  +
  +image::images/api.test.debug.breakpoint.png[align="center"]
  +
  +If we now run the unit test in _debug_ mode (right-click in test class, select 'Run as' and then 'JUnit test'), the test execution halts at our breakpoint, where we can now inspect the variables of our test as shown in the right upper panel.
  +
  +image::images/api.test.debug.view.png[align="center"]
  +
  +To inspect the Flowable data, open up the _'Display'_ window (if this window isn't there, open Window->Show View->Other and select _Display_.) and type (code completion is available) +org.h2.tools.Server.createWebServer("-web").start()+
  +
  +image::images/api.test.debug.start.h2.server.png[align="center"]
  +
  +Select the line you've just typed and right-click on it. Now select 'Display' (or execute the shortcut instead of right-clicking)
  +
  +image::images/api.test.debug.start.h2.server.2.png[align="center"]
  +
  +Now open up a browser and go to link:$$http://localhost:8082$$[http://localhost:8082], and fill in the JDBC URL to the in-memory database (by default this is ++jdbc:h2:mem:flowable++), and hit the connect button.
  +
  +image::images/api.test.debug.h2.login.png[align="center"]
  +
  +You can now see the Flowable data and use it to understand how and why your unit test is executing your process in a certain way.
  +
  +image::images/api.test.debug.h2.tables.png[align="center"]
  +
  +
  +
  +[[apiProcessEngineInWebApp]]
  +
  +
  +=== The DMN engine in a web application
  +
  +The +DmnEngine+ is a thread-safe class and can easily be shared among multiple threads. In a web application, this means it is possible to create the DMN engine once when the container boots and shut down the engine when the container goes down.
  +
  +The following code snippet shows how you can write a simple +ServletContextListener+ to initialize and destroy process engines in a plain Servlet environment:
  +
  +[source,java,linenums]
  +----
  +public class DmnEnginesServletContextListener implements ServletContextListener {
  +
  +  public void contextInitialized(ServletContextEvent servletContextEvent) {
  +    DmnEngines.init();
  +  }
  +
  +  public void contextDestroyed(ServletContextEvent servletContextEvent) {
  +    DmnEngines.destroy();
  +  }
  +
   }
   ----
   
  -[[apiDebuggingUnitTest]]
  -
  -
  -=== Debugging unit tests
  -
  -When using the in-memory H2 database for unit tests, the following instructions allow to easily inspect the data in the Flowable database during a debugging session. The screenshots here are taken in Eclipse, but the mechanism should be similar for other IDEs.
  -
  -Suppose we have put a _breakpoint_ somewhere in our unit test. In Eclipse this is done by double-clicking in the left border next to the code:
  -
  -image::images/api.test.debug.breakpoint.png[align="center"]
  -
  -If we now run the unit test in _debug_ mode (right-click in test class, select 'Run as' and then 'JUnit test'), the test execution halts at our breakpoint, where we can now inspect the variables of our test as shown in the right upper panel.
  -
  -image::images/api.test.debug.view.png[align="center"]
  -
  -To inspect the Flowable data, open up the _'Display'_ window (if this window isn't there, open Window->Show View->Other and select _Display_.) and type (code completion is available) +org.h2.tools.Server.createWebServer("-web").start()+
  -
  -image::images/api.test.debug.start.h2.server.png[align="center"]
  -
  -Select the line you've just typed and right-click on it. Now select 'Display' (or execute the shortcut instead of right-clicking)
  -
  -image::images/api.test.debug.start.h2.server.2.png[align="center"]
  -
  -Now open up a browser and go to link:$$http://localhost:8082$$[http://localhost:8082], and fill in the JDBC URL to the in-memory database (by default this is ++jdbc:h2:mem:flowable++), and hit the connect button.
  -
  -image::images/api.test.debug.h2.login.png[align="center"]
  -
  -You can now see the Flowable data and use it to understand how and why your unit test is executing your process in a certain way.
  -
  -image::images/api.test.debug.h2.tables.png[align="center"]
  -
  -
  -
  -[[apiProcessEngineInWebApp]]
  -
  -
  -=== The process engine in a web application
  -
  -The +ProcessEngine+ is a thread-safe class and can easily be shared among multiple threads. In a web application, this means it is possible to create the process engine once when the container boots and shut down the engine when the container goes down.
  -
  -The following code snippet shows how you can write a simple +ServletContextListener+ to initialize and destroy process engines in a plain Servlet environment:
  -
  -[source,java,linenums]
  -----
  -public class ProcessEnginesServletContextListener implements ServletContextListener {
  -
  -  public void contextInitialized(ServletContextEvent servletContextEvent) {
  -    ProcessEngines.init();
  -  }
  -
  -  public void contextDestroyed(ServletContextEvent servletContextEvent) {
  -    ProcessEngines.destroy();
  -  }
  -
  -}
  -----
  -
  -The +contextInitialized+ method will delegate to +ProcessEngines.init()+. That will look for +flowable.cfg.xml+ resource files on the classpath, and create a +ProcessEngine+ for the given configurations (e.g. multiple jars with a configuration file). If you have multiple such resource files on the classpath, make sure they all have different names. When the process engine is needed, it can be fetched using
  -
  -[source,java,linenums]
  -----
  -ProcessEngines.getDefaultProcessEngine()
  +The +contextInitialized+ method will delegate to +DmnEngines.init()+. That will look for +flowable.dmn.cfg.xml+ resource files on the classpath, and create a +DmnEngine+ for the given configurations (e.g. multiple jars with a configuration file). If you have multiple such resource files on the classpath, make sure they all have different names. When the DMN engine is needed, it can be fetched using
  +
  +[source,java,linenums]
  +----
  +DmnEngines.getDefaultDmnEngine()
   ----
   
   or
   
   [source,java,linenums]
   ----
  -ProcessEngines.getProcessEngine("myName");
  -----
  -
  -Of course, it is also possible to use any of the variants of creating a process engine,
  +DmnEngines.getDmnEngine("myName");
  +----
  +
  +Of course, it is also possible to use any of the variants of creating a DMN engine,
   as described in the <<configuration,configuration section>>.
   
   
  -The +contextDestroyed+ method of the context-listener delegates to +ProcessEngines.destroy()+. That will properly close all initialized process engines.
  +The +contextDestroyed+ method of the context-listener delegates to +DmnEngines.destroy()+. That will properly close all initialized DMN engines.
  
positive.code: [source,java,linenums]
  ----
  DmnEngine dmnEngine = DmnEngines.getDefaultDmnEngine();
  
  DmnRuleService dmnRuleService = dmnEngine.getDmnRuleService();
  DmnRepositoryService dmnRepositoryService = dmnEngine.getDmnRepositoryService();
  DmnManagementService dmnManagementService = dmnEngine.getDmnManagementService();
  
negative.code: 
  +DmnEngines.getDefaultDmnEngine()+ will initialize and build a DMN engine the first time it is called and afterwards always return the same DMN engine. Proper creation and closing of all DMN engines can be done with +DMNEngines.init()+  and +DMNEngines.destroy()+.
  
  The DmnEngines class will scan for all +flowable.dmn.cfg.xml+ and +flowable-dmn-context.xml+ files. For all +flowable.dmn.cfg.xml+ files, the DMN engine will be built in the typical Flowable way: +DmnEngineConfiguration.createDmnEngineConfigurationFromInputStream(inputStream).buildDmnEngine()+. For all +flowable-dmn-context.xml+ files, the DMN engine will be built in the Spring way: First the Spring application context is created and then the DMN engine is obtained from that application context.
  
  All services are stateless. This means that you can easily run Flowable DMN on multiple nodes in a cluster, each going to the same database, without having to worry about which machine actually executed previous calls. Any call to any service is idempotent regardless of where it is executed.
  
  The *DmnRepositoryService* is probably the first service needed when working with the Flowable DMN engine. This service offers operations for managing and manipulating +deployments+ and +DMN definitions+. A DMN definition is the root concept of a DMN model. (The main concepts of DMN are explained in the <dmn-introduction, DMN introduction section>) It contains the definition of the +decision+ (and it's +decision table+). 
  A +deployment+ is the unit of packaging within the Flowable DMN engine. A deployment can contain multiple DMN xml files. Deploying a deployment means it is uploaded to the engine, where all DMN definitions are inspected and parsed before being stored in the database. From that point on, the deployment is known to the system and any decision included in the deployment can now be executed.
  
  Furthermore, this service allows to
  
  * Query on deployments, DMN definitions and decision tables known to the engine.
  * Retrieve a POJO version of the DMN definition or decision table which can be used to introspect using Java rather than xml.
  
  The *DmnRuleService* provides methods for executing a decision. By providing parameters and input data the evaluation of a decision can be started.
  
  The *DmnManagementService* is typically not needed when coding custom application using Flowable DMN. It allows to retrieve information about the engine version, database tables and table metadata.
  
  For more detailed information on the service operations and the DMN engine API, see link:$$flowable/index.html$$[the javadocs].
  
  
  === Exception strategy
  
  The base exception in Flowable is the +org.flowable.engine.FlowableException+, an unchecked exception. This exception can be thrown at all times by the API, but 'expected' exceptions that happen in specific methods are documented in the link:$$http://flowable.org/javadocs/index.html$$[ the javadocs]. For example, an extract from ++DmnRuleService++:
  
  [source,java,linenums]
  ----
  /**
    * Execute a decision identified by it's key.
    *
    * @param  decisionKey      the decision key, cannot be null
    * @param  inputVariables   map with input variables
    * @return                  the {@link RuleEngineExecutionResult} for this execution
    * @throws FlowableObjectNotFoundException
    *            when the decision with given key does not exist.
    * @throws FlowableException
    *           when an error occurs while executing the decision.
    */
  RuleEngineExecutionResult executeDecisionByKey(String decisionKey, Map<String, Object> inputVariables);
  ----
  
  In the example above, when an key is passed for which no decisions exist, an exception will be thrown. Also, since the javadoc *explicitly states that decisionKey cannot be null, an +FlowableIllegalArgumentException+ will be thrown when +null+ is passed*.
  
  Even though we want to avoid a big exception hierarchy, the following subclasses were added which are thrown in specific cases. All other errors that occur during process-execution or API-invocation that don't fit into the possible exceptions below, are thrown as regular ++FlowableExceptions++s.
  
  * ++FlowableOptimisticLockingException++: Thrown when an optimistic locking occurs in the data store caused by concurrent access of the same data entry.
  * ++FlowableClassLoadingException++: Thrown when a class requested to load was not found or when an error occurred while loading it.
  * ++AFlowableObjectNotFoundException++: Thrown when an object that is requested or action on does not exist.
  * ++FlowableIllegalArgumentException++: An exception indicating that an illegal argument has been supplied in a Flowable DMN API-call, an illegal value was configured in the engine's configuration or an illegal value has been supplied.
  
  [[queryAPI]]
  
  