From 3d99e0a26aff6134189c7d23e513ea1ba3849005 Mon Sep 17 00:00:00 2001 From: Tiese Barrell Date: Sun, 3 Mar 2013 20:43:42 +0100 Subject: [PATCH] Added documentation for ACT-1572. Added documentation of the new options on the Runtime annotation. There have been changes to the way the runtime characteristics are specified. Also, new options have been added to support expression and delegateExpression, based on Michael Priess' work in the pull request https://github.com/Activiti/Activiti-Designer/pull/5. --- userguide/src/en/chapters/ch11-Designer.xml | 79 +++++++++++++++------ 1 file changed, 57 insertions(+), 22 deletions(-) diff --git a/userguide/src/en/chapters/ch11-Designer.xml b/userguide/src/en/chapters/ch11-Designer.xml index 947d77c53d..338354fcc6 100644 --- a/userguide/src/en/chapters/ch11-Designer.xml +++ b/userguide/src/en/chapters/ch11-Designer.xml @@ -568,14 +568,17 @@
Adding shapes to the palette - With your project set up, you can now easily add shapes to the palette. Each shape you + + With your project set up, you can now easily add shapes to the palette. Each shape you wish to add is represented by a class in your JAR. Take note that these classes are not the classes that will be used by the Activiti engine during runtime. In your extension you describe the properties that can be set in Activiti Designer for each shape. From these - shapes, your refer to the runtime class that should be used by the engine. This class - should implement JavaDelegate as for any ServiceTask in Activiti. + shapes, you can also define the runtime characteristics that should be used by the engine + when a process instance reaches the node in the process. The runtime characteristics can use any + of the options that Activiti supports for regular ServiceTasks. See this section for more - details. + details. + A shape's class is a simple Java class, to which a number of annotations are added. The class should implement the CustomServiceTask interface, but you shouldn't implement this interface yourself. Extend the @@ -627,7 +630,7 @@ private String accountNumber; * @version 1 * @since 1.0.0 */ -@Runtime(delegationClass = "org.acme.runtime.AcmeMoneyJavaDelegation") +@Runtime(javaDelegateClass = "org.acme.runtime.AcmeMoneyJavaDelegation") @Help(displayHelpShort = "Creates a new account", displayHelpLong = "Creates a new account using the account number specified") public class AcmeMoneyTask extends AbstractCustomServiceTask { @@ -708,34 +711,66 @@ public class AcmeMoneyTask extends AbstractCustomServiceTask { - There is a special annotation for specifying the class to be executed for your CustomServiceTask, + There is a special annotation for specifying the runtime characteristics of your CustomServiceTask, the @Runtime annotation. Here's an example of how to use it: - @Runtime(delegationClass = "org.acme.runtime.AcmeMoneyJavaDelegation") - - - The delegationClass - attribute you provide should contain the canonical name of the runtime class. This is a class that implements - Activiti's JavaDelegate interface. You should implement this class in the same manner as any - other JavaDelegate. Documentation for this is provided in the userguide here. - + @Runtime(javaDelegateClass = "org.acme.runtime.AcmeMoneyJavaDelegation") + + + Your CustomServiceTask will result in a normal ServiceTask in the BPMN output + of processes modelled with it. Activiti enables several ways to define the runtime characteristics of ServiceTasks. Therefore, the @Runtime annotation can take one of three attributes, which match directly to the options + Activiti provides, like this: + + + + javaDelegateClass maps to activiti:class in the BPMN output. Specify the fully qualified classname of a class that implements JavaDelegate. + + + + + expression maps to activiti:expression in the BPMN output. Specify an expression to a method to be executed, such as a method in a Spring Bean. You should not specify any @Property + annotations on fields when using this option. For more information, see below. + + + + + javaDelegateExpression maps to activiti:delegateExpression in the BPMN output. Specify an expression to a class that implements JavaDelegate. + + + + - The user's property values will be injected into the delegationClass runtime class + The user's property values will be injected into the runtime class if you provide members in the class for Activiti to inject into. The names should match the names of the members in your CustomServiceTask. For more information, consult this part of the userguide. Note that since version 5.11.0 of the Designer you can use the Expression interface for dynamic field values. This means that the value of the property in the Activiti Designer must contain an expression and this expression will then be injected into an Expression property in the JavaDelegate implementation class. - - - Note that the runtime class shouldn't be in your extension JAR, as it's dependent on the Activiti - libraries. Activiti needs to be able to find it at runtime, so it needs to be on the Activiti engine's - classpath. - - + + + + You can use @Property annotations on members of your CustomServiceTask, but this will not work if you use @Runtime's expression attribute. The reason for this is that the + expression you specify will be attempted to be resolved to a method by Activiti, not to a class. Therefore, no injection into + a class will be performed. Any members marked with @Property will be ignored by Designer if you use expression in your @Runtime annotation. Designer will not render them as editable fields in the node's property pane and will produce no output + for the properties in the process' BPMN. + + + + + + Note that the runtime class shouldn't be in your extension JAR, as it's dependent on the Activiti + libraries. Activiti needs to be able to find it at runtime, so it needs to be on the Activiti engine's + classpath. + + + + + The examples project in Designer's source tree contains examples of the different options for configuring @Runtime. Take a look in the money-tasks project for some starting points. The examples refer to delegate class examples that are in the money-delegates project. + +
-- GitLab