search

kumuluz / kumuluzee

Lightweight open-source framework for developing microservices using standard Java EE technologies and migrating Java EE to cloud-native architecture.
https://ee.kumuluz.com
MIT License
291 stars 71 forks source link
cloud-native cloud-native-architectures cloud-native-microservices jakartaee java javaee kumuluzee microprofile microservice-framework microservices uberjar

readme

KumuluzEE

KumuluzEE CI

Lightweight open-source framework for developing microservices using standard Java/JakartaEE technologies, extending them with Node.js, Go and other languages, and migrating to cloud-native architecture.

KumuluzEE is a lightweight framework for developing microservices using standard Java/JakartaEE technologies, extending them with Node.js, Go and other languages, and migrating existing applications to microservices and cloud-native architecture. KumuluzEE packages microservices as standalone JARs. KumuluzEE microservices are lightweight and optimized for size and start-up time. They fit perfectly with Docker containers. KumuluzEE microservices are fully compatible with Kubernetes and enable Kubernetes-native development. KumuluzEE will also provide support for Serverless Functions on Azure, AWS and Google.

KumuluzEE also provides extensions for developing common patterns in cloud-native architectures, including configuration, logging, discovery, fault tolerance with circuit-breakers, metrics, security, event streaming and more.

KumuluzEE has been designed to use the standard Java/JakartaEE technologies and APIs with optional extensions for easier development of cloud-native microservices. Therefore, it is particularly suitable for existing enterprise Java developers, who would like to leverage their skills, but progressively move from monolithic to microservice design patterns.

KumuluzEE provides full support for Java latest versions (check each release for specific information). In addition to Java, KumuluzEE supports several programming languages, including Node.js and Go. Support for additional languages will be added soon. For these languages, KumuluzEE also provides support for service configuration and discovery.

KumuluzEE is Eclipse MicroProfile compliant and provides support for MicroProfile 1.0, 1.1, 1.2, 1.3, 1.4, 2.0, 2.1, 3.0, 3.1, 3.2 and 3.3. Support for 4.x and 5.x is coming soon. KumuluzEE provides support for all MicroProfile specifications, including MicroProfile Config, MicroProfile Health, MicroProfile Fault Tolerance, MicroProfile Metrics, MicroProfile JWT Authentication, MicroProfile Rest Client, MicroProfile OpenAPI and MicroProfile Open Tracing APIs.

Getting started

If you already know how to use Java/JakartaEE, then you already know how to use KumuluzEE. It is simple and straightforward.

See the getting started wiki section to create your first light-weight standalone Java microservice in 5 minutes.

Read tutorials at our home page.

Refer to samples for more examples.

Features

Primary features:

KumuluzEE provides support for various Java/JakartaEE APIs and components. The goal is to support as many Java components as possible (contributions welcome).

Java/JavaEE/JakartaEE components

Currently the following components are supported with more being added over time:

Additional features

KumuluzEE provides additional features, which are described on the project Wiki, particularly:

KumuluzEE also provides support for Uber JARs. With the KumuluzEE Maven plugin, you can pack and run each microservice as a single, self-contained Uber-JAR. Details are described later in this document.

KumuluzEE projects

In addition to the standard Java EE components, KumuluzEE also comes with several projects that complement and extend its functionality. The projects follow the same modular concept as the Java components in which you can chose if you want to use it as well as the underlying implementation of the project. Most projects are geared towards creating cloud-native microservices including configuration, logging, discovery, fault tolerance including circuit-breakers, metrics, security, event streaming and more. Projects also extend KumuluzEE with technologies, such as Ethereum for blockchain microservices, gRPC, GraphQL, and others. The following projects are available with more planned soon:

MicroProfile

KumuluzEE is Eclipse MicroProfile compliant and provides support for:

It implements the following MicroProfile APIs:

Usage

KumuluzEE ships with a BOM (bill of materials) which you can use to easily add the various components you need without worrying about the versions and their compatibility as it is required that all components are the same version.

Using maven add the BOM module of the library as a dependency to your project. The ${kumuluzee.version} variables represents the most current minor version. You can see the available version on the Release Page.

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.kumuluz.ee</groupId>
            <artifactId>kumuluzee-bom</artifactId>
            <version>${kumuluzee.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

Now you can choose either any single combinations of Java components or use one of the common pre-built profiles that ship as part of KumuluzEE. You can chose any of the following profiles:

MicroProfile 1.0

<!-- MicroProfile 1.0 -->
<dependency>
    <groupId>com.kumuluz.ee</groupId>
    <artifactId>kumuluzee-microProfile-1.0</artifactId>
</dependency>

MicroProfile 1.1

<!-- MicroProfile 1.1 -->
<dependency>
    <groupId>com.kumuluz.ee</groupId>
    <artifactId>kumuluzee-microProfile-1.1</artifactId>
</dependency>

MicroProfile 1.2

<!-- MicroProfile 1.2 -->
<dependency>
    <groupId>com.kumuluz.ee</groupId>
    <artifactId>kumuluzee-microProfile-1.2</artifactId>
</dependency>

MicroProfile 1.3

<!-- MicroProfile 1.3 -->
<dependency>
    <groupId>com.kumuluz.ee</groupId>
    <artifactId>kumuluzee-microProfile-1.3</artifactId>
</dependency>

MicroProfile 1.4

<!-- MicroProfile 1.4 -->
<dependency>
    <groupId>com.kumuluz.ee</groupId>
    <artifactId>kumuluzee-microProfile-1.4</artifactId>
</dependency>

MicroProfile 2.0

<!-- MicroProfile 2.0 -->
<dependency>
    <groupId>com.kumuluz.ee</groupId>
    <artifactId>kumuluzee-microProfile-2.0</artifactId>
</dependency>

MicroProfile 2.1

<!-- MicroProfile 2.1 -->
<dependency>
    <groupId>com.kumuluz.ee</groupId>
    <artifactId>kumuluzee-microProfile-2.1</artifactId>
</dependency>

MicroProfile 3.0

<!-- MicroProfile 3.0 -->
<dependency>
    <groupId>com.kumuluz.ee</groupId>
    <artifactId>kumuluzee-microProfile-3.0</artifactId>
</dependency>

MicroProfile 3.1

<!-- MicroProfile 3.1 -->
<dependency>
    <groupId>com.kumuluz.ee</groupId>
    <artifactId>kumuluzee-microProfile-3.1</artifactId>
</dependency>

MicroProfile 3.2

<!-- MicroProfile 3.2 -->
<dependency>
    <groupId>com.kumuluz.ee</groupId>
    <artifactId>kumuluzee-microProfile-3.2</artifactId>
</dependency>

MicroProfile 3.3

<!-- MicroProfile 3.3 -->
<dependency>
    <groupId>com.kumuluz.ee</groupId>
    <artifactId>kumuluzee-microProfile-3.3</artifactId>
</dependency>

To choose your Java components with fine grain control include them as your dependencies. You can chose any of the following artifacts:

<!-- Servlet (Jetty) -->
<dependency>
    <groupId>com.kumuluz.ee</groupId>
    <artifactId>kumuluzee-servlet-jetty</artifactId>
</dependency>

<!-- WebSocket (Jetty) -->
<dependency>
    <groupId>com.kumuluz.ee</groupId>
    <artifactId>kumuluzee-websocket-jetty</artifactId>
</dependency>

<!-- JSP (Jetty Apache Jasper) -->
<dependency>
    <groupId>com.kumuluz.ee</groupId>
    <artifactId>kumuluzee-jsp-jetty</artifactId>
</dependency>

<!-- EL (UEL) -->
<dependency>
    <groupId>com.kumuluz.ee</groupId>
    <artifactId>kumuluzee-el-uel</artifactId>
</dependency>

<!-- CDI (Weld) -->
<dependency>
    <groupId>com.kumuluz.ee</groupId>
    <artifactId>kumuluzee-cdi-weld</artifactId>
</dependency>

<!-- JPA (EclipseLink) -->
<dependency>
    <groupId>com.kumuluz.ee</groupId>
    <artifactId>kumuluzee-jpa-eclipselink</artifactId>
</dependency>

<!-- or -->

<!-- JPA (Hibernate) -->
<dependency>
    <groupId>com.kumuluz.ee</groupId>
    <artifactId>kumuluzee-jpa-hibernate</artifactId>
</dependency>

<!-- JAX-RS (Jersey) -->
<dependency>
    <groupId>com.kumuluz.ee</groupId>
    <artifactId>kumuluzee-jax-rs-jersey</artifactId>
</dependency>

<!-- JAX-WS (RI Metro) -->
<dependency>
    <groupId>com.kumuluz.ee</groupId>
    <artifactId>kumuluzee-jax-ws-metro</artifactId>
</dependency>

<!-- or -->

<!-- JAX-WS (Apache CXF) -->
<dependency>
    <groupId>com.kumuluz.ee</groupId>
    <artifactId>kumuluzee-jax-ws-cxf</artifactId>
</dependency>

<!-- JSF (Mojarra) -->
<dependency>
    <groupId>com.kumuluz.ee</groupId>
    <artifactId>kumuluzee-jsf-mojarra</artifactId>
</dependency>

<!-- Bean Validation (Hibernate validator) -->
<dependency>
    <groupId>com.kumuluz.ee</groupId>
    <artifactId>kumuluzee-bean-validation-hibernate-validator</artifactId>
</dependency>

<!-- JSON-P -->
<dependency>
    <groupId>com.kumuluz.ee</groupId>
    <artifactId>kumuluzee-json-p-jsonp</artifactId>
</dependency>

<!-- JSON-B -->
<dependency>
    <groupId>com.kumuluz.ee</groupId>
    <artifactId>kumuluzee-json-b-yasson</artifactId>
</dependency>

<!-- JTA -->
<dependency>
    <groupId>com.kumuluz.ee</groupId>
    <artifactId>kumuluzee-jta-narayana</artifactId>
</dependency>

<!-- JavaMail -->
<dependency>
    <groupId>com.kumuluz.ee</groupId>
    <artifactId>kumuluzee-javamail-ri</artifactId>
</dependency>

To choose your KumuluzEE project, you simply include it as your dependency. You can find the available implementations and options at their respected project pages.

Pack and run microservice as Uber JAR

KumuluzEE (version 2.4 and higher) provides support for packing and running microservices as Uber JARs. It also includes a Maven plugin that correctly packages the microservice.

To package a Kumuluz EE microservice into an Uber JAR, you need to add the following plugin declaration into your REST module pom.xml:

<plugin>
    <groupId>com.kumuluz.ee</groupId>
    <artifactId>kumuluzee-maven-plugin</artifactId>
    <version>${kumuluzee.version}</version>
    <executions>
        <execution>
            <id>package</id>
            <goals>
                <goal>repackage</goal>
            </goals>
            <configuration>
                <finalName/>
                <outputDirectory/>
                <mainClass/>
                <webappDir/>
            </configuration>
        </execution>
    </executions>
</plugin>

Parameters

Run

Start the application using the following command:

java -jar ${project.build.finalName}.jar

Example:

java -jar my-app-1.0.0-SNAPSHOT.jar

Getting started

You can find the getting started guide on the projects wiki. You can find samples for Java EE and KumuluzEE

Building

Ensure you have JDK 8 (or newer), Maven 3.2.1 (or newer) and Git installed

java -version
mvn -version
git --version

First clone the KumuluzEE repository:

git clone https://github.com/kumuluz/KumuluzEE.git
cd KumuluzEE

To build KumuluzEE run:

mvn clean package

This will build all modules and run the testsuite.

Once completed you will find the build archives in the modules respected target folder.

Changelog

Recent changes can be viewed on Github on the Releases Page

Contribute

See the contributing docs

When submitting an issue, please follow the guidelines.

When submitting a bugfix, write a test that exposes the bug and fails before applying your fix. Submit the test alongside the fix.

When submitting a new feature, add tests that cover the feature.

License

MIT