Skip to content

Commit

Permalink
Main page documentation update
Browse files Browse the repository at this point in the history 
Change and reformat short descriptions for modules and link each module header to the corresponding module README.md
so the documentation is more concise, understandable and easier to navigate
  • Loading branch information
@nkescec
nkescec committed Jul 14, 2022
1 parent e83a640 commit 39eecff
Showing 1 changed file with 59 additions and 52 deletions.
111 changes: 59 additions & 52 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,20 +6,22 @@

# nrich

Nrich is a Java library developed at CROZ whose purpose is to make development of applications on JVM a little easier. It contains modules that were found useful on projects and as such were extracted
to a common library. It is based on Spring Framework it also provides Spring Boot starters for most of the modules to make configuration easier.
Nrich is a Java library developed at CROZ whose purpose is to make development of applications on the JVM a little easier.
It contains modules that were found useful on projects and as such were combined
to a common library.
It is based on Spring Framework, and it also provides Spring Boot starters for most of the modules to make the configuration easier.

Most modules are composed of multiple submodules:

- api - has the `api` suffix and contains classes that represent API of the module (service interfaces, parameters, return types...)
- implementation - contains actual api implementation
- spring boot starter - has the `spring-boot-starter` suffix and contains Spring Boot auto configuration of the specified module
- spring boot starter - has the `spring-boot-starter` suffix and contains Spring Boot autoconfiguration of the specified module

In Spring Boot environment only spring boot starter modules should be added as dependencies.

## Compatibility

The following table contains nrich versions with corresponding minimum Java and Spring version.
The following table contains nrich versions with a corresponding minimum Java and Spring version.

| Nrich version | Java version | Spring Boot Version |
|---------------|--------------|---------------------|
Expand All @@ -28,85 +30,90 @@ The following table contains nrich versions with corresponding minimum Java and
| 1.3.x | 1.8 | 2.6.6 |
| 1.4.x | 1.8 | 2.6.6 |


## Modules

nrich is composed of following modules:
Nrich is composed of following modules:

### nrich-bom
### [nrich-bom](nrich-bom/README.md)

Provides managed dependencies for all nrich modules as well as for libraries used inside those modules that are not covered by Spring Boot dependencies.

### nrich-core-api
### [nrich-core-api](nrich-core-api/README.md)

Contains common classes that are used throughout library
It contains common classes that are used throughout the library.

### nrich-encrypt
### [nrich-encrypt](nrich-encrypt/README.md)

Provides easier encryption of data, it can encrypt method results and decrypt method arguments. Method for encryption/decryption can be marked using annotations or as properties (i.e.
in `application.yml` files).
Provides easier encryption and decryption of data.
It can encrypt method results and decrypt method arguments.
Methods whose results should be encrypted and/or arguments decrypted can be marked using annotations or as properties specified in the property file (such as `application.yml` file).

### nrich-excel
### [nrich-excel](nrich-excel/README.md)

Provides easier generation of excel reports from provided data and templates. Default implementation uses `Apache POI` library but tries to simplify usage.

### nrich-form-configuration
### [nrich-form-configuration](nrich-form-configuration/README.md)

Allows for resolving of server side constraints (`jakarta-validation-api`) on client side. Its purpose is to have a central place for constraint definitions. On the server side client provides a
mapping between client form and class containing constraints. After that when client asks request for form, all constraints with error messages defined for a class are returned to the client that is
then responsible for processing and applying them to the form.
Provides mapping of server-side class constraints to client-side form constraints.
Its purpose is to provide a central place for constraint definitions.
The Client registers a form to the class that defines constraints, which enables him to request information for the registered form.
Supplied information contains constraints with their error messages, which are specified in the class.
The client is then responsible for processing and applying them to the form.

### nrich-jackson
### [nrich-jackson](nrich-jackson/README.md)

Sets commonly used defaults for standard Jackson properties (i.e `FAIL_ON_EMPTY_BEANS: false`) to avoid repeating it in every project. It also provides Jackson modules that serialize empty strings to
null and that serialize class name for `@Entity` annotated classes or classes from defined package list.
Sets commonly used defaults for standard Jackson properties (as an example `FAIL_ON_EMPTY_BEANS: false`) to avoid repetition in projects.
It also provides Jackson modules that serialize empty strings to
null and serialize class names to fully-qualified class names for classes that are annotated with `@Entity` annotation or are from a package defined in a given list.

### nrich-logging
### [nrich-logging](nrich-logging/README.md)

Provides a logging service logging errors in a standard format and can also resolve verbosity and logging levels for each exception. It is used in `webmvc` module for logging exceptions but can easily
be replaced with custom implementation.
Provides a logging service for consistent error logging in a standard format.
Provided logging service can also resolve verbosity and logging levels for each exception.
This module is used in [webmvc](nrich-webmvc/README.md) module for exception logging but can easily be replaced with some other custom implementation.

### nrich-notification
### [nrich-notification](nrich-notification/README.md)

Allows for resolving of client notifications from server side. Notifications can be resolved for controller actions (i.e. `Entity has successfully been saved`), for exceptions (i.e. `Error occurred`)
and for validation errors (i.e. `Validation errors found in request`). Validation notification also return a list of validation errors with properties that failed validation. Notification messages are
resolved by message keys or exception class names from Spring's `MessageSource`. Users can also return responses with notification. `webmvc` module uses this module to send notification responses to
client on exceptions with registered
`@RestControllerAdvice`.
Intended for addition of specified notifications into the server-side response, which can later be shown on the client-side.
It supports three different notification severity levels and can also include a list of validation errors.
Definition and resolution of messages is realized with Spring's `MessageSource` feature.

### nrich-registry
### [nrich-registry](nrich-registry/README.md)

Purpose of this module is transforming JPA entities in a format that client can interpret and create dynamic forms and grids for editing of entities without additional implementation on server side.
On the server side providing methods for searching, creating, updating and deleting entities through REST API. Configuration consists only from defining included entities and (optionally) providing
property label/header messages in `messsage.properties`.
Simplifies the administration of specified JPA entities and provides a formatted representation of them that client-side can interpret and create dynamic forms and grids.
Generated forms and grids can be used for entity editing without additional implementation on server-side.
The Module also provides methods for searching, creating, updating and deleting entities through a REST API.

### nrich-search
### [nrich-search](nrich-search/README.md)

Allows for easier querying of entities. For its input it uses a class holding values that will be used in a query and a parameter (`SearchConfiguration`) that defines how those values will be added to
query (i.e. what operators should be used, mapping of those properties on entities etc.) it also defines what result type will be returned, what associations should also be fetched etc. It also allows
for using string as an input (instead of class holding the value), and a list of fields that should be searched from the entity (for quick search functionality). It was created as a means of
simplifying creation of queries for various search forms on client side. Spring Data JPA library is used in implementation and module functionality is added through two repositories interfaces that
users can add to their repository interface.
Simplifies the querying of entities.
It is based on top of the Spring Data JPA library and it was created as a means of
simplifying the creation of queries for various search forms on the client-side.
Queries can be automatically formed from different types of inputs, such as the property holding class, a string or from a list of search fields, and additional query properties can be defined using
the special configuration class.

### nrich-security-csrf
### [nrich-security-csrf](nrich-security-csrf/README.md)

Intended as a replacement for Spring Security csrf functionality. It works with Spring Web MVC and WebFlux libraries. Clients should define initial token url and after that send generated token with
each request in a header or as a parameter.
Intended as a replacement for Spring Security csrf functionality.
It works with Spring Web MVC and WebFlux libraries.
Clients should define the initial token url and after that send the generated token with each request in a header or as a parameter.

### nrich-spring-boot
### [nrich-spring-boot](nrich-spring-boot/README.md)

Adds additional functionality to Spring Boot. i.e. `ConditionalOnPropertyNotEmpty` annotation that checks if a property is not empty.
Adds additional functionality to Spring Boot that is used within nrich.

### nrich-spring
### [nrich-spring](nrich-spring/README.md)

Contains utility classes for Spring access. i.e. `ApplicationContextHolder` for resolving of `ApplicationContext`
from static context.
Contains utility classes for Spring access, such as `ApplicationContextHolder` for resolving of `ApplicationContext` from static context.

### nrich-validation
### [nrich-validation](nrich-validation/README.md)

Contains additional `jakarta-validation-api` constraints and validators (i.e `ValidFile`, `MaxSizeInBytess` etc).
Contains additional `jakarta-validation-api` constraints and validators that proved to be commonly used, such as `NotNullWhen` validator.

### nrich-webmvc
### [nrich-webmvc](nrich-webmvc/README.md)

Provides additional functionality built on top of Spring Web MVC framework. Main purpose is handling exceptions through `NotificationErrorHandlingRestControllerAdvice` that handles exceptions by
logging them and sending notifications to client with exception descriptions. It also adds additional classes that handle binding (i.e. transforming empty string to null), locale resolving etc.
Provides additional functionality built on top of the Spring Web MVC framework.
Main purpose is to handle exceptions through `NotificationErrorHandlingRestControllerAdvice` that handles exceptions by
logging them, and then creating and sending notifications to the client-side with exception's description.
The Module uses the [nrich-notification](nrich-notification/README.md) module for notification handling and [nrich-logging](nrich-logging/README.md) for log handling.
It also adds additional classes that handle binding (in other words transforming empty string to null), locale resolving and the like.

0 comments on commit 39eecff

Please sign in to comment.