In this section, the Java APIs for working with Aspect Models are described. All of the components described in the
following subsections can either be included in your project using a dedicated dependency (as described in the
respective subsection), or you can use the aspect-model-starter artifact that aggregates all necessary dependencies:
sds-developer-guide:ROOT:partial$sds-aspect-model-starter-artifact.adoc
The error handling in many APIs is done using the
Try type provided by the Java library Vavr. This
is similar to a java.lang.Optional in that a successful result can be processed using .map() or .flatMap(), but if
an error occurs, the object can also provide the original exception. Compared with throwing exceptions, using a Try<T>
as a return type instead has the advantage of enabling composable and better readable code. Please see the
Vavr User Guide for more information.
The aspect-model-urn artifact provides a way to parse and validate Aspect model element URNs as described in the
specification.
import io.openmanufacturing.sds.aspectmodel.urn.AspectModelUrn;
final AspectModelUrn urn = AspectModelUrn.fromUrn( "urn:bamm:com.example:1.0.0#Example" );
System.out.println( urn.getNamespace() ); // com.example
System.out.println( urn.getName() ); // Example
System.out.println( urn.getVersion() ); // 1.0.0
System.out.println( urn.getUrnPrefix() ); // urn:bamm:com.example:1.0.0#To include the artifact, use the following dependencies:
sds-developer-guide:ROOT:partial$sds-aspect-model-urn-artifact.adoc
Aspect models are, like their Meta Model, described using the Resource Description Format (RDF, [rdf11]) and the Terse RDF Triple Language syntax (TTL, [turtle]). There are two ways of working with Aspect models: Either the model is loaded as an RDF model where the abstraction level directly corresponds to the RDF/Turtle serialization, or the RDF is parsed into a native Java Aspect model representation where the abstraction level corresponds to the BAMM concepts. Both approaches have different use cases and advantages and both are supported by the Aspect model Java tooling:
| Working on the RDF level | Using the Java Aspect model |
|---|---|
|
|
As a rule of thumb, if your use case mostly consists of consuming Aspect models, you should prefer the Java Aspect model, if you create or edit Aspect models, this is better done using the RDF API.
Loading an Aspect model in either the RDF-based or the Java Aspect model-based APIs does not only comprise parsing the Turtle file, but also the resolution of elements on the RDF level:
-
An Aspect model refers to meta model elements (everything that starts with
bamm:), and can refer to namespaces of shared elements (bamm-c,bamm-eandunit) -
It can also refer to elements from other Aspect models or model elements defined in separate Turtle files
You use the model resolver to load an Aspect model, which takes care of the first point: The used meta model elements
and elements from shared namespaces are automatically resolved and added to the loaded RDF model. For the second point,
you need to provide the model resolver with the information on where to find other Aspect models: In memory, in a local
file system, in a remote model repository etc. This is done using a resolution strategy, which is a function from some
type T to a Try of a RDF model. Several commonly used resolution strategies are readily available:
-
The
FileSystemStrategyresolves ajava.nio.file.Pathfor a file relative to the models directory -
The
UrnFileSystemStrategyresolves a AspectModelUrn to a file in the models directory -
The
InMemoryStrategyresolves a model against an already loaded Apache Jena RDF model -
The
SequenceStrategycan be used to chain two different strategies of the same type -
The
EitherStrategycan be used to chain two different strategies of different types
To implement custom resolution strategies (e.g., to resolve models against a different blob storage API), you can base
your implementation on the AbstractResolutionStrategy. Using the model resolver requires at least one resolution
strategy that can resolve AspectModelUrns (because references in an Aspect model to external model elements use
their respective URNs) and can use another resolution strategy, for example for file paths. The following sections show
examples for the different variants.
Consider the following example:
sds-developer-guide:ROOT:partial$sample-loading-aspect-model-rdf.adoc
To include the model resolver artifact, use the following dependencies:
sds-developer-guide:ROOT:partial$sds-aspect-model-resolver-artifact.adoc
Consider the following example:
sds-developer-guide:ROOT:partial$sample-loading-aspect-model-java.adoc
To include the Java Aspect model artifact, use the following dependencies:
sds-developer-guide:ROOT:partial$sds-aspect-meta-model-java-artifact.adoc
There are two serialization components available: One to turn a Java Aspect model into a Jena RDF model (the reverse
operation of what the AspectModelLoader does) and one to serialize the resulting Jena RDF model in Turtle syntax,
formatted according to the guidelines described in the BAMM specification.
sds-developer-guide:ROOT:partial$sample-serializing-aspect-model.adoc
To include the serializer artifact, use the following dependencies:
sds-developer-guide:ROOT:partial$sds-aspect-model-serializer-artifact.adoc
Consider the following example:
sds-developer-guide:ROOT:partial$sample-validating-aspect-model.adoc
To include the model validator, use the following dependencies:
sds-developer-guide:ROOT:partial$sds-aspect-model-validator-artifact.adoc
Different types of artifacts can be generated from an Aspect model. All corresponding generators are included in the following dependency:
sds-developer-guide:ROOT:partial$sds-aspect-model-document-generators-artifact.adoc
The documentation generation APIs provide methods that take as an argument a Function<String, java.io.OutputStream>.
This is a mapping function that takes a file name as an input (which is determined by the respective generator) and
returns a corresponding OutputStream, for example (but not necessarily) a FileOutputStream. By providing this
function when calling the generator method, you can control where the output is written to, even when the generator
creates multiple files. For the code examples in the following subsections, we assume that the following method is
defined for calling the generators:
OutputStream outputStreamForName( final String aspectFileName ) {
// Create an OutputStream for the file name, e.g. a FileOutputStream
...
}Using the AspectModelDiagramGenerator, automatically layouted diagrams can be created for Aspect models in the formats
PNG, SVG and Graphviz/DOT.
sds-developer-guide:ROOT:partial$sample-diagram-generation.adoc
A HTML reference documentation for an Aspect model can be generated as shown in the following code sample. The documentation contains an overview diagram and describes the model elements as specified in the Aspect model. Preferred names and descriptions in the respective language from the Aspect model are shown in the resulting document as part of each model element.
sds-developer-guide:ROOT:partial$sample-html-generation.adoc
The sample JSON payload generator is used to create a valid JSON payload for an Aspect model as it could be returned by
an Aspect that implements that Aspect model. This follows the
mapping rules as defined in the Meta Model specification.
The generator uses bamm:exampleValues of Properties if present, otherwise random values corresponding to the
respective data types are generated.
sds-developer-guide:ROOT:partial$sample-json-payload-generation.adoc
The JSON schema generator creates a JSON Schema that describes the payload for an Aspect model as it could be returned by an Aspect that implements that Aspect model. Currently, the generated schema corresponds to
sds-developer-guide:ROOT:partial$sample-json-schema-generation.adoc
The OpenAPI specification generator creates either a JSON Schema or a Yaml Spec that specifies an Aspect regarding to the OpenApi specification. The currently used versions corresponds Draft 4 of the JSON Schema specification, and 3.0.1.
sds-developer-guide:ROOT:partial$sample-openapi-generation.adoc
|
Note
|
For Enumerations with complex data types, the values are modelled as instances of the Entity defined as the Enumeration’s data type (see {bamm-documentation-url}/v{aspect-meta-model-version}/modeling-guidelines.html#declaring-enumerations[Declaring Enumerations] in the Modelling Guidelines for more information). In case the Entity instances contain Properties with a sorted collection as their data type, the order of the values of said collection in the Entity instances is not preserved in the generated OpenAPI specification. Preserving this order in OpenAPI is not possible at this point. |
Java code can be generated from an Aspect model in two ways:
-
The generated code represents the Aspect payload. Aspects and Entities become Java classes; their Properties become fields in the classes. Characteristics are not first-class elements, but are implicitly represented by the usage of corresponding data types (e.g. using
java.util.Setas the type for theSetCharacteristic of a Property) orjavax.validationannotations. The generated classes can be used in a straightforward fashion, but they do not contain information about the underlying Aspect model such as its version number. Parts of the Aspect model that have no representation in its corresponding JSON payload are not part of those classes either, in particular descriptions and preferred names. These classes are called POJOs (Plain Old Java Objects), as they do not contain logic but serve mainly as data containers. -
The generated code represents the Aspect model itself: It is a type-safe variant of the model and includes every information that is also present in the model such as Characteristics, descriptions including language tags and original XSD data types. It is however not intended to store payload corresponding to an Aspect. Theses classes are called static meta classes, because they are created at compile time (static) and talk about the structure of the information, not the information itself (meta).
Depending on the use case, you would either use one or both of the types simultaneously.
To include the Java generator, use the following dependencies:
sds-developer-guide:ROOT:partial$sds-aspect-model-java-generator-artifact.adoc
In the Java code generated from an Aspect model, the scalar Aspect model data types are mapped to native Java types. The following table lists the correspondences.
| Aspect model type | Java native type |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
POJO generation is straightforward; there are two minor differences to the generation of documentation artifacts.
Firstly, when instantiating the generator, you pass a flag indicating whether
Jackson annotations should be generated in the class. Secondly, the name
mapping function passed to the generation method takes a QualifiedName instead of a String, so that you can decide how
to handle the package structure of the class.
sds-developer-guide:ROOT:partial$sample-pojo-generation.adoc
For the generation of static meta classes, consider the following example:
sds-developer-guide:ROOT:partial$sample-static-meta-class-generation.adoc
To use the generated static meta classes, you need the following additional dependency:
sds-developer-guide:ROOT:partial$sds-aspect-static-meta-model-java-artifact.adoc
The meta model version migrator provides functionality to automatically migrate an Aspect model that uses an older version of the Aspect Meta Model to an Aspect model that uses a newer (usually the latest) version of the meta model.
This is shown in the following sample:
sds-developer-guide:ROOT:partial$sample-meta-model-version-migration.adoc
To use the meta model version migrator, you need the following dependency:
sds-developer-guide:ROOT:partial$sds-aspect-meta-model-version-migrator-artifact.adoc
In order to access the source RDF files that describe the BAMM vocabulary, shared Characteristics and Entities as well
as Units, you can add a dependency to the aspect-meta-model artifact. Note that this artifact does not contain any
Java classes.
sds-developer-guide:ROOT:partial$aspect-meta-model-artifact.adoc
In order to access the files via java.lang.Class#getResourceAsStream, you can refer to the following directory
structure that is present in the artifact:
.
├── characteristic
│ └── {aspect-meta-model-version}
│ ├── characteristic-definitions.ttl
│ ├── characteristic-instances.ttl
│ ├── characteristic-shapes.ttl
│ └── characteristic-validations.js
├── entity
│ └── {aspect-meta-model-version}
│ ├── FileResource.ttl
│ ├── ThreeDimensionalPosition.ttl
│ └── TimeSeriesEntity.ttl
├── meta-model
│ └── {aspect-meta-model-version}
│ ├── aspect-meta-model-definitions.ttl
│ ├── aspect-meta-model-shapes.ttl
│ ├── prefix-declarations.ttl
│ └── type-conversions.ttl
└── unit
└── {aspect-meta-model-version}
└── units.ttl|
Tip
|
If you use the artifact aspect-model-resolver instead (see section Loading and Saving Aspect Models for infos on the
dependency) you can directly refer to the RDF files using a resource URL:
|
import java.io.InputStream;
import java.net.URL;
import java.util.Optional;
import io.openmanufacturing.sds.aspectmodel.resolver.services.AspectMetaModelResourceResolver;
import io.openmanufacturing.sds.aspectmodel.resolver.services.MetaModelUrls;
import io.openmanufacturing.sds.aspectmetamodel.KnownVersion;
import io.openmanufacturing.sds.aspectmodel.vocabulary.BAMM;
final KnownVersion metaModelVersion = KnownVersion.BAMM_1_0_0;
final AspectMetaModelResourceResolver resolver = new AspectMetaModelResourceResolver();
final Optional<URL> characteristicDefinitionsUrl =
MetaModelUrls.url( "characteristic", metaModelVersion, "characteristic-instances.ttl" );
characteristicDefinitionsUrl.ifPresent( url -> {
final InputStream inputStream = resolver.openUrl( url );
resolver.loadTurtle( inputStream ).forEach( model -> {
// Do something with the org.apache.jena.org.rdf.model.Model
final BAMM bamm = new BAMM( metaModelVersion );
final int numberOfCharacteristicInstances =
model.listStatements( null, RDF.type, bamm.Characteristic() ).toList().size();
System.out.println( "Meta Model Version " + metaModelVersion.toVersionString()
+ " defines " + numberOfCharacteristicInstances + " Characteristic instances" );
} );
} );