Skip to content

Commit

Permalink
Add AAS Registry Implementation (#29)
Browse files Browse the repository at this point in the history
  • Loading branch information
@geso02
geso02 authored May 31, 2023
1 parent b2b9f48 commit f5b97f5
Show file tree
Hide file tree
Showing 221 changed files with 18,108 additions and 0 deletions.
26 changes: 26 additions & 0 deletions basyx.aasregistry/.gitignore
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
*.class

# Mobile Tools for Java (J2ME)
.mtj.tmp/


# exclude jar for gradle wrapper
!gradle/wrapper/*.jar

# virtual machine crash logs, see http://www.java.com/en/download/help/error_hotspot.xml
hs_err_pid*

# build files
**/target
.gradle
build

# intellij files
/.idea/
/.project

# eclipse files
*.classpath
*.project

*/src/generated/
21 changes: 21 additions & 0 deletions basyx.aasregistry/LICENSE
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
MIT License

Copyright (c) 2022 DFKI GmbH

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
67 changes: 67 additions & 0 deletions basyx.aasregistry/README.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,67 @@
# Asset Administration Shell Registry

This is a Java-based implementation of the Asset Administration Shell Registry server and client based on the corresponding [Open-API specification](https://app.swaggerhub.com/apis/Plattform_i40/AssetAdministrationShellRegistryServiceSpecification/V3.0_SSP-001) of the German Plattform Industrie 4.0 and its specification document [Details of the Asset Administration Shell, Part 2](https://industrialdigitaltwin.org/wp-content/uploads/2023/04/IDTA-01002-3-0_SpecificationAssetAdministrationShell_Part2_API.pdf)

[basyx.aasregistry-client-native](basyx.aasregistry-client-native/README.md) can be used to interact with the backend to register or unregister descriptors and submodels or perform search operations.

[basyx.aasregistry-paths](basyx.aasregistry-paths/README.md) generates a builder class that can be used by the registry client to create search requests.

[basyx.aasregistry-plugins](basyx.aasregistry-plugins/README.md) contains maven plugins used by the other projects.

[basyx.aasregistry-service](basyx.aasregistry-service/README.md) provides the application server to access the AAS descriptor storage and offers an API for REST-based communication.

[basyx.aasregistry-service-basemodel](basyx.aasregistry-service-basemodel/README.md) provides a base model implementation that should be used if you do not need specific model annotations for your storage. It is used for the in-memory storage implementation and you need to add it explicitly as dependency for your server deployment as it is defined as 'provided' dependency in the [basyx.aasregistry-service](basyx.aasregistry-service/README.md) POM.

[basyx.aasregistry-service-base-tests](basyx.aasregistry-service-base-tests/README.md) provides helper classes and abstract test classes that can be extended in storage tests or integration tests. The abstract test classes already define test methods so that you will get a good test coverage without writing any additional test cases.

[basyx.aasregistry-service-mongodb-storage](basyx.aasregistry-service-mongodb-storage/README.md) provides a registry-storage implementation based on mongoDB that could be used as storage for [aasregistry-service](aasregistry-service/README.md). It comes with java-based model classes, annotated with mongoDB annotations.

[basyx.aasregistry-service-inmemory-storage](basyx.aasregistry-service-inmemory-storage/README.md) provides a non-persistent registry-storage implementation where instances are stored in hash maps. It can be used as storage for [aasregistry-service](aasregistry-service/README.md).

[basyx.aasregistry-service-kafka-events](basyx.aasregistry-service-kafka-events/README.md) extends basyx.aasregistry-service with a registry-event-sink implementation that delivers shell descriptor and submodel registration events using Apache Kafka. The default provided by aasregistry-service just logs the events.

[basyx.aasregistry-service-release-kafka-mongodb](basyx.aasregistry-service-release-kafka-mongodb/README.md) is used to combine the server artifacts to a release image that uses [Apache Kafka](https://kafka.apache.org/) as event sink and [MongoDB](https://www.mongodb.com/) as storage.

[basyx.aasregistry-service-release-kafka-mem](basyx.aasregistry-service-release-kafka-mem/README.md) is used to combine the server artifacts to a release image that uses Apache Kafka as event sink and an in-memory storage.

[basyx.aasregistry-service-release-log-mongodb](basyx.aasregistry-service-release-log-mongodb/README.md) is used to combine the server artifacts to a release image that logs registry events and uses MongoDB as data storage.

[basyx.aasregistry-service-release-log-mem](basyx.aasregistry-service-release-log-mem/README.md) is used to combine the server artifacts to a release image that logs registry events and an in-memory storage.

A docker-compose file that illustrates the setup can be found in the [docker-compose](docker-compose/docker-compose.yml) folder.


# Important

The REST API and the client implementation will not be modified until a new major version is released or an update of the openAPI definition. All server-side classes and the plugins are not intended to be used as programming library. They could be updated or removed then a new minor version is released.

# Build Resources

To build the images run these commands from this folder or for the parent project pom:

Install maven generate jars:

``` shell
mvn clean install
```

In order to build the docker images, you need to specify *docker.username* and *docker.password* properties (here without running tests):

``` shell
MAVEN_OPS='-Xmx2048 -Xms1024' mvn clean install -DskipTests -Ddocker.username=eclipsebasyx -Ddocker.password=""
```

You can now check your images from command-line and push the images:
``` shell
docker images ...
```
Or you can directly push them from maven.

``` shell
MAVEN_OPS='-Xmx2048 -Xms1024' mvn deploy -Ddocker.registry=docker.io -Ddocker.username=eclipsebasyx -Ddocker.password=pwd
```
In addition maven deploy will also deploy your maven artifacts, so you can do everything in one step.

Have a look at the *docker-compose* sub-folder to see how the created images could be referenced in docker-compose files.

Consider updating the [image name pattern](pom.xml#L16) if you want a different image name.
Empty file added basyx.aasregistry/basyx.aas-registry-service-release-kafka-mongo
View file
Empty file.
34 changes: 34 additions & 0 deletions basyx.aasregistry/basyx.aasregistry-client-native/README.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
# Basyx AAS Registry Client Native

This is the generated java openAPI client (based on native java with jackson parsing) that can be used to communicate with the AAS registry server.

To use the client in your maven projects define the following dependency:
```xml
<dependency>
<groupId>org.eclipse.digitaltwin.basyx.aasregistry</groupId>
<artifactId>basyx.aasregistry-client-native</artifactId>
</dependency>
```

If you also want to use the search API we highly recommend that you also include the search path builder class:
```xml
<dependency>
<groupId>dorg.eclipse.digitaltwin.basyx.aasregistry</groupId>
<artifactId>basyx.aasregistry-paths</artifactId>
</dependency>
```

The search API does not only provide concrete filtering but also similarity matches like words in a longer string. This code, for example, is a match for submodels that contain the word *robot* in their description:

```java
new ShellDescriptorQuery().queryType(QueryTypeEnum.MATCH).path(AasRegistryPaths.submodelDescriptors().description().text()).value("robot");
```

We also support these regular expressions. A query can be created like this:

```java
new ShellDescriptorQuery().queryType(QueryTypeEnum.REGEX).path(AasRegistryPaths.submodelDescriptors().description().text()).value("r[ob]{3}t");
```

As response to a search query, the client will receive a list of the filtered *AssetAdministrationShellDescriptors*. If you have enabled pagination, the list will only contain a subset of all results. By addressing an attribute of a submodel descriptor, the matching descriptors are shrunk so that they contain only matching submodels.

Empty file added basyx.aasregistry/basyx.aasregistry-client-native/open-api/.gitkeep
View file
Empty file.
120 changes: 120 additions & 0 deletions basyx.aasregistry/basyx.aasregistry-client-native/pom.xml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,120 @@
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
<modelVersion>4.0.0</modelVersion>

<parent>
<groupId>org.eclipse.digitaltwin.basyx</groupId>
<artifactId>basyx.aasregistry</artifactId>
<version>${revision}</version>
<relativePath>..</relativePath>
</parent>

<artifactId>basyx.aasregistry-client-native</artifactId>

<packaging>jar</packaging>
<properties>
<openapi.result.folder>${project.basedir}/${openapi.folder.name}</openapi.result.folder>
<openapi.result.file>${openapi.result.folder}/${openapi.name}</openapi.result.file>
</properties>
<build>
<plugins>
<plugin>
<artifactId>maven-clean-plugin</artifactId>
<configuration>
<filesets>
<fileset>
<directory>${project.basedir}/${generated.folder}</directory>
<excludes>
<exclude>**/.gitkeep</exclude>
</excludes>
<followSymlinks>false</followSymlinks>
</fileset>
<fileset>
<directory>${openapi.result.folder}</directory>
<excludes>
<exclude>**/.gitkeep</exclude>
</excludes>
<followSymlinks>false</followSymlinks>
</fileset>
</filesets>
</configuration>
</plugin>

<plugin>
<groupId>org.eclipse.digitaltwin.basyx</groupId>
<artifactId>basyx.aasregistry-plugins</artifactId>
<executions>
<execution>
<goals>
<goal>yaml-overlay</goal>
</goals>
</execution>
</executions>
<configuration>
<base>${project.basedir}/../${openapi.folder.name}/${openapi.base.name}</base>
<overlay>${project.basedir}/../${openapi.folder.name}/${openapi.extensions.name}</overlay>
<out>${openapi.result.file}</out>
</configuration>
</plugin>
<plugin>
<groupId>org.openapitools</groupId>
<artifactId>openapi-generator-maven-plugin</artifactId>
<executions>
<execution>
<goals>
<goal>generate</goal>
</goals>
<configuration>
<generatorName>java</generatorName>
<library>native</library>
<inputSpec>${openapi.result.file}</inputSpec>
<output>${project.basedir}/${generated.folder}</output>
<apiPackage>org.eclipse.digitaltwin.basyx.aasregistry.client.api</apiPackage>
<invokerPackage>org.eclipse.digitaltwin.basyx.aasregistry.client</invokerPackage>
<modelPackage>org.eclipse.digitaltwin.basyx.aasregistry.client.model</modelPackage>
<generateModels>true</generateModels>
<generateApis>true</generateApis>
<generateApiTests>false</generateApiTests>
<generateModelDocumentation>false</generateModelDocumentation>
<generateApiDocumentation>false</generateApiDocumentation>
<generateSupportingFiles>true</generateSupportingFiles>
<templateDirectory>${project.basedir}/templates</templateDirectory>
<supportingFilesToGenerate>AbstractOpenApiSchema.java,ServerConfiguration.java,ServerVariable.java,Configuration.java,JSON.java,ApiException.java,ApiResponse.java,ApiClient.java,Pair.java,RFC3339DateFormat.java</supportingFilesToGenerate>
<configOptions>
<java8>true</java8>
<dateLibrary>java8</dateLibrary>
<sourceFolder>java</sourceFolder>
</configOptions>
</configuration>
</execution>
</executions>
</plugin>

</plugins>
</build>

<dependencies>
<dependency>
<groupId>org.openapitools</groupId>
<artifactId>jackson-databind-nullable</artifactId>
</dependency>
<dependency>
<groupId>javax.annotation</groupId>
<artifactId>javax.annotation-api</artifactId>
</dependency>
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-databind</artifactId>
</dependency>
<dependency>
<groupId>com.fasterxml.jackson.datatype</groupId>
<artifactId>jackson-datatype-jsr310</artifactId>
</dependency>
<dependency>
<groupId>com.google.code.findbugs</groupId>
<artifactId>jsr305</artifactId>
</dependency>
</dependencies>

</project>
Loading

0 comments on commit f5b97f5

Please sign in to comment.