License • Issues • Discussions • Wiki • Contributing • Code of Conduct
All participants of IDS-based data ecosystems must be able to communicate with each other. Even though different participants may have different implementations of IDS-Connectors, they all need to send and receive IDS-Messages. This commonality is addressed by the IDS-Messaging-Services, which provide a lightweight implementation for IDS-Message-Handling. The IDS-Messaging-Services offer open-source functionality for sending IDS-Messages as well as interfaces for processing received IDS-Messages. The architecture relies on a modern modular architecture-approach so that the functionalities needed for communication in a data ecosystems can be easily selected specific to the infrastructure components present in the data ecosystems. In addition, advanced functionalities are implemented, such as checking the validity of the Dynamic-Attribute-Token of incoming messages.
This project is currently no longer maintained but looking for new maintainers.
Applications for maintainers shall be directed to the International Data Spaces Association.
This project was previously maintained by Fraunhofer ISST and after that by sovity GmbH. Please do not approach former maintainers. If you have questions, plase open an issue / discussion for the community or approach the International Data Spaces Association.
The IDS-Messaging-Service follows the SemanticVersioning system.
The following IDS-Infomodel-Artifacts are used as dependencies.
| Group | Artifact | Version |
|---|---|---|
| de.fraunhofer.iais.eis.ids.infomodel | java | 4.2.7 |
| de.fraunhofer.iais.eis.ids | infomodel-serializer | 4.2.8 |
| de.fraunhofer.iais.eis.ids | interaction | 4.2.7 |
The following transmission options for IDS-Messages are currently supported:
- HTTP Multipart
Currently being worked on:
- IDS-LDP / REST
Supported out-of-the-box connectivity to the following IDS-Infrastructure-Components with advanced functionality:
- Other IDS-Connectors
- IDS-AppStore
- IDS-Broker
- IDS-ClearingHouse
- IDS-DAPS
- IDS-ParIS
- IDS-VoCol
- 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. 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:
- appstore
- broker
- clearinghouse
- paris
- vocol
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.
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 dependencies 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.*",
"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.
For extended instructions and info on the other modules, see the GitHub-Wiki.
Log-codes exist for different log-levels. They allow easy search for the code location that produced the log.
Syntax: IMS-XY-L-1234, shortened to: IMSXYL1234
- IMS = IDS-Messaging-Services
- XY = Subsystem Module (CO Core, AP AppStore, BR Broker, CL ClearingHouse, ME Messaging, PA Paris, VO Vocol)
- L = Event Severity (E Error, W Warn, D Debug, I Info)
- 1234 = Log identifier
Will e.g. print as [code=(IMSCOE0001)]: IDS-Messaging-Services Core-Module Error 0001.
This project has a GitHub-Wiki where more details about the individual java-modules and their functionalities are documented.
You are very welcome to contribute to this project when you find a bug, want to suggest an improvement, or have an idea for a useful feature. Please find a set of guidelines at the CONTRIBUTING-Guideline and the CODE_OF_CONDUCT-Guideline.
For any questions or suggestions please refer to the GitHub-Issues or the GitHub-Discussion area.
This project is licensed under the Apache License 2.0 - see the LICENSE for details.