impl, docu

Issue #327

open-bpmn.metamodel/README.md

@@ -1,10 +1,10 @@
 <h1><img width="200" src="../doc/images/logo-openbpmn-no-margin.png" /> Meta Model</h1>
 
-**Open BPMN** provides a Java Meta Model used to create, load and manipulate a BPMN model programmatically. The Meta Model includes factory and builder classes to easily operate on a BPMN model instance. The library is based on the `org.w3c.dom` XML API and operates directly on the dom Nodes which makes this Meta Model very flexible. The Open BPMN Meta Model allows you to handle any kind of BPMN model and also work with BPMN 2.0 extensions or add your own extensions.
+**Open BPMN** provides a Java Meta Model used to create, load and manipulate a BPMN model programmatically. The Meta Model includes factory and builder classes to easily operate on a BPMN model instance. The library is based on the `org.w3c.dom` XML API and operates directly on the dom Nodes which makes this Meta Model very flexible. The Open BPMN Meta Model allows you to handle any kind of BPMN model and also work with BPMN 2.0 extensions and add your own extensions.
 
 ## The BPMNModelFactory
 
-The class `BPMNModelFactory` provides methods to create ane  model from scratch or to load an existing one. The `BPMNModelFactory` returns a BPMNModel instance to be used to read, update or delete elements.
+With the utility class `BPMNModelFactory` you find methods to create a model from scratch or to load an existing one. The `BPMNModelFactory` returns a `BPMNModel` instance to be used to read, update or delete any kind of bpmn elements.
 
 ### Create a New Model
 
@@ -18,10 +18,9 @@ BPMNModel model = BPMNModelFactory.createInstance(exporter, version, targetNameS
 model.save("src/test/resources/create-process_1.bpmn");
 ```
 
-This file contains a default process with no elements. With the default process instance you can add BPMN flow elements:
+This file contains a default process with no elements. With the default process instance you can add BPMN flow elements as you can see in the next example:
 
 ```java
-BPMNModel model = BPMNModelFactory.createInstance(exporter, version, targetNameSpace);
 BPMNProcess processContext = model.openDefaultProcess();
 processContext.addEvent("start_1","Start",EventType.START);
 processContext.addEvent("end_1","End",EventType.END);
@@ -31,7 +30,7 @@ model.save("src/test/resources/create-process_1.bpmn");
 
 ### Load an existing Model
 
-To load a model instance call the `read` method. Again you can open the default process with  "openDefaultProcess" or you can
+To load an existing BPMN model  call the `read` method. Again you can open the default process with the method `openDefaultProcess` or you can
 open a specific process within your model by its id:
 
 ```java
@@ -60,6 +59,8 @@ model.save("src/test/resources/create-process_1.bpmn");
 
 ## Positioning Elements
 
+BPMN separates the `bpmn2:process` defintion from the `bpmndi:BPMNDiagram` defintion. This allows a workflow engine to operate only on the process, while a modeling tool can layout the model by operating on the BPMNDiagram defintion. This *separation of concerns* is an important and strong concept in BPMN2. 
+
 Working with a graphical editor like **Open BPMN** allows you to move BPMN Elements within a diagram. In case of a BPMN Collaboration Model this means moving a BPMN Element from one Pool into another the process assignment of the BPMN element changes. The position of a BPMN element defines to which process the element belongs to. The Open BPMN Meta Model makes this process transparent by automatically updating the process assignment whenever you change the position of a BPMN element. This also applies to lanes within a pool.
 
 ```java
@@ -85,3 +86,37 @@ task.setPosition(50, 450);
 assertTrue(marketingProcess == task.getBpmnProcess());
 
 ```
+
+## BPMN Extensions
+
+BPMN 2.0 introduces an extensibility mechanism that allows extending standard BPMN elements with additional properties and behavior. This extension mechanism can be used by modeling tools and workflow engines. The Open-BPMN meta model provides convenience methods to operate on the BPMN 2.0 extension.
+
+To access the `bpmn2:extensionElements` you can call the  the method `findExtensionsElement`. This method expects the root BPMN element containing the extensions. In the following example we access the extensions for a bpmn task element 'myTask':
+
+
+```java
+  Element extensionElement = myModel.findBPMN2Extensions(myTask);
+
+```
+
+To access an extension element directly you can call the method `findExtensionsElement`. This method expects the root BPMN element and a namespace and extension name. The following example returns the Open-BPMN auto-align extension element from the `bpmn2: defintions` : 
+
+```java
+ Element extensionElement = myModel.findExtensionElement(myModel.getDefinitions(), BPMNModelFactory.OPEN_BPMN_NAMESPACE, "auto-align");
+
+```
+Here you can see the corresponding BPMN file: 
+
+```xml
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<bpmn2:definitions ...>
+  <bpmn2:extensionElements>
+    <open-bpmn:auto-align>true</open-bpmn:auto-align>
+  </bpmn2:extensionElements>
+  ....
+</bpmn2:definitions>
+```
+
+**Note:** This method automatically creates the corresponding extension element if it is not yet part of the model. 
+
+

open-bpmn.metamodel/src/main/java/org/openbpmn/bpmn/BPMNModel.java

@@ -1025,6 +1025,73 @@ public BPMNElement findElementById(String id) {
         return null;
     }
 
+    /**
+     * This method returns the bpmn2:extensionElements node for a given BPMN
+     * Element. If not yet defined, the
+     * method creates an new emtpy bpmn2:extensionElements node.
+     * 
+     * The bpmn2:extensionElements node can be used to read or create custom
+     * extension elements.
+     * 
+     * @param defaultModel
+     * @param nameSpace
+     * @param elementName
+     * @return
+     */
+    public Element findBPMN2Extensions(Element element) {
+        // find extension elements
+        Element extensionElement = findChildNodeByName(element, BPMNNS.BPMN2,
+                "extensionElements");
+        if (extensionElement == null) {
+            extensionElement = createElement(BPMNNS.BPMN2, "extensionElements");
+            element.insertBefore(extensionElement, element.getFirstChild());
+
+        }
+        return extensionElement;
+    }
+
+    /**
+     * This method returns an extension element for a given element node defined by
+     * its namespace and tag name. If the extension element is not yet defined, the
+     * method creates an empty one.
+     * 
+     * @param defaultModel
+     * @param nameSpace
+     * @param elementName
+     * @return
+     * @throws BPMNInvalidReferenceException
+     */
+    public Element findExtensionElement(Element element, String namespace, String elementName)
+            throws BPMNInvalidReferenceException {
+        Element extensionElement = findBPMN2Extensions(element);
+        Element autoAlignElement = null;
+        // resolve the tag name
+        String tagName = namespace + ":" + elementName;
+        NodeList childs = extensionElement.getChildNodes();
+        for (int i = 0; i < childs.getLength(); i++) {
+            Node childNode = childs.item(i);
+            if (childNode.getNodeType() == Node.ELEMENT_NODE && tagName.equals(childNode.getNodeName())) {
+                autoAlignElement = (Element) childNode;
+                break;
+            }
+        }
+
+        // If extension element is not yet defined, we create a new empty one....
+        if (autoAlignElement == null) {
+
+            if (definitions.hasAttribute("xmlns:" + namespace)) {
+                // find schema uri
+                String nameSpaceUri = definitions.getAttribute("xmlns:" + namespace);
+                autoAlignElement = getDoc().createElementNS(nameSpaceUri,
+                        namespace + ":" + elementName);
+                extensionElement.appendChild(autoAlignElement);
+            } else {
+                throw new BPMNInvalidReferenceException("Namespace '" + namespace + "' not defined!");
+            }
+        }
+        return autoAlignElement;
+    }
+
     /**
      * Returns all Events within this model
      * <p>

open-bpmn.metamodel/src/main/java/org/openbpmn/bpmn/util/BPMNModelFactory.java

@@ -34,6 +34,8 @@ public class BPMNModelFactory {
     public static final String DEFAULT_EXPORTER = "org.openbpmn";
     public static final String DEFAULT_VERSION = "1.0.0";
     public static final String DEFAULT_TARGETNAMESPACE = "http://open-bpmn.org";
+    public static final String OPEN_BPMN_NAMESPACE = "open-bpmn";
+    public static final String OPEN_BPMN_SCHEMA = "http://open-bpmn.org/XMLSchema";
 
     /**
      * This method creates a new empty BPMNModel instance. The BPMNModel is
@@ -124,10 +126,14 @@ public static BPMNModel read(String modelFilePath) throws BPMNModelException {
     }
 
     /**
-     * Reads a BPMNModel instance from an InputStream
+     * Reads a BPMNModel instance from an InputStream.
      * <p>
      * The method cleans whitespace after reading the file for a better handling and
      * later output format.
+     * <p>
+     * If the file is empty, the mmethod creates automatically a default process. In
+     * addition the Open-BPMN extension 'allign-to-grid' is set to true. This option
+     * can be deactivated in the model properties.
      * 
      * @param modelFile
      * @return a BPMNModel instance
@@ -147,6 +153,7 @@ public static BPMNModel read(InputStream is, Path path) throws BPMNModelExceptio
                 // create a default model
                 BPMNModel defaultModel = BPMNModelFactory
                         .createInstance(DEFAULT_EXPORTER, DEFAULT_VERSION, DEFAULT_TARGETNAMESPACE);
+
                 return defaultModel;
             }
 
@@ -192,8 +199,8 @@ public static BPMNModel read(InputStream is, Path path) throws BPMNModelExceptio
      * @param definitions
      */
     private static void setOpenBPMNNameSpace(Element definitions) {
-        if (!definitions.hasAttribute("xmlns:open-bpmn")) {
-            definitions.setAttribute("xmlns:open-bpmn", "http://open-bpmn.org/XMLSchema");
+        if (!definitions.hasAttribute("xmlns:" + OPEN_BPMN_NAMESPACE)) {
+            definitions.setAttribute("xmlns:" + OPEN_BPMN_NAMESPACE, OPEN_BPMN_SCHEMA);
         }
     }
 

src/site/markdown/glsp-server/BPMN_EXTENSIONS.md

@@ -3,9 +3,38 @@
 BPMN 2.0 introduces an extensibility mechanism that allows extending standard BPMN elements with additional properties and behavior. It can be used by modeling tools to add non-standard elements or Artifacts to satisfy a specific need, such as the unique requirements of a vertical domain, and still have a valid BPMN Core.
 A BPMN 2.0 Extension defines a `ExtensionDefinition` and a `ExtensionAttributeDefinition`. The latter defines a list of attributes that can be attached to any BPMN element. The attribute list defines the name and type of the new attribute. This allows BPMN adopters to integrate any meta model into the BPMN meta model and reuse already existing model elements.
 
-**Open-BPMN** supports the extensibility mechanism of BPMN 2.0 by so called "BPMNExtension Points". An extension point allows adopters to add custom properties to any BPMN Element managed within the Open BPMN modeling tool. This extension mechanism is also used by Open-BPMN to support the BPMN Process Modeling Conformance level. In the following section you will learn how to implement custom BPMN Extensions and to extend the Open-BPMN modelling tool.
+# The Open-BPMN Meta model
+
+The [Open-BPMN meta model](https://github.com/imixs/open-bpmn/tree/master/open-bpmn.metamodel) provides convenience methods to operate on the BPMN 2.0 extension. To access the `bpmn2:extensionElements` node of a BPMN element you can call the  the method `findExtensionsElement`. In the following example we access the extensions for a bpmn task element 'myTask':
+
+
+```java
+  Element extensionElement = myModel.findBPMN2Extensions(myTask);
+
+```
+
+To access an extension element directly you can call  the method `findExtensionsElement`. This method expects the root BPMN element and a namespace and extension name. The following example returns the Open-BPMN auto-align extension element from the `bpmn2: definitions` : 
 
-# Development
+```java
+ Element extensionElement = myModel.findExtensionElement(myModel.getDefinitions(), BPMNModelFactory.OPEN_BPMN_NAMESPACE, "auto-align");
+
+```
+Here you can see the corresponding BPMN file: 
+
+```xml
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<bpmn2:definitions ...>
+  <bpmn2:extensionElements>
+    <open-bpmn:auto-align>true</open-bpmn:auto-align>
+  </bpmn2:extensionElements>
+  ....
+</bpmn2:definitions>
+```
+
+
+# Open-BPMN Extension Points
+
+**Open-BPMN** supports the extensibility mechanism of BPMN 2.0 by so called "BPMNExtension Points". An extension point allows adopters to add custom properties to any BPMN Element managed within the Open BPMN modeling tool. This extension mechanism is also used by Open-BPMN to support the BPMN Process Modeling Conformance level. In the following section you will learn how to implement custom BPMN Extensions and to extend the Open-BPMN modelling tool.
 
 To implement a new extension point within Open-BPMN an adaptor has to implement a BPMNExtension and define a new Server Module to register the new Extension. Open-BPMN will automatically integrate tne BPMNExtension into the modeling life-cycle and manage to store the new attributes into the .bpmn model file.