2.4. Deployment Descriptors

Deployment descriptors allow the user to configure the execution server on multiple levels:

The granular configuration items specified by the deployment descriptors take precedence over the server level ones, except in case of configuration items that are collection based, which are merged. The hierarchy works like this: deploy time configuration > KJAR configuration > server configuration.

For example, if the persistence mode (one of the items you can configure) defined at the server level is NONE but the same mode is specified as JPA at the KJAR level, the actual mode will be JPA for that KJAR. If nothing is specified for the persistence mode in the deployment descriptor for that KJAR (or if there is no deployment descriptor), it will fall back to the server level configuration, which in this case is NONE (or to JPA if there is no server level deployment descriptor).

Can You Override this Hierarchal Merge Mode Behavior?

Yes. In the default way, if there are deployment descriptors present at multiple levels, the configuration properties are merged with the granular ones overriding the coarse values, and with missing configuration items at the granular level being supplied with those values from the higher levels. The end result is a merged Deployment Descriptor configuration. This default merge mode is called the MERGE_COLLECTIONS mode. However, you can change it (see Section 2.4.2, “Managing Deployment Descriptors”) if it does not suit your environment to one of the following modes:

Deployment Descriptors from dependent KJARs are placed lower than the actual KJAR being deployed, but they still have higher hierarchy than the server level.

Do I Need to Provide a Full Deployment Descriptor for All Kjars?

No, and this is where the beauty of the merge between different files can help you. Providing partial Deployment Descriptors is possible and recommended. For example, if you want to only override the audit mode in a KJAR, then you just need to provide that and the rest of the values will be merged from server level or higher level KJARs.

It is worth noting that when using OVERRIDE_ALL merge mode, all configuration items should be specified since the relevant KJAR will always use them and will not merge with any other deployment descriptor in the hierarchy.

What Can You Configure?

High level technical configuration details can be configured via deployment descriptors. The following table lists these along with the permissible and default values for each.

How Do You Provide Values For Collections-Based Configuration Items?

In the table of valid configuration items earlier, you would have noticed that the valid values for the collection based items are either ObjectModel or NamedObjectModel. Both are similar and provide a definition of the object to be built or created at runtime, with the exception that the NamedObjectModel object details name the object to be looked. Both these types are defined using an identifier, optional parameters and resolver (to resolve the object).

As an example, if you have built a custom marshaling strategy and want your deployments to use that strategy instead of the default, you will need to provide that strategy as an ObjectModel, with the identifier being com.mycompany.MyStrategy, resolver being reflection (the easiest and the default) and any parameters that are required for your strategy to work. Reflection will then be used to create an instance of this strategy using the fully qualified class name that you have provided as the identifier.

<marshalling-strategy>
 <resolver>reflection</resolver>
 <identifier>com.myCompany.MyStrategy</identifier>
 <parameters>
    <parameter xsi:type="xs:string" xmlns:xs="http://www.w3.org/2001/XMLSchema">
      param
    </parameter>
  </parameters>
</marshalling-strategy>

<marshalling-strategy>
 <resolver>reflection</resolver>
 <identifier>com.myCompany.MyStrategy</identifier>
 <parameters>
    <parameter xsi:type="xs:string" xmlns:xs="http://www.w3.org/2001/XMLSchema">
      param
    </parameter>
  </parameters>
</marshalling-strategy>

In the case that reflection based on resolver is not enough (as demonstrated in the previous example), you can use a resolver based on MVEL expression as the identifier of the object model. While evaluating expressions, you can substitute out-of-the-box parameters. For example:

<marshalling-strategy>
  <resolver>mvel</resolver>
  <identifier>new com.myCompany.CustomStrategy(runtimeManager)</identifier>
</marshalling-strategy>

<marshalling-strategy>
  <resolver>mvel</resolver>
  <identifier>new com.myCompany.CustomStrategy(runtimeManager)</identifier>
</marshalling-strategy>

The Spring based resolver allows you to look up a bean by its identifier from a Spring application context. Whenever JBoss BPM Suite is used with Spring, this resolver helps in deploying KJARs into the runtime. As an example (note that the identifier in this case is a named bean in the Spring context):

<marshalling-strategy>
 <resolver>spring</resolver>
 <identifier>customStrategy</identifier>
</marshalling-strategy>

<marshalling-strategy>
 <resolver>spring</resolver>
 <identifier>customStrategy</identifier>
</marshalling-strategy>

Deployment Descriptors can be edited via the Business Central in one of two ways. Either graphically (by clicking on Authoring Project Authoring Deployment Descriptor or by clicking on Authoring Administration menu and then clicking through to the META-INF folder in the File Explorer. Click on the kie-deployment-descriptor.xml file to edit it manually.

Every time a project is created, a stock kie-deployment-descriptor.xml file is generated with default values as described earlier.

Overriding Hierarchical Merge Mode Behavior

To change the default mode of MERGE_COLLECTIONS to one of KEEP_ALL, OVERRIDE_ALL, or OVERRIDE_EMPTY, you can use the following methods, depending on the requirement.

Restricting Access to the Runtime Engine

One of the configuration items discussed earlier, required-roles, can be edited via the Deployment Descriptors. This property restricts access to the runtime engine on a per KJAR or per server level by ensuring that access to certain processes is only granted to users that belong to groups defined by this property.

The security role can be used to restrict access to process definitions or restrict access at runtime.

The default behavior is to add required roles to this property based on repository restrictions. You can of course, edit these properties manually if required, as described above by providing roles that match actual roles defined in the security realm.