Activiti 5.22.0 Annotated Source Code

This repository contains the source code for Activiti version 5.22.0 with extensive Chinese annotations (approximately 10,000 lines). It is designed as a learning resource to help developers understand the internal workings of the Activiti workflow engine.

Key areas covered by the annotations include:

• Process Engine Configuration: ProcessEngineConfiguration and its subclasses.
• BPMN Parsing: BpmnModel and related classes for first-layer parsing.
• Event Dispatching: EventDispatcher and related classes.
• Optimization: Activiti's four major cache classes.
• Job Scheduling: Classes related to scheduled tasks.
• PVM Parsing: Classes related to the second-layer parsing (PVM).
• Listeners: Listener-related classes.
• Design Patterns: Implementation of the Command pattern and Chain of Responsibility.
• Atomic Operations: Classes supporting PVM execution (e.g., XXXoperation).
• Flow Control: Behavior classes that determine process direction.
• Persistence Layer: MyBatis integration (though coverage is lighter here due to its dependency on the MyBatis framework).

Activiti provides several stateless services to manage different aspects of the workflow engine:

• RepositoryService: Manages 'static' data. Used for deploying and querying deployments and process definitions (the BPMN 2.0 blueprints).
• RuntimeService: Manages 'dynamic' runtime state. Used to start process instances, manage process variables, and query executions (pointers to where a process is currently).
• TaskService: Handles human interaction. Used to query, claim, and complete tasks assigned to users or groups.
• IdentityService: Manages users and groups. Note: The engine does not verify if a user exists at runtime, allowing integration with external systems like LDAP.
• FormService: (Optional) Manages start forms and task forms defined in the BPMN 2.0 process.
• HistoryService: Provides access to historical data (e.g., start times, task durations, paths followed).
• ManagementService: Used for administrative tasks like inspecting database tables and managing jobs (timers, async continuations).

Activiti allows you to define form properties within your process definition (BPMN XML) to facilitate UI rendering. These properties act as a mapping layer between complex Java process variables and a simple Map<String, String> that UI technologies can consume.

Key Concepts

• Mapping: Properties can map directly to process variables (by ID) or to nested properties of a Java object using UEL expressions (e.g., #{address.street}).
• Default Behavior: If no variable attribute is specified, the submitted property is stored as a process variable with the same ID.
• Type Conversion: Activiti handles conversion between form property types and Java types (e.g., a long property maps to java.lang.Long).
• Validation: Using required="true" in the XML will cause an exception during submission if the field is missing.

Supported Form Types

• string
• long
• enum
• date
• boolean

<userTask id="task">
  <extensionElements>
    <activiti:formProperty id="room" />
    <activiti:formProperty id="duration" type="long"/>
    <activiti:formProperty id="speaker" variable="SpeakerName" writable="false" />
    <activiti:formProperty id="street" expression="#{address.street}" required="true" />
  </extensionElements>
</userTask>

A timer boundary event acts as a stopwatch or alarm. When the activity it is attached to starts, the timer begins. When the timer fires, the activity is interrupted (by default) and the process follows the event's outgoing flow.

Interrupting vs. Non-interrupting

• Interrupting (Default): The activity being monitored is cancelled when the timer fires. Set cancelActivity="true" (or omit the attribute).
• Non-interrupting: The original activity continues running, but an additional execution path is triggered via the event's outgoing flow. Set cancelActivity="false".

Important: Timer boundary events require the job or async executor to be enabled in activiti.cfg.xml via jobExecutorActivate or asyncExecutorActivate set to true.

<!-- Interrupting Timer Boundary Event -->
<boundaryEvent id="escalationTimer" cancelActivity="true" attachedToRef="firstLineSupport">
  <timerEventDefinition>
    <timeDuration>PT4H</timeDuration>
  </timerEventDefinition>
</boundaryEvent>

<!-- Non-interrupting Timer Boundary Event -->
<boundaryEvent id="escalationTimer" cancelActivity="false" attachedToRef="firstLineSupport"/>

Embedded Sub-Process

A standard Sub-Process is a grouping of activities within a parent process.

• Use cases: Hierarchical modeling (collapsing details) and creating a new scope for events (e.g., a boundary timer that only affects activities inside the sub-process).
• Constraints: Must have exactly one none start event, at least one end event, and sequence flows cannot cross its boundaries.

Event Sub-Process

An Event Sub-Process is triggered by a specific event (Message, Error, Signal, Timer, or Compensation) rather than a sequence flow.

• Triggering: Subscription to the start event is created when the hosting scope is created.
• Interrupting vs. Non-interrupting:
  • Interrupting: Cancels any executions in the current scope.
  • Non-interrupting: Spawns a new concurrent execution.
• Activiti Limitations: Currently only supports interrupting event sub-processes, and only those triggered by Error or Message start events.
• Implementation: Set triggeredByEvent="true" on the <subProcess> element.

<!-- Event Sub-Process Example -->
<subProcess id="eventSubProcess" triggeredByEvent="true">
	<startEvent id="catchError">
		<errorEventDefinition errorRef="error" />
	</startEvent>
	<sequenceFlow id="flow2" sourceRef="catchError" targetRef="taskAfterErrorCatch" />
	<userTask id="taskAfterErrorCatch" name="Provide additional data" />
</subProcess>

Start events indicate where a process begins. They are always 'catching' events.

None Start Event: Used when the process is started manually via the API (e.g., startProcessInstanceByXXX()). It has no sub-elements in XML.

• Extension: activiti:formKey can be used to reference a form template.

Timer Start Event: Used to start a process at a specific time or on intervals. These are scheduled as soon as the process is deployed.

Message Start Event: Starts a process when a specific named message is received.

• Constraint: Message names must be unique across a process definition and across all deployed process definitions.
• Constraint: Message start events are only supported on top-level processes (not embedded sub-processes).

Signal Start Event: Starts a process when a named signal is fired. All process definitions with a signal start event matching the signal name will be started.

Error Start Event: Used to trigger an Event Sub-Process. It cannot be used to start a standard process instance.

<!-- None Start Event with formKey extension -->
<startEvent id="request" activiti:formKey="org/activiti/examples/taskforms/request.form" />

<!-- Timer Start Event (repeating cycle) -->
<startEvent id="theStart">
  <timerEventDefinition>
    <timeCycle>R4/2011-03-11T12:13/PT5M</timeCycle>
  </timerEventDefinition>
</startEvent>

<!-- Message Start Event -->
<startEvent id="messageStart" >
    <messageEventDefinition messageRef="tns:newInvoice" />
</startEvent>

<!-- Signal Start Event -->
<startEvent id="theStart">
    <signalEventDefinition id="theSignalEventDefinition" signalRef="theSignal"  />
</startEvent>