From 250f70d1a8c3bf7bb49828a8f3fb17423e0c812f Mon Sep 17 00:00:00 2001 From: Sascha Doemer Date: Fri, 15 Dec 2023 13:39:51 +0100 Subject: [PATCH] Refactor README.md for readability and relevance This commit includes a significant update to the README file of the project. The file is now reformatted to increase readability; sentences are broken down into shorter, more digestible chunks. Changes also include up-to-date information about the software development kit (SDK) now supporting Java 17 and using Jakarta EE 9.1. Detailed guidance on dealing with communication certificates has been added, marking an important shift in how the SDK operates. --- README.adoc | 77 ++++++++++++++++++++++++++++++++++------------------- 1 file changed, 49 insertions(+), 28 deletions(-) diff --git a/README.adoc b/README.adoc index 3205b906..8b90103e 100644 --- a/README.adoc +++ b/README.adoc @@ -1,4 +1,3 @@ - = agrirouter-sdk-java :imagesdir: assets/images :toc: @@ -7,28 +6,35 @@ [abstract] == Abstract + image::agrirouter.svg[agrirouter] -The agrirouter is a universal data exchange platform for farmers and agricultural contractors that makes it possible to connect machinery and agricultural software, regardless of vendor or manufacturer. Agrirouter does not save data; it transfers data. -As a universal data exchange platform, agrirouter fills a gap on the way to Farming 4.0. Its underlying concept unites cross-vendor and discrimination-free data transfer. You retain full control over your data. Even data exchange with service providers (e.g. agricultural contractors) and other partners is uncomplicated: Data are very rapidly transferred via the online connection, and if you wish, is intelligently connected to other datasets. +The agrirouter is a universal data exchange platform for farmers and agricultural contractors that makes it possible to connect machinery and agricultural software, regardless of vendor or manufacturer. +Agrirouter does not save data; it transfers data. +As a universal data exchange platform, agrirouter fills a gap on the way to Farming 4.0. +Its underlying concept unites cross-vendor and discrimination-free data transfer. +You retain full control over your data. +Even data exchange with service providers, (e.g., agricultural contractors) and other partners is uncomplicated: +Data is very rapidly transferred via the online connection, and if you wish, is intelligently connected to other datasets. == Supporters & Maintainers + image::lmis.svg[agrirouter] -The LMIS AG is a recognised german IT service company, certified according to DIN EN ISO 9001:2015 and based in -Osnabrück, Berlin, Friedland and Wuppertal. Our core competence is the individual development, optimization and support -of IT solutions. We also provide professional IT consulting services and training courses. We have been supporting -the whole project during the development in the field of test management and are currently responsible for the development -support of the platform. +The LMIS AG is a recognised german IT service company, certified according to DIN EN ISO 9001:2015 and based in Osnabrück, Berlin, Friedland and Wuppertal. +Our core competence is the individual development, optimization and support of IT solutions. +We also provide professional IT consulting services and training courses. +We have been supporting the whole project during the development in the field of test management and are currently responsible for the development support of the platform. -We are active maintainers of the SDK and are using the SDK for internal testing as well. Therefore, we have a -high interest in a stable and usable interface to connect to the agrirouter. +We are active maintainers of the SDK and are using the SDK for internal testing as well. +Therefore, we have a high interest in a stable and usable interface to connect to the agrirouter. Feel free to get in touch by visiting our https://www.lmis.de[website] or contacting us via GitHub. == The current project you're looking at -This project contains the SDK for the communication with the agrirouter. Everything you need for the onboarding process, secure communication, and much more. +This project contains the SDK for the communication with the agrirouter. +Everything you need for the onboarding process, secure communication, and much more. == Releases @@ -36,11 +42,13 @@ The release workflow follows the https://docs.microsoft.com/en-us/azure/devops/r === Update from 1.4.x to 2.x -The update for the new release includes some breaking changes. To have a rough overview of what has to be done to have the new features from 2.x in your application, please see the following migration / update guide when updating. +The update for the new release includes some breaking changes. +To have a rough overview of what has to be done to have the new features from 2.x in your application, please see the following migration / update guide when updating. ==== Update the Maven dependencies -The first step is to update the coordinates of the dependencies. With the release 2.x the coordinates changed to a new name and a new version. +The first step is to update the coordinates of the dependencies. +With the release 2.x, the coordinates changed to a new name and a new version. [xml] ---- @@ -63,7 +71,8 @@ The first step is to update the coordinates of the dependencies. With the releas ==== Update package declarations for services and internal classes -Since the package declaration was updated along with the coordinates, there will be compiler errors that should be fixed. Some classes have moved to a more meaningful package. +Since the package declaration was updated along with the coordinates, there will be compiler errors that should be fixed. +Some classes have moved to a more meaningful package. image::migration_1-4_to_2-0/compiler-errors-before.png[Compiler errors before the migration.] @@ -73,7 +82,9 @@ image::migration_1-4_to_2-0/package-declaration-after-refactoring.png[Package de ==== Update the usage of the enums for message types -To have a better understanding about system message types and content message types, the declaration for the different types has changed. There are two new classes, the `ContentMessageType` for content messages and the `SystemMessageType` for system messages. The former technical message type will cause a compiler error, since it was replaced. +To have a better understanding about system message types and content message types, the declaration for the different types has changed. +There are two new classes, the `ContentMessageType` for content messages and the `SystemMessageType` for system messages. +The former technical message type will cause a compiler error since it was replaced. image::migration_1-4_to_2-0/former-technical-message-types.png[Former message types.] @@ -83,11 +94,11 @@ image::migration_1-4_to_2-0/system-message-type-afterwards.png[System message ty ==== Remove former URLs for ProtoBuf message types -With the new release the URLs can be fetched from the content message types and there is no need to put them into a helper method any longer. +With the new release, the URLs can be fetched from the content message types and there is no need to put them into a helper method any longer. image::migration_1-4_to_2-0/former-content-message-type-urls.png[Former content message types.] -With the new release fetch the URLs is way more comfortable. +With the new release, fetch, the URLs are way more comfortable. image::migration_1-4_to_2-0/type-urls-from-technical-message-types.png[Type URLs from content message types.] @@ -96,6 +107,11 @@ image::migration_1-4_to_2-0/type-urls-from-technical-message-types.png[Type URLs The http://www.agrirouter-middleware.de[agrirouter middleware] has been updated after the release of version 2.x and can be an indicator regarding the workload for the migration. Have a look at the following https://github.com/agrirouter-middleware/agrirouter-middleware/pull/12[PR #12] to see the necessary adaptions. +=== Update from 2.x to 3.x + +With the release of version 3.x, the SDK now supports Java 17 and uses Jakarta EE 9.1, with this version you are no longer able to use Java 8. +We will continue to support Java 8 with the 2.x branch, but we will not add any new features to the 2.x branch. + == Modules === `api` Module @@ -108,7 +124,8 @@ The `impl` module contains the implementation of the given SDK defined by the `a === `convenience` Module -The `convenience` module contains common implementations for different problems which are not located within the SDK. Those could be capability setting, MQTT client creation or other common problems that are normally not part of the SDK. +The `convenience` module contains common implementations for different problems which are not located within the SDK. +Those could be capability setting, MQTT client creation or other common problems that are normally not part of the SDK. === `test` Module @@ -116,9 +133,11 @@ The `test` module contains integration tests not only for the SDK, but also for === Integration -If you want to add a dependency feel free to fetch the latest release from Github Packages. Please find the documentation right https://help.github.com/en/packages/using-github-packages-with-your-projects-ecosystem/configuring-apache-maven-for-use-with-github-packages[here]. +If you want to add a dependency, feel free to fetch the latest release from GitHub Packages. +Please find the documentation right https://help.github.com/en/packages/using-github-packages-with-your-projects-ecosystem/configuring-apache-maven-for-use-with-github-packages[here]. -If you want to add the packages, you need to define the settings within your `pom` or the `settings.xml` otherwise. If you need an example, you can either have a look at the `ci/settings.xml` for general purpose or check out the snippet below for a custom `settings.xml`. +If you want to add the packages, you need to define the settings within your `pom` or the `settings.xml` otherwise. +If you need an example, you can either have a look at the `ci/settings.xml` for general purpose or check out the snippet below for a custom `settings.xml`. [xml] ---- @@ -154,28 +173,30 @@ If you want to add the packages, you need to define the settings within your `po ---- -You can use this `settings.xml` and include it during the build process in a specific way. Just use `mvn clean verify -s your_path_to_the_file/settings.xml` to use the settings if they are set in a local file. +You can use this `settings.xml` and include it during the build process in a specific way. +Just use `mvn clean verify -s your_path_to_the_file/settings.xml` to use the settings if they are set in a local file. === Compatibility -We are supporting JDK 8 and later, releases are build using a JDK 8 to have compatibility for most users. If you need to build the current development branch, please feel free build the branch on yourself and install it to your local repository. +We are supporting JDK 17 and later, releases are build using a JDK 17 to have compatibility for most users. +If you need to build the current development branch, please feel free to build the branch on yourself and install it to your local repository. -== Certificates for the communication +== Certificates for communication -We do not longer maintain the certificates within the SDK. -Maintaining them in the SDK would mean, that we have to release the SDK with every change of the certificate. -Therefore feel free to add the root certificates to a Java Key Store add reference it within your application. +We do no longer maintain the certificates within the SDK. +Maintaining them in the SDK would mean that we have to release the SDK with every change of the certificate. +Therefore, feel free to add the root certificates to a Java Key Store add reference it within your application. === Adding a certificate to the JKS -The certificates are PEM files which can be added directly to the keystore using the following command. +The certificates are PEM files that can be added directly to the keystore using the following command. [source] ---- keytool -importcert -file certificate.pem -keystore my_agrirouter_key_store.jks ---- -If you try to add the command, please be aware, that the containing PEM file has to fulfill the following requirements: +If you try to add the command, please be aware that the containing PEM file has to fulfill the following requirements: * The header and footer are included enclosed between five dashes. * There are no trailing spaces on each line.