4.14. Data models

Data models are models of data objects. A data object is a custom complex data type (for example, a Person object with data fields Name, Address, and Date of Birth).
Data models are saved in data models definitions stored in your Project. Red Hat JBoss BPM Suite provides the Data modeler, a custom graphical editor, for defining data objects.

4.14.1. Data Modeler

The Data Modeler is the built-in editor for creating data objects as part of a Project data model from Business Central. Data objects are custom data types implemented as POJOs. These custom data types can then be used in any resource (such as a Process) after importing them.
To open the editor, open the Project Authoring perspective, click New Item → Data Object on the perspective menu. If you want to edit an existing model, these files are located under Data Objects in Project Explorer.
You will be prompted to enter the name of this model object when creating a new model, and asked to select a location for it (in terms of the package). On successful addition, it will bring up the editor where you can create fields for your model object.
The Data Modeler supports roundtrips between the Editor and Source tabs, along with source code preservation. This allows you to make changes to your model in external tools, like JBDS, and the Data Modeler updates the necessary code blocks automatically.
In the main editor window the user can
  • Add/delete fields
  • Select a given field. When a field is selected then the field information will be loaded in all the domain editors.
  • Select the data object class. For example, by clicking on the data object name (on the main window) instead of loading the field properties, the domain editors will load the class properties.

4.14.2. Annotations in Data Modeler

JBoss BPM Suite supports all Drools annotations by default, and can be customized using the Drools & jBPM interface.
If you want to add/edit custom or pre-defined annotations, you can switch to the source tab and modify the source code directly (in JBDS or Business Central). You can also use the Advanced screen to manage arbitrary annotations.
When creating or adding fields to a persistable data object, the JPA annotations that are added by default will generate a model that can be used by jBPM at runtime. In general, modifying the default configurations where the model will be used by processes is not recommended.
JBoss BPM Suite 6.2 onwards supports the use of JPA specific annotations, with Hibernate available as the default JPA implementation. Other JPA annotations are also supported where the JPA provider is loaded in the classpath.

Note

When adding an annotation in the Data Modeler, the annotation class should be on the workbench classpath, or a project dependency can be added to a .jar file that has the annotation. The Data Modeler will run a validation check to confirm that the annotation is on the classpath, and the project will not build if the annotation is not present.

4.14.3. Creating a Data Object (Not Persistable)

  1. In the Project Authoring perspective, click New Item → Data Object on the perspective menu. Enter the name and the location (the name has to be unique across the package, but it is possible to have two data object with the same name in two different packages). Uncheck the Persistable box to prevent the Data Object from being made persistable. Press the Ok button.
  2. Create fields of the data object:
    1. By clicking add field button in the main editor window, you can add a field to the object with the attributes Id, Label and Type. Required attributes are marked with *.
      • Id: field ID unique within the data object
      • Label: label to be used in the Fields panel (optional)
      • Type: data type of the field
    2. Click the Create button (the new field is created and the New field window closes) or the Create and continue button (the new field is created and the New field window remains open, so it is possible to continue adding more fields).
    Attributes can be edited selecting the attribute and editing the fields using the general properties screen to the right.

Important

To use a data object, make sure you import the data model into your resource. This is necessary even if the data model lives in the same Project as your resource (Business Process).

4.14.4. Persistable Data Objects

From JBoss BPM Suite 6.2 onwards, the Data Modeler is extended to support the generation of persistable Data Objects by checking the Persistable check box on the perspective menu when you create a new Data Object. Persistable Data Objects are based on the JPA specification. When the Persistable check box is selected when the object is created, the platform will set some configurations required for persistence by default. The object can also be made persistable after the object has already been createdThis can then be customized as required.

Procedure 4.7. Creating a Persistable Data Object

  1. When creating a persistable Data Object, the Identifier field id will be generated automatically, along with the @Entity annotation.
    Selecting the List option changes a property to have multiple values. For example, it can enable an attribute Name, to have a list of strings with multiple names.
  2. Create fields of the data object:
    1. By clicking add field button in the main editor window, you can add a field to the object with the attributes Id, Label and Type. Required attributes are marked with *.
      • Id: field ID unique within the data object
      • Label: label to be used in the Fields panel (optional)
      • Type: data type of the field
    2. Click the Create button (the new field is created and the New field window closes) or the Create and continue button (the new field is created and the New field window remains open, so it is possible to continue adding more fields).
    Attributes can be edited selecting the attribute and editing the fields using the general properties screen to the right.

4.14.5. Data Object Domain Screens

The following domain screen tabs can be selected from the right side of the Data Object editor screen.

Drools & jBPM

The Drools & jBPM screen allows configuration of Drools-specific attributes.
The Data Modeler in Business Central supports the editing of pre-defined annotations of fact model classes and attributes. The following Drools annotations are supported, and can be customized using the Drools & jBPM interface:
  • TypeSafe
  • Role
  • Timestamp
  • Duration
  • Expires
For the fields within the fact model, the position annotation is supported. The Drools & jBPM screen when a specific field is selected looks as follows:

Persistence

The Persistence screen can be used to configure attributes on basic JPA annotations for persistence. Fine tuning of annotations, or to add specific annotations, use the Advanced screen.
The Persistence screen when a specific field is selected looks as follows:
The following annotations can be managed via the Persistence screen.

Table 4.4. Type Annotations

AnnotationAutomatically Generated when Data Object is Persistable
javax.persistence.EntityYes
javax.persistence.TableNo

Table 4.5. Field Annotations

AnnotationAutomatically Generated when Data Object is Persistable
javax.persistence.IdYes
javax.persistence.GeneratedValueYes
javax.persistence.SequenceGeneratorYes
javax.persistence.ColumnNo
javax.persistence.OneToOneNo
javax.persistence.OneToManyYes - when a field has one or multiple values
javax.persistence.ManyToOneYes - when a field has multiple values
javax.persistence.ManyToManyNo
javax.persistence.ElementCollectionYes - generated by the UI when a new field has one or multiple of a base java type, such as Integer, Boolean, String. This annotation cannot be edited with the Persistence screen tool (use the Advanced screen tool instead).
All other JPA annotations can be added using the Advanced screen.

Advanced

The Advanced screen is used for fine-tuning of annotations. Annotations can be configured, added and removed using the Advanced screen. These can be any annotation that is on the classpath.
After you click on the add annotation option, the Add new Annotation window is displayed. It is required to enter a fully qualified class name of an annotation and by pressing the search icon, the annotation definition is loaded into the wizard. Then it is possible to set different annotation parameters (required parameters are marked with *).
If possible, the wizard will provide a suitable editor for the given parameters.
If it is not possible to provide a customized editor, the wizard will provide a generic parameter editor.
After you enter all the required parameters, the Finish button is enabled and the annotation can be added to the given field or data object.

4.14.6. Configuring Relationships Between Data Objects

When an attribute type is defined as another Data Object, the relationship is identified and defined by the symbol in the object attribute list. You can jump to the Data Object definition to view and edit by clicking on the icon.
Relationship customization is only relevant where the data object is persistable.
Relationships can be configured by selecting an attribute with a relationship and choosing the Persistence button on the right. Under Relationship Properties, click the Relationship Type property editing option.
Attempting to delete a Data Object that has a relationship with another Data Object will show the Usage Detected screen. It is still possible to delete the object from here, however this will stop your project from building successfully until the resulting errors are resolved.

4.14.7. Persistence Descriptor

When creating persistent data objects, the persistence.xml file is created by default when the user opens the project editor and selects Persistence Descriptor. It can then be configured via the Persistence Descriptor. The Persistence Descriptor is accessible by opening the Project Editor, and clicking Project Settings: Project General Settings → Persistence descriptor.
In the Advanced properties section, it is possible to change or delete all the properties generated by default and add new ones as well.
If you open the Project persisteable Data Objects section in the Persistence Descriptor, you will see that there are two available buttons:
  • Add class enables the user to add arbitrary classes to the persistence.xml file to be declared as entities.
  • Add project persistable classes will automatically load all the persisteable data objects in the current project.

4.14.8. Deployment Descriptor

Deployment Descriptor editor can also be accessed via the Project Editor menu, and allows configuration of the kie-deployment-descriptor.xml file for deployment in the jBPM runtime. Automatic configuration of the JPA Marshalling Strategies is only available in JBoss BPM Suite.