项目作者: SoftwareAG

项目描述 :
Maven archetype for cumulocity microservice
高级语言: Java
项目地址: git://github.com/SoftwareAG/cumulocity-microservice-archetype.git
创建时间: 2020-04-13T20:33:21Z
项目社区:https://github.com/SoftwareAG/cumulocity-microservice-archetype

开源协议:Apache License 2.0

下载


cumulocity-microservice-archetype

Maven archetype to generate cumulocity microservice project. Based on https://github.com/SoftwareAG/cumulocity-clients-java and https://cumulocity.com/guides/microservice-sdk/java/#java-microservice

The project will contain following project structure:

  1. project
  2. |-- pom.xml
  3. `-- src
  4. |-- main
  5. | | -- java
  6. | | `-- package
  7. | | | -- App.java
  8. | | | -- controller/ExampleController.java
  9. | | `-- service/ExampleService.java
  10. | | -- resources
  11. | | |-- application.properties
  12. | | |-- application-dev.properties
  13. | | |-- application-test.properties
  14. | | |-- application-prod.properties
  15. | | `-- banner.txt
  16. | `-- configuration
  17. | |-- cumulocity.json
  18. | `-- logging.xml

The project contains also an example REST controller which must be replaced or removed depending on your further development.
However the complete project is directly runnable without any additional changes. It uses also some best practices like:

  • using spring profiles (dev, test and prod)
  • using local configured application-dev.properties to run localy on development env
  • using Logback configuration file
  • using current java cumulocity microservice SDK + configuration via cumulocity.json
  • using custom banner with cumulocity SDK version
  • using JUnit 5 and SpringBootTest to check if context load is successful

In order to make it even faster to setup your project, the archetype contains a post-generation script which registers your microservice automatically on your tenant. This step is optional.

The post-generation script does following steps:

  • Generate microservice application on tenant
  • Subscribes microservice to tenant
  • Acquires microservice credentials
  • writes all information to application-dev.properties

Prerequisites

  • Java installed >= 11
  • Maven installed >= 3.6
  • Cumulocity IoT Tenant >= 1010.0.0
  • Cumulocity IoT User Credentials (Base64 encoded)

Run

Cloning this repository into you local GIT repository

  1. git clone https://github.com/SoftwareAG/cumulocity-microservice-archetype.git

Go to project

  1. cd cumulocity-microservice-archetype

Install archetype localy in your local maven repository

  1. mvn install

Go to the folder you want to generate the project

  1. cd ..

Generate C8y miroservice project using interactive mode

  1. mvn archetype:generate -DarchetypeGroupId=cumulocity.microservice -DarchetypeArtifactId=cumulocity-microservice-archetype

Note: In case you use go-c8y-cli you can use directly following environment variables C8Y_BASEURL and C8Y_HEADER_AUTHORIZATION in the command:

  1. mvn archetype:generate -DarchetypeGroupId=cumulocity.microservice -DarchetypeArtifactId=cumulocity-microservice-archetype -DdevC8yBaseURL=%C8Y_BASEURL% -DdevC8yUserCredentialsBASE64=%C8Y_HEADER_AUTHORIZATION%

Step 1: Define your microservice name

  1. [INFO] Generating project in Interactive mode
  2. [INFO] Archetype [cumulocity.microservice:cumulocity-microservice-archetype:1.0.0-SNAPSHOT] found in catalog local
  3. Define value for property 'microserviceName':

If your microservice name has more than one words, seperate the words by ‘-‘

Step 2: Define your artifact id (default value cumulocity-microservice-)

  1. [INFO] Generating project in Interactive mode
  2. [INFO] Archetype [cumulocity.microservice:cumulocity-microservice-archetype:1.0.0-SNAPSHOT] found in catalog local
  3. Define value for property 'microserviceName': hello-devices
  4. [INFO] Using property: groupId = cumulocity.microservice
  5. [INFO] Using property: version = 1.0.0-SNAPSHOT
  6. [INFO] Using property: c8yVersion = 1013.0.0
  7. [INFO] Using property: devC8yBaseURL = null
  8. [INFO] Using property: devC8yUserCredentialsBASE64 = null
  9. Define value for property 'artifactId' cumulocity-microservice-hello-devices: :

You can now just hit enter to continue with default or enter your own artificat id.

Step 3: Define your package name (default value cumulocity.microservice.)

  1. [INFO] Generating project in Interactive mode
  2. [INFO] Archetype [cumulocity.microservice:cumulocity-microservice-archetype:1.0.0-SNAPSHOT] found in catalog local
  3. Define value for property 'microserviceName': hello-devices
  4. [INFO] Using property: groupId = cumulocity.microservice
  5. [INFO] Using property: version = 1.0.0-SNAPSHOT
  6. [INFO] Using property: c8yVersion = 1013.0.0
  7. [INFO] Using property: devC8yBaseURL = null
  8. [INFO] Using property: devC8yUserCredentialsBASE64 = null
  9. Define value for property 'artifactId' cumulocity-microservice-hello-devices: :
  10. Define value for property 'package' cumulocity.microservice.hello-devices: : cumulocity.microservice.hello_devices

You can now just hit enter to continue with default or enter your own artificat id. !!! Beaware that ‘-‘ can’t be used at java packages. In that case you must replace ‘-‘ with ‘_’. !!!

Step 4.1: Confirm your configuration with ‘Y’ without running post-generation script

  1. [INFO] Generating project in Interactive mode
  2. [INFO] Archetype [cumulocity.microservice:cumulocity-microservice-archetype:1.0.0-SNAPSHOT] found in catalog local
  3. Define value for property 'microserviceName': hello-devices
  4. [INFO] Using property: groupId = cumulocity.microservice
  5. [INFO] Using property: version = 1.0.0-SNAPSHOT
  6. [INFO] Using property: c8yVersion = 1013.0.0
  7. [INFO] Using property: devC8yBaseURL = null
  8. [INFO] Using property: devC8yUserCredentialsBASE64 = null
  9. Define value for property 'artifactId' cumulocity-microservice-hello-devices: :
  10. Define value for property 'package' cumulocity.microservice.hello-devices: : cumulocity.microservice.hello_devices
  11. Confirm properties configuration:
  12. microserviceName: hello-devices
  13. groupId: cumulocity.microservice
  14. version: 1.0.0-SNAPSHOT
  15. c8yVersion: 1013.0.0
  16. devC8yBaseURL: null
  17. devC8yUserCredentialsBASE64: null
  18. artifactId: cumulocity-microservice-hello-devices
  19. package: cumulocity.microservice.hello_devices
  20. Y: : Y

Now you have created your microservice project successfully! In case your devC8yBaseURL and devC8yUserCredentialsBASE64 variable wasn’t set, you can continue with Step 4.2, in order to initialze them via interactive mode and run the post-generation script. However running this script is optional!

IMPORTANT!!!

If you haven’t setup your application-dev.properties to a specific tenant, the predefined unit test will not succeed! This unit test is starting the spring boot application and checks if the application is successfully starting. The microservice can’t start if the c8y configuration isn’t setup. However you can build with skipping the test by:

  1. mvn clean install -Dmaven.test.skip=true

Step 4.2: Confirm your configuration with ‘N’ with running post-generation script

And repeate step 1 - 3 and insert devC8yBaseURL and devC8yUserCredentialsBASE64

  1. Y: : N
  2. Define value for property 'microserviceName': hello-devices
  3. Define value for property 'groupId' cumulocity.microservice: :
  4. Define value for property 'version' 1.0.0-SNAPSHOT: :
  5. Define value for property 'c8yVersion' 1013.0.0: :
  6. Define value for property 'devC8yBaseURL': https://ms-template.eu-latest.cumulocity.com
  7. Define value for property 'devC8yUserCredentialsBASE64': Basic XXXXX
  8. Define value for property 'artifactId' cumulocity-microservice-hello-devices: :
  9. Define value for property 'package' cumulocity.microservice.hello-devices: : cumulocity.microservice.hello_devices
  10. Confirm properties configuration:
  11. microserviceName: hello-devices
  12. groupId: cumulocity.microservice
  13. version: 1.0.0-SNAPSHOT
  14. c8yVersion: 1013.0.0
  15. devC8yBaseURL: https://ms-template.eu-latest.cumulocity.com
  16. devC8yUserCredentialsBASE64: Basic XXXXX
  17. artifactId: cumulocity-microservice-hello-devices
  18. package: cumulocity.microservice.hello_devices
  19. Y: : Y

Step 5: Build your fresh generated project

Go to the project folder

  1. cd cumulocity-microservice-hello-devices/

and build the project:

  1. mvn install

Running the microservice locally you have to add microservice service user to application-dev.properties, have you run the script with step 4.2 the properties are automatically configured

  1. C8Y.bootstrap.tenant=<tenant ID>
  2. C8Y.baseURL=<URL>
  3. C8Y.bootstrap.user=<service-user>
  4. C8Y.bootstrap.password=<service-user-password>

Step 6: Start the microservice and test

Go to target and run the spring boot appliation

java -jar cumulocity-microservice-hello-devices-1.0.0-SNAPSHOT.jar

Open the browser and open link http://localhost:8080/api/hello/devices, you have to insert your Cumulocity credentials, keep in mind to set the tenant Id in front of your user name like t2134/alexander.pester@softwareag.com.

Now your microservice is ready to evolve!!!

For building docker container please change property in pom file to:

  1. <c8y.docker.skip>false</c8y.docker.skip>

Live Demo

https://youtu.be/2j21ULZbtlg

Authors

Alexander Pester

Disclaimer

These tools are provided as-is and without warranty or support. They do not constitute part of the Software AG product suite. Users are free to use, fork and modify them, subject to the license agreement. While Software AG welcomes contributions, we cannot guarantee to include every contribution in the master project.

Contact

For more information you can Ask a Question in the TECHcommunity Forums.

You can find additional information in the Software AG TECHcommunity.


Contact us at TECHcommunity if you have any questions.