Implementing Data Operations

It currently supports integration with the following Beams:

• minimal-jee-beam: base of the applicationApplicationThe overarching model container grouping all components, domain logic, and configurations for an enterprise solution.. Note: backend only, no struts and knockout support.
• standard-api-beam: control layerLayerLogical separation of functionality within a single system/application, focused on code organization. integration for standard-api.
• service-api-beam: control layerLayerLogical separation of functionality within a single system/application, focused on code organization. integration for jaxrs-service-api (rest-expandersExpanderA unit of generation that combines a data tree instance (functional M1 model) with a template to generate an artifact.).
• angular-beam: view layerLayerLogical separation of functionality within a single system/application, focused on code organization. integration for angular.
• process-automation-beam: workflow integration (triggers and events) for process-automation.

Additionally, there is support for the following community resources:

• enum-type-bundle: Declare and use Enums in the model.
• proxy-stub-test-expanders: Alternative implementation of Agents suitable for testing.
• batch-operation-expanders: Reimplements batched create/update/delete in a single flush, instead of flushing each record.

Naming Convention

All elements of a DataOperation should use camelCase naming. This means both a dataOperation and any parameters or groups have a camelCase name. The DataOperation itself is suffixed by the DataElement name. For example with an operation named register on DataElement City, the working name will be registerCity. The root group will always inherit the name of the DataOperation it is defined on. Any additional groups require a name which will be added as a suffix. For example registerCityAddress for a group named address on the dataOperation above.

Operation types use a dot-separated PascalCase convention. The standard typesStandard Types (StandardTypes). A set of pre-built ValueTypes (e.g., EmailAddress, Iban, TelephoneNumber) providing validated data types out of the box. include Create and BatchUpdate for example. When defining your own types, it is advised to prefix them as a means to add scope. For example Workflow.Trigger is defined for triggers within the workflow context. When creating project-specific types you should use the project name as the prefix.

Code Structure

One of the goals is to provide a strong interface and avoid coupling. This means there are very few places you have to look for customizations, which will be listed here.

• «DataOperation»Performer (logic/common): main implementation of a DataOperation. Any required services will be injected through class fieldsFieldA property of a DataElement expanded to a database column and user interface input element.. It will also handle any exceptions defined for error codes.
• «DataOperation»Mapper (logic/common): mapper from parameter object to element details. Not available for all operations.
• «DataOperation»Validator (logic/common): data validations of a DataOperation.
• «ParameterGroup»SharedValidator (shared/common): datatype validations of a ParameterGroup.
• «DataElement»QueryOperations (data/ejb3): query definitions for operations with Query type.

The entrypoint for all operations is «DataElement»OperationsBean, which makes it a useful place to visit to see what is happening. All operations are also exposed through the «DataElement»Agent to make them easy to access. This does impose some limitations on which names can be chosen, which is also enforced by a model-validation.

Another difference with previous implementations is that you will get a dedicated «DataOperation»Result class for each DataOperation. These follow a predefined interface and can be extended to provide type-specific additions. For example the Create operation adds a DataRef value accessible through .getCreatedReference(). All available error-codes can be handled separately if needed through the .hasError(ErrorCode) api. For validations a ValidationReport can be added and retrieved using .getValidationReport().

// interface of a DataOperation called 'publish' on DataElement 'Article'.
PublishArticleResult publish(ParameterContext<PublishArticle> parameterContext);

// Manual error handling of data-operations (not needed in expanded contexts)
PublishArticleResult result = agent.publish(context.withParameter(parameters));
if (result.hasValidationErrors()) {
  ValidationReport validationReport = result.getValidationReport();
  // Do something with the validation errors
} else if (result.hasError(MY_SPECIFIC_ERROR)) {
  // Check very specific error
} else if (result.isError()) {
  ErrorDescription description = result.getError(); // General error
} else {
  return result.getCreatedReference(); // specific value accessor.
}

Layers

DataOperations are "off" by default, which means they only span the minimal number of layersLayerLogical separation of functionality within a single system/application, focused on code organization. unless explicitly exposed further. The default scope depends on the DataOperation type, but most operations only need the Logic and Shared layersLayerLogical separation of functionality within a single system/application, focused on code organization.. An exception to this is the QueryOperation which also needs access to the Data layerLayerLogical separation of functionality within a single system/application, focused on code organization..

To expose an operation through additional layersLayerLogical separation of functionality within a single system/application, focused on code organization., specific options need to be used. These options are cascading meaning you can apply them to DataElement, Component or ApplicationApplicationThe overarching model container grouping all components, domain logic, and configurations for an enterprise solution. as well.

Option

control.operation.stdapi DataOperationDataElementComponentApplicationCascading

Enable JAX-RS Standard APIStandard API (stdAPI). A fully generated JAX-RS REST API expanding JSON:API compliant endpoints directly from JEE element models. (stdapi) CONTROL layerLayerLogical separation of functionality within a single system/application, focused on code organization. on a DataOperation.

<options>
  <control.operation.stdapi/>
</options>

Option

control.operation.svcapi DataOperationDataElementComponentApplicationCascading

Enable JAX-RS Service API (svcapi) CONTROL layerLayerLogical separation of functionality within a single system/application, focused on code organization. on a DataOperation.

<options>
  <control.operation.svcapi/>
</options>

Option

operation.exposeProxy DataOperationDataElementComponentApplicationCascading

Enable PROXY layerLayerLogical separation of functionality within a single system/application, focused on code organization. on a DataOperation. Enables proxy-expanderExpanderA unit of generation that combines a data tree instance (functional M1 model) with a template to generate an artifact. integration as well.

<options>
  <operation.exposeProxy/>
</options>