Module for logging- and MDC-related JakartaEE components without any dependencies.

Contains java classes that serve as ancestors for the entire Coffee javaEE solution set.

This is where the java.time (java 8+) class for handling XSD universal adapters and basic paths to rest endpoints is served.

The module contains the basic exception classes. All other exceptions that are created, can only be derived from these.

Its content should preferably be XSDs to serve as guides on projects. They should preferably contain very universal XSD simple and complexType, which projects can bend to their own image.

This module is used to generate the Coffee DTO. It is organized separately to be easily replaced from the dependency structure.

The module serves as a sample implementation for coffee-dto-base, coffee-dto-xsd and coffee-dto-gen. Projects using Coffee will include it. If the DTOs generated by Coffee do not match the target project, you will have to excelude them at this module.

By itself it is a universal, usable module.

Coffee uses its own logging system, for several reasons:

Each class has its own logger, loggers are not inheritable, not transferable. The CDI + jboss logger provides the basis for using it:

If a parameter is included in the logging, it should be placed between "[parameter]" characters EXCEPT.

The purpose of this is to be able to immediately identify the variable value when looking at the log, and also if it has a value of "" (empty String) or null.

As a configuration solution we use the microprofile-config solution.

In short, what is it? You can specify configuration parameters in a wide range of ways. It is not enough to burn a configuration parameter into some properties file, because it may have a different value from environment to environment. The values can be specified at a separate level, be it ETCD, properties, system property, environment property or whatever. The microprofile-config can look up a given key from all available sources and use the highest priority value. Basic use cases:

The annotations in the hu.icellmobilsoft.coffee.cdi.trace.annotation package allow the modules of coff::ee to provide trace information. The annotations are used to allow coff::ee modules to plug into an existing trace flow or to start a new flow.

The internal logic of coffee trace implementation is independent and selectable within the projects. If no trace implementation is selected, then by default, no trace propagation occurs in the system.

The internal logic of coffee has a metric implementation that is independent and selectable within projects. If no metric implementation is selected, then the default Noop*MetricsHandler is activated in the system.

The choice of implementations can be found in the coffee-module-mp-metrics/micrometer documentation.

This class allows you to query type specific configurations.

Similar to the ConfigurationHelper class, but uses @ApplicationScope level caching, where cached values are stored for 30 minutes. It allows these cached values to be immediately which can be used to build additional logic (e.g. change the value externally in ETCD), and then topic JMS to forget the values and immediately read them again).

Contains helper methods with @Transactional annotations for @FunctionalInterfaces declared in the FunctionalInterfaces class.

Thus, it is possible that if the first entry point of a class is not in a transaction, but we want to run a code snippet in a transaction within it, we just need to highlight the desired snippet in a private method or in any @FunctionalInterface provided by coffee and call the corresponding method of TransactionHelper, which will perform the transactional execution.

This avoids the need to highlight the logic to be run in the transaction in a public method with @Transactional annotation and call the method created inside the class via CDI.current() or to do the same by highlighting it in a separate class.

BatchService is used to perform bulk database operations (insert, update, delete) in a group.
It mainly contains batch operations based on PreparedStatement, in which SQL compilation is performed with the support of Hibernate.

The DatabaseHealth can check if the database is reachable. The DatabasePoolHealth can check how loaded the connection pool used for operations to the database is.

This function is based on metric data, so it is necessary that one of the implementations is activated.

This class is used to log HTTP request-response requests to the application. It is activated manually at the project level using the following pattern:

The HTTP request-response log itself is compiled by the hu.icellmobilsoft.coffee.rest.log.RequestResponseLogger class, and can be used in other situations if needed, for example logging an error.

During request logging, sensitive data is masked both from the headers and from the json/xml body (e.g. X-PASSWORD: 1234 instead of X_PASSWORD: *). The data is determined whether it is to be protected based on its key (key for headers and JSON content, tag for XML), which by default is a key corresponding to the regexes [\w\s]*?secret[\w\s]*? or [\w\s]*?pass[\w\s]*? (e.g. userPassword, secretToken, …​), if needed in the project, the regex can be overwritten by specifying the configuration coffee.config.log.sensitive.key.pattern in one of the default microprofile-config sources (sys var, env var, META-INF/microprofile-config.properties), multiple patterns can be specified separated by commas.

This class works similarly as the BaseRestLogger. The only difference is that it uses less memory, because it doesn’t copy the streams of the request and response entities for logging, but collects the entities while reading and writing them.

It is activated manually at the project level using the following pattern:

The HTTP request-response log itself is compiled by the hu.icellmobilsoft.coffee.rest.log.optimized.RequestResponseLogger class, with the temprorary @Named("optimized_RequestResponseLogger") annotation. The request and response entity log limits are determined here according to whether the request or response entity is application/octet-stream or multipart/form-data and the REST interface is not annotated with the LogSpecifier then we limit the log size.

REST logging can be customized per endpoint with the hu.icellmobilsoft.coffee.rest.log.annotation.LogSpecifier annotation, this can be specified multiple times in one place, and its scope can be limited by the target field, field, of which more than one can be specified in the annotation (activated by default for all targets); this gives the possibility to customize REST request-response, microprofile-client request-response separately.

Specifiable targets are enum values of hu.icellmobilsoft.coffee.rest.log.annotation.enumeration.LogSpecifierTarget:

Currently the LogSpecifier is prepared for the following cases:

The purpose of this class is to summarize the transformations and manipulations related to XML objects. Its structure is fully modular, you can customize everything to your project’s needs using the CDI. Its modules provide this functionality by default:

The description in XSD Catalog and generation deals with XSD generation. This section focuses on the activation in the code - XML validation using XSD catalog.

The whole function is performed by the JaxbTool class. It is intentionally built in a modular way so that it can be easily adapted to needs. As described above, Coffee includes an implementation of IXsdResourceResolver, that can read the schema structure specified in the XSD Catalog. This class is called

Since we use maven-bound dependencies to generate the XSD Catalog, such as:

So you need to be prepared to manage the maven: URI protocol. This is done in the hu.icellmobilsoft.coffee.tool.protocol.handler.MavenURLHandler class, which needs to be activated. This can be done in several ways, the recommended solution is the following:

So you need to create the file src/main/resources/META-INF/services/java.net.spi.URLStreamHandlerProvider and include the class that handles it (Coffee part).

The framework supports JSON format messages in addition to XML for REST communication. To serialize/deserialize these messages, it uses an external module, Gson, maintained by Google The framework complements/upgrades Gson with some custom adapters. Below is an example JSON, and its own added adapters. The ISO 8601 standard is used for the time-related values, except in one case. In the case of the Date class, the format has been changed to the universal UNIX epoch in milliseconds

Note: Most of the JSON-related operations are of a utility nature and are publicly available under coffee-tool in the JsonUtil class.

Microprofile OpenApi provides the ability to set additional OpenApi configuration via the implementation of the org.eclipse.microprofile.openapi.OASFilter interface. The implementation of hu.icellmobilsoft.coffee.rest.filter.OpenAPIFilter contains within the project the generic error codes related to coffee error handling and the corresponding response objects, which are generally applied to all endpoints crossed by the filter, providing more accurate documentation compared to the openapi.yml config file written in microservices using coffee, since this information is dynamically loaded. To activate this filter in the configuration, you need to specify mp.openapi.filter in the configuration key hu.icellmobilsoft.coffee.rest.filter.OpenAPIFilter, which is the class that implements it.

Example in a microprofile default properties config:

A module contains application/octet-stream + BaseResultType writert. This allows the system to send an octet-stream response to any own DTO BaseResultType object. This is very useful, for example, when generating a file with an error.

The module contains a Deltaspike inspired ProjectStage object which can be injected. Its role is to be able to specify at runtime, via configuration, whether the project is running in production, development or test mode.

It can be used by specifying 2 configurations:

The values that can be specified are converted to hu.icellmobilsoft.coffee.rest.projectstage.ProjectStageEnum. Each enum value contains which config value represents which enum.

Configurations can be specified from multiple locations using Microprofile Config, but only the first one in the order described above will be considered.

Currently, in the project, if the ProjectStage value is not Production, the system will return a broader response for errors.

Using this works as follows:

For possible further breakdowns, use as follows:

The default implementor of Jsonb is Eclipse Yasson. This can be changed using default configurations:

In the above configuration, 2 elements can be set:

A collector for general gRPC handling of the Coff:ee API (annotations, version, …​).

A collector for general Protobuf and gRPC classes. It includes exception handling, status handling, and other general CDI (Contexts and Dependency Injection) and Coff:ee functionalities.

A generic ExceptionMapper interface following the JAX-RS pattern. It allows converting a specific Exception type to a gRPC Status using the capabilities provided by CDI.

A helper tool used for proto → class generation. The logic utilizes the Mustache template system, which will be present in the com.salesforce.jprotoc.ProtocPlugin system.

Example usage in a pom.xml:

A more complex example can be found in the backend-sampler project’s pom.xml.

Module containing a CDI-compatible implementation of a gRPC server.

It reads all classes implementing IGrpcService and delegates them to the gRPC service through the GrpcServerManager.

Implemented features:

It includes support for implementing a gRPC client. This includes:

The gRPC server and client can optionally activate interceptors to provide metric data. For this, only the inclusion of the Maven dependency is required:

If the metric module is not included at the dependency level, the server/client operation remains unchanged, only metric data is not provided.

Provided metrics:

The gRPC server and client can optionally activate interceptors to provide tracing data. For this, only the inclusion of the Maven dependency is required:

If the tracing module is not included at the dependency level, the server/client operation remains unchanged, only tracing data is not provided.

A collector of generated schema2proto for general XSD descriptors (coffee-dto-xsd module) and other manually created proto files. This package serves to use Coff:ee proto files, so projects don’t need to generate them again.

Unfortunately, the used schema2proto plugin is not compatible with the Windows operating system, so automatic compilation generation is not set. If there are any changes to the XSD files, the following command needs to be executed on a Linux-compatible system:

The schema2proto parameter activates XSD → proto generation, and the copy-generated-sources parameter activates copying the generated proto files into the sources. Afterward, the changes will appear in the git diff.

Contains all Coff:ee proto files and their generated classes. The plugin generates an interface descriptor that can be implemented in a full CDI environment. It also generates a BindableService implementation that delegates gRPC calls to the implemented interface.

The purpose of ID generation is to work with unique and non-sequential ID values (strings) under all circumstances.^[1] For generation, we use the EntityIdGenerator.java class, this is used by default with annotation on the entity java class, but if needed it can be called directly with the generate() method. Operationally, the generate method will generate a new ID for the entity if the ID value is not already set (null), otherwise it will use the existing ID.

The algorithm will generate an ID of up to 16 lengths [0-9a-zA-Z] using random characters, taking into account the nanosecond part of the current time, e.g. '2ZJMG008YRR4E5NW'

Example code for an identifier used on the AbstractIdentifiedEntity.java class:

Example code for an Entity where an identifier is required:

We have the option to set the timezone through environment variable or system property. If we don’t set this, we’ll use the system’s timezone by default.

The variable: COFFEE_MODEL_BASE_JAVA_TIME_TIMEZONE_ID

The audit columns are used to track all table-level movements, e.g. insertion or modification of a new record. The columns used for this purpose are separated. Items tracking insertions are stored in columns X__INSDATE and X__INSUSER and the value of these fields is only stored in case of an insert, not in case of an update. The elements used for modification are stored in columns X__MODDATE and X__MODUSER. These are predefined in the AbstractAuditEntity.java class and are automatically loaded using the appropriate annotation (e.g. @CreatedOn, @ModifiedOn)

Example code for an Entity where audit elements are required:

The version column is a strictly technical element defined in the AbstractEntity.java class. It is used by Hibernate via @Version annotation, ensuring that during a merge operation the entity can remain intact using optimistic lock concurrency control.

The field spacing in which we want to languageize the values must be specified in the LocalizationConverter , which can be done with annotations starting with @CsvCustomBind:

Then we need to specify the language for the columns and the values of the fields we want to annotate (e.g. in the messages_en.properties file):

Finally, you need to call the CsvUtil#toLocalizedCsv method with the selected language:

The code in the examples will result in the following CSV:

To deploy ETCD configurations, the coffee-module-etcd module is pulled in as a dependency. This will provide the auxiliary classes needed for configuration management, and contains an EtcdConfig implementation to define it, that the coffee.etcd.default.url property included in the configuration will be the ETCD’s reachability. With the help of the following properties, additional optional configurations are possible for establishing the ETCD connection:

On the backend side, there are several ways to manage configurations. These typically support and complement each other.

The microprofile-config annotation can be used to inject specific configuration values. In order for microprofile-config to detect ETCD storage, in our code, we need to activate the coffee-module-etcd in ConfigSource implementation in the code of your code:

Example ConfigSource activation:

The priority of ConfigSources is set to 150.

It is possible to inject String, Integer, Boolean, Long, Float and Double configurations. The ETCD always stores String, the parsing to the desired type is done after reading the value. The mechanism uses ConfigEtcdHandler in the background to read the values. See configuration module

Provides a way to read and write ETCD configuration values in a context. It uses ConfigEtcdService in the background.

Provides the ability to query, write, list, search for configuration values. The lowest class of those listed. All of the above mechanisms work through this implement their functionality. Presumably you will only need to use it if you delete it, list configurations.

When requesting or deleting a non-existent configuration, the service throws a BONotFoundException. Since this mechanism is used by all listed options, this is true for all of them.

The configuration handler does not support separate namespaces, all information stored in etcd is accessible.

Each configuration key starts with a visibility prefix. They are managed according to the following conventions:

Download and unpack the ETCD package for your system: https://github.com/coreos/etcd/releases/

Set the ETCDCTL_API environment variable to 3:

From the command line, you can use etcdctl to read and write the values in the ETCD configuration:

The retrieved keys and the resulting values are logged unless the key matches the regular expression [\w\s]*?secret[\w\s]*? or [\w\s]*?pass[\w\s]*?, in which case the value is masked and logged. The default regex can be overridden by specifying coffee.config.log.sensitive.key.pattern in one of the default microprofile-config sources (sys var, env var, META-INF/microprofile-config.properties), multiple patterns can be specified separated by commas.

The EtcdHealth can check if the etcd server is reachable.

Localization functionality in a backend system is useful from several perspectives, for example error codes, enum translations or even language-agnostic generation of documents. For this purpose, deltaspike Messages and i18n which is still being enhanced with newer CDI features.

It has three components:

The @RedisConnection qualifier has been introduced. Using this, there is no need to define/implement Redis configuration, JedisPool, Jedis, RedisService separately per Redis connection; they are all built and injected via CDI. Configuration in yaml:

Use the RedisManager associated with the above config:

The first case will use the "default" pool settings, in the second case, the "custom" pool settings.

The class RedisManager and its associated RedisManagerProducer are introduced. The producer will produce the RedisManager with the called configKey value, making it available to retrieve Jedis from the JedisPool when we want to perform some action on redis. RedisManager’s job is to federate the use of Jedis functions, which handles common logging, error handling, connection usage. The defined methods expect Jedis functions to be run, this can be done using initConnection() and closeConnection(), or through the runWithConnection methods. This approach allows Redis connections to be used as long as they are needed, saving a lot of resources.

Example of using multiple redis operations. This is typically set/get combined with expire. In such a case, no Jedis instance is requested from the pool unnecessarily and when done, it is closed.

Example of performing an operation.

The RedisHealth can check if the Redis server is reachable.

The JedisConnectionProducer provides metrics about the usage of the Jedis pool.

The metrics can be overridden using the @Alternative or @Specializes annotations.

The coffee-module-redisstream module uses the [coffee-module-redis] module for Redis connection management. The Redis connection setup is the same as described for [coffee-module-redis], it is based on the "key" there, only through its own annotation class, which also allows other stream settings.

Since the implementation uses the jedis driver, so there is a restriction on the format in which the general message frame. Normally this is an XSD which is part of an API, but now, due to the specificity of the driver (redis.clients.jedis.StreamEntry object is the carrier), these are just keys. These keys are called hu.icellmobilsoft.coffee.module.redisstream.config.IRedisStreamConstant.Common interface:

When browsing Redis content, this may look like this:

The value of extSessionId here is already seen to be a "composite" process identifier, where "3OXV5ZUSUAF1KA8G" is the original process ID, and then appended with "3OCISPU2RW0NWR7M" which is the unique identifier of the asynch. When browsing the logs, you can then clearly see where the process is split.

The message shown here is a more complex message content, should belong somewhere in the API (XSD) and JSON format is recommended to use.

Configuration is done via the @RedisStreamConsumer and @RedisStreamProducer qualifiers. Configuration in yaml:

This includes an EE level setting, which is needed if the default is not enough to start extra threads (e.g. maximum thread count). These settings vary by application server, e.g:

The system logs at MDC level as "retryCounter", the number of iterations of the retry (coffee.redisstream.sampleGroup.consumer.retryCount configuration).

This implementation does not deal with retrieved but not ACKed messages. These need to be handled locally on a case by case basis as to what to do with them. The hu.icellmobilsoft.coffee.module.redisstream.service.RedisStreamService class contains query and handling methods for this purpose, which can be used in the stuck business process.

The Redis consumers got stuck during service shutdown and stalled during processing. To support graceful shutdown, the hu.icellmobilsoft.coffee.module.redisstream.bootstrap.ConsumerLifeCycleManager class was created, which waits for the consumers to complete their ongoing operations.

By default, it is enabled, but it can be disabled in the following way:

The Pub/Sub function implements classic publisher-subscriber messaging. Publishers send a message to a given Redis pub/sub channel, which is received by all subscribers who have just subscribed. Unlike Redis streams, messages are not even stored in-memory on the channel, if a subscriber subscribes to the channel afterwards, he will not receive the previous messages, and therefore the subscription will not be by repeated requests (e.g. XREAD), but on a reserved grpc connection.

The coffee-module-redispubsub module uses the [coffee-module-redis] module to handle Redis connection. The Redis connection setup is the same as described in [coffee-module-redis], it is based on the "key" there.

The module integrates the Pub/Sub solution using the microprofile reactive messaging API, thus configuration and message sending/receiving is done according to the specification (therefore, with minimal code modification, the module can be used as a replacement for existing connectors (e.g. Kafka, MQTT, Google Pub/Sub…​)). Integration is done via the PubSubConnector class, which is used to register subscribers, and is used to send messages

Subscriber creation is done with the configurations and annotations defined by microprofile-reactive-messaging.

Publisher creation is also done with the configurations and annotations defined by microprofile-reactive-messaging.

The module wraps all messages in a PubSubMessage object, this contains the sender SID, which is read by the consumer and set in MDC. The class implements org.eclipse.microprofile.reactive.messaging.Message so that the consumer method parameter as described in the documentation Methods consuming data.

It works entirely on the basis of CDI, focusing on the following needs:

Many types of rule evaluation are possible, starting from the following pattern

It is intended to handle rules belonging to the rule category.

Based on https://github.com/eclipse/microprofile-opentracing and the https://github.com/opentracing-contrib/java-interceptors project. We use our own binding instead of the org.eclipse.microprofile.opentracing.Traced annotation, as this way we can completely decouple the traceability of our modules.

The bindings in the extension are used to make the different technologies of the modules traceable.

Contains a metric-independent Noop* implementation that is activated by default when no specific metric implementation is plugged in.

The module contains metrics that can be activated based on the metric implementation:

The starting point is microprofile-rest-client which is a member of the micropfile.io group. It can do many things off our shoulders, it can be used on its own but needs to be extended to meet the needs of projects some useful features.

Most of the above principles are implemented in the microprofile-rest-client the rest is done by the next few classes.

To use it, the sub-dependency must be added to pom.xml:

Since the generation uses an annotation processor, it can be configured at compile time with -A. This can be specified via maven-compiler-plugin for maven:

This version aims to implement Jakarta EE 10, which follows the change from java import javax.* → jakarta.* throughout the project.

Since almost all dependencies have been updated, so listing them one by one is redundant. Mostly cosmetic version changes, or EE10 implementations.

The content of the beans.xml files has been updated:

Include Jandex-maven-plugin on all modules. Consolidated the use of classLoader across several modules, using Thread.currentThread().getContextClassLoader() everywhere except in the coffee-deltaspike module!

For XSD → DTO generation, the project uses a forked jaxb4 maven plugin: phax/maven-jaxb2-plugin#v016. The plugin is a fork of the previously used jaxb2 plugin, a dependency swap is sufficient com.helger.maven:jaxb40-maven-plugin:0.16.0.

The coffee-deltaspike subproject has been created for this purpose, to replace the functionality that was lost by dropping the deltaspike dependency there is nothing to replace it with. This could be a permanent solution, time will tell.

Contains the classes responsible for the language, 1:1 correspondence to the solution used so far - at class name level. The language is a "lite" copy of the original (https://deltaspike.apache.org/documentation/core.html#Messagesandi18n), without @MessageBundle and @MessageTemplate. The MessageContext and Locale resolvers are completely as in the original. The DefaultMessageResolver and the DefaultMessageContext are interleaved on several threads, fixed via DefaultMessageResolve.

Replaces the original deltaspike-data-module functionality, except for a few things:

Changes from the original deltaspike code:

On implementing projects, possible deltaspike message and data dependency should be replaced by the coffee-deltaspike-message and coffee-deltaspike-data dependency respectively. The org.apache.deltaspike.jpa.api.transaction.Transactional annotation is replaced by hu.icellmobilsoft.coffee.jpa.annotation.Transactional, must be replaced everywhere.

Deltaspike core after ejecting org.apache.deltaspike.core.api.projectstage.ProjectStage was removed and replaced by hu.icellmobilsoft.coffee.rest.projectstage.ProjectStage. It searches for the correct keys in all configs.

Replace org.apache.deltaspike.core.api.projectstage.ProjectStage → hu.icellmobilsoft.coffee.rest.projectstage.ProjectStage class.

The deltaspike data dependency has been removed. The former deltaspike data CurrentUser has been replaced by hu.icellmobilsoft.coffee.model.base.annotation.CurrentUser annotation. The AuditProvider, TimestampsProvider classes are replaced by the former deltaspike data Instead of implementing the PrePersistAuditListener and PreUpdateAuditListener interfaces, they are implemented as methods with the java-like PrePersist and PreUpdate annotations have been provided. The deltaspike AuditEntityListener has been removed from AbstractEntity, and the AbstractAuditEntity classes have been replaced by the following annotation: @EntityListeners({ TimestampsProvider.class, AuditProvider.class }).

Change the annotation of deltaspike data org.apache.deltaspike.data.api.audit.CurrentUser to hu.icellmobilsoft.coffee.model.base.annotation.CurrentUser.

The driver jakarta EE 10 and the changes to Jakarta Messaging 3.1 in it have changed a lot: ActiveMQ Artemis embraces Jakarta EE.

You should test the JmsHandler.createTextMessage and JmsUtil.newJmsException functions, where the change was specifically affected, changed the original concept with delay messages.

Unfortunately there is no java-compatible release of the Apache commons-email dependency yet, so the coffee-module-notification module has been removed from the coffee modules. Next issue handles: EMAIL-203 or commons-email Gihub PR pull request.

coffee-module-notification module has been removed.

Module has been optimized, so some classes (e.g. OpenTraceExtension) have become redundant. The @hu.icellmobilsoft.coffee.cdi.trace.annotation.Traced annotation replaces all functions, which can still be used to trace the individual modules of coffee.

The former @Traceable annotation should be replaced by @hu.icellmobilsoft.coffee.cdi.trace.annotation.Traced annotation.

Parameterized junit tests with @ParameterizedTest annotation (e.g. hu.icellmobilsoft.coffee.rest.projectstage.ProjectStageProducerTest) are annotated with @ExplicitParamInjection. Without this, the CDI managed parameter injection will not work.

During csvUtil csv generation, the line separator was replaced: ICSVWriter.DEFAULT_LINE_END (\n) → System.lineSeparator(). Thus, an operating system dependent line separator is used.

The changes do not result in any changeover work, it is backwards compatible.

In JbossMDCAdpater, there was an error in logging the parameter, which has been fixed.

Changes do not result in migration work, backwards compatible.

The changes do not result in any migration work, it is backwards compatible.

The following feature supports have been added to the system:

Changes are backwards compatible doesnt need any migration.

Changes are backwards compatible doesnt need any migration.

Changes are backwards compatible doesnt need any migration.

Renames coffee-grpc-metrics-impl → coffee-grpc-metrics-mpmetrics

💥 BREAKING CHANGE 💥

coffee-bom → coffee-bom-project -re változott

A new module called Coffee Quarkus extension has been created, which adds other elements needed for Quarkus to some of the coffee modules. First element is coffee-module-mp-restclient-extension Second element is coffee-deltaspike-data-extension

A new module that defines a basic Coffee API such as enums, DTOs, exceptions, which can only have Java SE dependencies.

Contents:

A new module which contains functional interfaces used in Coffee, which can only have Java SE and such Coffee modules that can also only have Java SE dependencies.

Contents: (based on hu.icellmobilsoft.coffee.tool.common.FunctionalInterfaces, but declares the new hu.icellmobilsoft.coffee.se.api.exception.BaseException)

💥 BREAKING CHANGE 💥

Example of how to use validation: The annotated endpoint:

or for example:

or for example:

We need one for the XML

Another one for JSON

The JSON XSD validation is done by converting the inputStream to a DTO using the JSON parser (which is returned by the provider for further business logic processing), and then run an XML marshaller with XSD enabled on it to validate it. If errors occur during this process, they are handled at provider level. Then everything is done with the errors as with the XML validation.

We need to implement the IXsdResourceResolver interface (with @Alternative annotation). Then we need to register the alternative class in beans.xml e.g.:

You can also use your own implementations of XsdHelper (IXsdHelper), XmlRequestVersionReader (IXmlRequestVersionReader), XsdValidationErrorCollector (IXsdValidationErrorCollector).

Our ExceptionMapper implementation may also be complementary:

Here’s what else to watch out for: all XSD errors are returned by Coffee. These should be extracted separately, e.g. like this:

We generally use XSD to get rid of the basic valadication of DTO objects, such as:

In addition, it greatly assists object-oriented DTO generation, recycling - a well-written XSD structure can be very easily used for coding.

It is also important that we use JAVA language but the REST interface objects we write are defined in XSD and can be passed to a connected external client. You can generate your own DTOs from XSD in any language without having to rewrite them manually.

We try to keep the XSD as complex and documented as possible because we use an openapi-jaxb plugin that complements the DTOs with openapi annotations, where all data, restrictions and description. Thanks to this Swagger can also serve as a complete REST interface documentation for the developer, developer, tester, frontend, server and client, without the need to invest extra effort in post-documentation of the product.

Lest it seem that XSD is perfect, I will mention one of its biggest drawbacks - if the input is not XML (e.g. JSON), we can only solve the validation by extra transformation to XML. But the above listed advantages can save so much time that the price is we are willing to pay - so far all problems could be solved…​

Suppose we have a structure consisting of several XSDs. In this case we want a user DTO with has 2 elements, userName and password, these must satisfy the following constraints:

In this case 2 files are required:

Advantages:

Disadvantages:

Imagine a case where Coffee generates some very basic DTO objects. This is important so that a common "generic" code base can be created in Coffee, For example, a generic error handling, logging, apache client response processing, etc (where DTOs are involved). If there is no generic class to cast types to, such boilercode is not possible in Coffee, since only the "Object" itself could be referenced. Nor is it a solution for Coffee to force some fixed types, because then projects would not be able to customize and extend it (e.g. replacing XMLGregorianCalendar with java.time.OffsetDateTime). Traditional XSD import is not appropriate in this situation, because it looks for the import xsd path file in a fixed location, which is not part of our project but part of Coffee, and refers to a relative path within Coffee.

The catalog file provides a solution. The catalog is a separate file, you can make your own version of it. In it, we only use the basic XSDs that meet our needs. Whatever does not suit us, we have to copy the original XSD with everything and extend it with the Coffee DTO type. If the namespace and the complexType names are not changed, it will generate the same DTO class as in Coffee. This will be found by JAVA via the classpath and all Coffee logic can continue to work. If the change is very drastic you can use the CDI to replace the Coffee logic completely.