01. Getting Started
Following is a quick guide on how to integrate the IDS-Messaging-Services into a project with an initial example of sending and receiving IDS-Messages. In addition, there are pre-built methods for the supported IDS-Infrastructure-Components in the corresponding modules and their Service-Classes, which can be used instead of having to implement the specific message types yourself. This quick guide is also in the readme.
- The IDS-Messaging-Services use asymmetric encryption concepts and requires public and private key of the Connector-Instance.
- The IDS-Messaging-Services utilize contents of the IDSConfiguration Model which is part of the IDS Information Model. Therefor a configmodel.json-file should exist to load the configuration of the IDS-Connector. For example, the configuration file should reference the key- and trust-store.
- The IDS-Messaging-Services assume a SpringBoot project and therefore require various specific SpringBoot functionalities.
- Settings in the Application Properties
The Java-modules provided by the project are accessible as Maven artifact dependencies. These artifacts are hosted on sovity's Azure Repo. In order for the artifacts to be found, the repository must be added as a repository in the project's pom:
<repository>
<id>sovity-public</id>
<url>https://pkgs.dev.azure.com/sovity/5bec6cbd-c80a-47ac-86ce-1deb26cee853/_packaging/artifact/maven/v1</url>
</repository>The current module artifact structure of the IDS-Messaging-Services is built along the different IDS-Infrastructure-Components, which are currently supported with advanced functionalities out-of-the-box.
Modules with basic functions:
- core
- messaging
Modules for different infrastructure components:
- broker
- clearinghouse
Module with all functionalities, can be used instead of integrating the infrastructure modules individually:
- full
In general, the core-module artifact is the main module artifact with the configuration of the IDS-Messaging-Services. The messaging-module artifact provides all needed functionalities to send and receive IDS-Messages. The messaging-module artifact in turn holds the core-module artifact as a dependency. So it is enough to specify the messaging-module artifact in the project's pom and the functionality of the core-module artifact will be loaded automatically.
The individual module-artifacts of the IDS-Infrastructure-Components in turn require functionalities of the messaging-module artifact and have it therefore linked as a dependency in each module case. This simplified architecture means that it is sufficient, for example, to integrate the broker-module artifact into the project's pom, which automatically makes the functionalities of the messaging- and thus also the core-module artifact available.
The full module includes all out-of-the-box supported infrastructure components as dependencies and therefore provides an easy way to integrate all functionalities at once.
So, if an IDS-Connector should be implemented, in whose data ecosystem an IDS-Broker occurs as IDS-Infrastructure-Component, the following entry in the project's pom is completely sufficient as dependcies to get all needed functionalities to exchange messages with the IDS-Broker with advanced functionalities, without the need to use the full-module:
<dependency>
<groupId>ids.messaging</groupId>
<artifactId>broker</artifactId>
<version>IDS_MESSAGING_SERVICES_VERSION</version>
</dependency>Of course, the entry IDS_MESSAGING_SERVICES_VERSION must be exchanged with the desired version number of the IDS-Messaging-Services artifact.
For a detailed description of the usage of the different IDS-Messaging-Services artifacts see the Wiki pages of this project.
Following is a first step guide to using the IDS-Messaging-Services after including the required dependencies in the project's pom.
Add the @ComponentScan annotation to the SpringBoot-Application and scan for the IDS-Messaging-Services packages. This can be implemented, for example, as follows using wildcards:
@ComponentScan({
"ids.messaging.*"
})Start implementing Message-Handler e.g. as instances of RequestMessage which your IDS-Connector should be able to process as received IDS-Message. An example for a MessageHandler is given below. The following message-handler receives the arrived message and sends the received message payload directly back to the sending IDS-Connector. This can be customized as desired and serves only as an example.
@Component
@SupportedMessageType(RequestMessageImpl.class)
public class RequestMessageHandler implements MessageHandler<RequestMessageImpl> {
private static final Logger LOGGER = LoggerFactory.getLogger(RequestMessageHandler.class);
private final Connector connector;
private final DapsTokenProvider provider;
public RequestMessageHandler(final ConfigContainer container,
final DapsTokenProvider provider) {
this.connector = container.getConnector();
this.provider = provider;
}
/**
* This message implements the logic that is needed to handle the message. As it just returns the input as string
* the messagePayload-InputStream is converted to a String.
*
* @param requestMessage The RequestMessageImpl (part one of the multipart message) containing interesting meta data.
* @param messagePayload The received payload that has to be handled here
* @return received payload as string, wrapped inside a @{@link BodyResponse}
*/
@Override
public MessageResponse handleMessage(final RequestMessageImpl requestMessage,
final MessagePayload messagePayload) {
LOGGER.info("Received a RequestMessage!");
try {
final var receivedPayload = IOUtils.toString(messagePayload.getUnderlyingInputStream(), StandardCharsets.UTF_8.name()) + " - from RequestMessage!";
final var message = new ResponseMessageBuilder()
._securityToken_(provider.getDAT())
._correlationMessage_(requestMessage.getId())
._issued_(IdsMessageUtils.getGregorianNow())
._issuerConnector_(connector.getId())
._modelVersion_(this.connector.getOutboundModelVersion())
._senderAgent_(connector.getId())
.build();
return BodyResponse.create(message, receivedPayload);
} catch (Exception e) {
return ErrorResponse.withDefaultHeader(RejectionReason.INTERNAL_RECIPIENT_ERROR,
e.getMessage(),
connector.getId(),
connector.getOutboundModelVersion());
}
}
}Sending IDS-Messages: Now that messages can be received, the functionality for sending IDS-messages is shown with an example.
The following is an example without connection to an IDS-Infrastructure-Component. The idsHttpService can be accessed at any time to send a message to any recipient. For the messaging to the supported IDS-Infrastructure-Components, however, ready-made methods are already available in the respective modules, so that the specific message itself does not have to be created. The following is a minimal example, which assumes that only the messaging-module is present.
Building the IDS-message for a specific message type:
Message message = new RequestMessageBuilder()
._issued_(IdsMessageUtils.getGregorianNow())
._modelVersion_(baseConnector.getOutboundModelVersion())
._issuerConnector_(baseConnector.getId())
._senderAgent_(baseConnector.getId())
._securityToken_(tokenProvider.getDAT())
.build();
MultipartBody body = this.buildRequestBody(InfomodelMessageBuilder.messageWithString(message, payload));
final var response = idsHttpService.sendAndCheckDat(body, targetUri);The above is a standard example of HTTP-Multipart using the services' sendAndCheckDat()-method. In addition, there are other methods like a plain send()-Method which will not check the DAT of the received response to the message.
The sendAndCheckDat() returns a Map<String, String> where, for example, response.get("header") and response.get("payload") can be used to access the message-fields.