<commit_before>= camunda BPMN model API

The camunda BPMN model API is a simple, lightweight Java library for parsing, creating and editing BPMN 2.0 XML files. It is licensed under the Apache 2.0 license.

* Web Site: http://www.camunda.org/
* User Guide: link:http://docs.camunda.org/latest/guides/user-guide/#bpmn-model-api[http://docs.camunda.org]
* Examples: link:https://github.com/camunda/camunda-bpm-examples/tree/master/bpmn-model-api[https://github.com/camunda/camunda-bpm-examples]
* Issue Tracker: link:https://app.camunda.com/jira/secure/RapidBoard.jspa?rapidView=39&selectedIssue=CAM-1799&quickFilter=156[https://app.camunda.com/jira]
* Contribution Guidelines: http://www.camunda.org/community/contribute.html
* License: Apache License, Version 2.0  http://www.apache.org/licenses/LICENSE-2.0

== Components

The model API currently consists of two Components.

=== XML model API

The XML model API is the foundation of the BPMN model API. It is a generic XML API to read, edit and write
XML files. It allows the access of all attributes and elements even if they are not implemented in the BPMN
model API.

=== BPMN model API

The main component the BPMN model API extends the XML model API by the BPMN 2.0 elements. It allows the
simple access of the attributes and child elements of a BPMN element.

== Features

=== Create an empty BPMN model

You can easily create a new empty BPMN model.

[source,java]
----
BpmnModelInstance modelInstance = Bpmn.createEmptyModel();
Definitions definitions = modelInstance.newInstance(Definitions.class);
definitions.setTargetNamespace("http://camunda.org/examples");
modelInstance.setDefinitions(definitions);
----

=== Validate a BPMN model

At any time you can validate your model against the BPMN 2.0 specification.

[source,java]
----
BpmnModelInstance modelInstance = [...]
Bpmn.validateModel(modelInstance);
----

=== Create a simple Process

Currently not all BPMN 2.0 elements are supported. But basic elements like
StartEvent, EndEvent, Tasks, Parallel- and ExclusiveGateways are already
implemented. For the current list of implemented elements please visit
link:bpmn-model/src/main/java/org/camunda/bpm/model/bpmn/instance[org.camunda.bpm.model.bpmn.instance]
package.

The following code creates a simple Process as a jUnit4 test. See link:bpmn-model/src/test/java/org/camunda/bpm/model/bpmn/CreateModelTest.java[CreateModelTest.java] for
another example with ParallelGateways.

[source,java]
----
public class CreateProcessTest {

  public BpmnModelInstance modelInstance;
  public Definitions definitions;
  public Process process;

  @Before
  public void createEmptyModel() {
    modelInstance = Bpmn.createEmptyModel();
    definitions = modelInstance.newInstance(Definitions.class);
    definitions.setTargetNamespace("http://camunda.org/examples");
    modelInstance.setDefinitions(definitions);
  }

  protected <T extends BpmnModelElementInstance> T createElement(BpmnModelElementInstance parentElement, String id, Class<T> elementClass) {
    T element = modelInstance.newInstance(elementClass);
    element.setAttributeValue("id", id, true);
    parentElement.addChildElement(element);
    return element;
  }

  public SequenceFlow createSequenceFlow(Process process, FlowNode from, FlowNode to) {
    SequenceFlow sequenceFlow = createElement(process, from.getId() + "-" + to.getId(), SequenceFlow.class);
    process.addChildElement(sequenceFlow);
    sequenceFlow.setSource(from);
    from.getOutgoing().add(sequenceFlow);
    sequenceFlow.setTarget(to);
    to.getIncoming().add(sequenceFlow);
    return sequenceFlow;
  }

  @Test
  public void createProcessWithOneTask() {
    // create process
    Process process = createElement(definitions, "process-with-one-task", Process.class);

    // create elements
    StartEvent startEvent = createElement(process, "start", StartEvent.class);
    UserTask task1 = createElement(process, "task1", UserTask.class);
    EndEvent endEvent = createElement(process, "end", EndEvent.class);

    // create flows
    createSequenceFlow(process, startEvent, task1);
    createSequenceFlow(process, task1, endEvent);
  }

  @After
  public void validateModel() throws IOException {
    Bpmn.validateModel(modelInstance);
    File tempFile = File.createTempFile("bpmn-model-api-", ".bpmn");
    Bpmn.writeModelToFile(tempFile, modelInstance);
  }

}
----

=== Find elements inside the model

[source,java]
----
// find element instance by ID
ModelElementInstance elementInstance = modelInstance.getModelElementById("start");

// find all elements of the type task
ModelElementType taskType = modelInstance.getModel().getType(Task.class);
Collection<ModelElementInstance> elementInstances = modelInstance.getModelElementsByType(taskType);
----

=== Save the BPMN model

The model API allows you to save your model in several ways

[source,java]
----
// create BPMN model
BpmnModelInstance modelInstance = [...]

// convert to string
String xmlString = Bpmn.convertToString(modelInstance);

// write to output stream
OutputStream outputStream = new OutputStream(...);
Bpmn.writeModelToStream(outputStream, modelInstance);

// write to file
File file = new File(...);
Bpmn.writeModelToFile(file, modelInstance);

----

== Planned features

* complete read, edit and write support for BPMN 2.0 models
* a fluent builder API to create simple models
* JSON import and export
* extended validation support like integrity checks for broken references<commit_msg>chore(README): add section for fluent builder<commit_after>= camunda BPMN model API

The camunda BPMN model API is a simple, lightweight Java library for parsing, creating and editing BPMN 2.0 XML files. It is licensed under the Apache 2.0 license.

* Web Site: http://www.camunda.org/
* User Guide: link:http://docs.camunda.org/latest/guides/user-guide/#bpmn-model-api[http://docs.camunda.org]
* Examples: link:https://github.com/camunda/camunda-bpm-examples/tree/master/bpmn-model-api[https://github.com/camunda/camunda-bpm-examples]
* Issue Tracker: link:https://app.camunda.com/jira/secure/RapidBoard.jspa?rapidView=39&selectedIssue=CAM-1799&quickFilter=156[https://app.camunda.com/jira]
* Contribution Guidelines: http://www.camunda.org/community/contribute.html
* License: Apache License, Version 2.0  http://www.apache.org/licenses/LICENSE-2.0

== Components

The model API currently consists of two Components.

=== XML model API

The XML model API is the foundation of the BPMN model API. It is a generic XML API to read, edit and write
XML files. It allows the access of all attributes and elements even if they are not implemented in the BPMN
model API.

=== BPMN model API

The main component the BPMN model API extends the XML model API by the BPMN 2.0 elements. It allows the
simple access of the attributes and child elements of a BPMN element.

== Features

=== Fluent builder API

To easily create simple BPMN 2.0 processes we provide the fluent builder API. It supports most BPMN 2.0
elements and allows you to set attributes and add some child elements. The following process is deployable
and can be executed by the camunda BPM platform.

[source,java]
----
BpmnModelInstance modelInstance = Bpmn.createExecutableProcess("processId")
  .startEvent()
  .userTask()
  .endEvent()
  .done();
----

For more complex examples see the link:http://docs.camunda.org/latest/guides/user-guide/#bpmn-model-api-fluent-builder-api[docs],
the tests in link:bpmn-model/src/test/java/org/camunda/bpm/model/bpmn/builder/ProcessBuilderTest.java[ProcessBuilderTest.java] or this
link:https://github.com/camunda/camunda-bpm-examples/tree/master/bpmn-model-api/generate-process-fluent-api[example].

=== Create an empty BPMN model

You can easily create a new empty BPMN model.

[source,java]
----
BpmnModelInstance modelInstance = Bpmn.createEmptyModel();
Definitions definitions = modelInstance.newInstance(Definitions.class);
definitions.setTargetNamespace("http://camunda.org/examples");
modelInstance.setDefinitions(definitions);
----

=== Validate a BPMN model

At any time you can validate your model against the BPMN 2.0 specification.

[source,java]
----
BpmnModelInstance modelInstance = [...]
Bpmn.validateModel(modelInstance);
----

=== Create a simple Process

Currently not all BPMN 2.0 elements are supported. But basic elements like
StartEvent, EndEvent, Tasks, Parallel- and ExclusiveGateways are already
implemented. For the current list of implemented elements please visit
link:bpmn-model/src/main/java/org/camunda/bpm/model/bpmn/instance[org.camunda.bpm.model.bpmn.instance]
package.

The following code creates a simple Process as a jUnit4 test. See link:bpmn-model/src/test/java/org/camunda/bpm/model/bpmn/CreateModelTest.java[CreateModelTest.java] for
another example with ParallelGateways.

[source,java]
----
public class CreateProcessTest {

  public BpmnModelInstance modelInstance;
  public Definitions definitions;
  public Process process;

  @Before
  public void createEmptyModel() {
    modelInstance = Bpmn.createEmptyModel();
    definitions = modelInstance.newInstance(Definitions.class);
    definitions.setTargetNamespace("http://camunda.org/examples");
    modelInstance.setDefinitions(definitions);
  }

  protected <T extends BpmnModelElementInstance> T createElement(BpmnModelElementInstance parentElement, String id, Class<T> elementClass) {
    T element = modelInstance.newInstance(elementClass);
    element.setAttributeValue("id", id, true);
    parentElement.addChildElement(element);
    return element;
  }

  public SequenceFlow createSequenceFlow(Process process, FlowNode from, FlowNode to) {
    SequenceFlow sequenceFlow = createElement(process, from.getId() + "-" + to.getId(), SequenceFlow.class);
    process.addChildElement(sequenceFlow);
    sequenceFlow.setSource(from);
    from.getOutgoing().add(sequenceFlow);
    sequenceFlow.setTarget(to);
    to.getIncoming().add(sequenceFlow);
    return sequenceFlow;
  }

  @Test
  public void createProcessWithOneTask() {
    // create process
    Process process = createElement(definitions, "process-with-one-task", Process.class);

    // create elements
    StartEvent startEvent = createElement(process, "start", StartEvent.class);
    UserTask task1 = createElement(process, "task1", UserTask.class);
    EndEvent endEvent = createElement(process, "end", EndEvent.class);

    // create flows
    createSequenceFlow(process, startEvent, task1);
    createSequenceFlow(process, task1, endEvent);
  }

  @After
  public void validateModel() throws IOException {
    Bpmn.validateModel(modelInstance);
    File tempFile = File.createTempFile("bpmn-model-api-", ".bpmn");
    Bpmn.writeModelToFile(tempFile, modelInstance);
  }

}
----

=== Find elements inside the model

[source,java]
----
// find element instance by ID
ModelElementInstance elementInstance = modelInstance.getModelElementById("start");

// find all elements of the type task
ModelElementType taskType = modelInstance.getModel().getType(Task.class);
Collection<ModelElementInstance> elementInstances = modelInstance.getModelElementsByType(taskType);
----

=== Save the BPMN model

The model API allows you to save your model in several ways

[source,java]
----
// create BPMN model
BpmnModelInstance modelInstance = [...]

// convert to string
String xmlString = Bpmn.convertToString(modelInstance);

// write to output stream
OutputStream outputStream = new OutputStream(...);
Bpmn.writeModelToStream(outputStream, modelInstance);

// write to file
File file = new File(...);
Bpmn.writeModelToFile(file, modelInstance);

----

== Planned features

* complete read, edit and write support for BPMN 2.0 models
* JSON import and export
* extended validation support like integrity checks for broken references
{'fraction_non_alphanumeric': 0.10488261313371895, 'fraction_numerical': 0.005444028581150051, 'mean_word_length': 4.685203094777563, 'pattern_counts': {'":': 0, '<': 9, '<?xml version=': 0, '>': 9, 'https://': 9, 'lorem ipsum': 0, 'www.': 6, 'xml': 2}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1670859', 'n_tokens_mistral': 3468, 'n_tokens_neox': 3391, 'n_words': 993}