kumuluz / kumuluzee-samples

KumuluzEE samples demonstrate how to get started using KumuluzEE microservice framework. They provide small, specific, working samples that can be used as a reference for your own projects.

KumuluzEE Samples

These samples demonstrate how to get started using KumuluzEE microservice framework. They provide small, specific, working samples that can be used as a reference for your own projects.

These samples and quickstarts contain several working projects that demonstrate how to use KumuluzEE microservices. They also serve as test projects for the framework itself.

We recommend that you go through some of these samples to get a better understanding of the framework and use them as a reference for your own projects.

Keep in mind that while projects containing multiple microservices are located in the same repository in order to simplify things, is is often recommended that you separate microservices by repository as well.

Samples will be constantly added over time.

About

The samples demonstrate many different use cases for using KumuluzEE to create self-sustaining microservices. The latest version of the samples will always use the latest version of the KumuluzEE framework. Therefore, it is recommended to use the latest version of the KumuluzEE framework for these samples. This way, you will also get all the latest features of the KumuluzEE. Refer to the usage section on how to build and run the samples.

Some samples are tagged as well. The tags (eg. v3.2.0) will correspond to the KumuluzEE release version in order to easily access the desired version of the framework that is used in the examples. Tha master branch will always use the latest snapshot version of the framework and the latest samples.

If you wish to use a snapshot version of KumuluzEE when running the samples, you must make sure you add the Sonatype snapshots repository to your pom.xml. The master branch already contains the repository as it's targeted against the snapshot version of the framework.

<repositories>
    <repository>
        <id>sonatype-snapshots</id>
        <name>Sonatype Snapshots</name>
        <url>https://oss.sonatype.org/content/repositories/snapshots</url>
        <releases><enabled>false</enabled></releases>
        <snapshots><enabled>true</enabled></snapshots>
    </repository>
</repositories>

The following samples are available (list might not be up-to-date; please refer to the actual list above):

Tutorial:

• Simple microservice tutorial (microservices-simple)
• Cloud-native Java EE Microservices with KumuluzEE: REST service using config, discovery, security, metrics, logging and fault tolerance (tutorial-microservice-config-discovery-faulttolerance-logs-metrics-security)

Java EE samples:

• Bean Validation
• JAX-RS
• JAX-WS
• JPA and CDI
• JSF
• JSP and Servlet
• Servlet
• Websocket
• REST service over HTTPS
• Logging with JUL and KumuluzEE

KumuluzEE extensions - samples:

• KumuluzEE Config
• KumuluzEE Config with etcd
• KumuluzEE Config with Consul
• KumuluzEE MicroProfile Config
• KumuluzEE Discovery with etcd
• KumuluzEE Discovery with Consul
• KumuluzEE Logs with Log4j2
• KumuluzEE Logs with JUL
• KumuluzEE REST
• KumuluzEE Security with Keycloak for REST services
• KumuluzEE Security with Keycloak for CDI
• KumuluzEE Fault Tolerance
• KumuluzEE Event Streaming with Kafka
• KumuluzEE Cors
• KumuluzEE Metrics
• KumuluzEE Health
• KumuluzEE AMQP
• KumuluzEE Ethereum
• KumuluzEE GraphQL
• KumuluzEE gRPC
• KumuluzEE OpenAPI
• KumuluzEE OpenAPI MicroProfile
• KumuluzEE Swagger
• KumuluzEE OpenTracing
• KumuluzEE Reactive
• KumuluzEE Rest Client

Requirements

In order to run these examples as they are intended, you will need the following:

1. Java 8 (or newer), you can use any implementation:

   • If you have installed Java, you can check the version by typing the following in a command line:

     java -version
     

2. Maven 3.2.1 (or newer):

   • If you have installed Maven, you can check the version by typing the following in a command line:

     mvn -version
     

3. Git:

   • If you have installed Git, you can check the version by typing the following in a command line:

     git --version
     

Usage

1. Clone the Git repository containing the examples:

   git clone [email protected]:kumuluz/kumuluzee-samples.git
   

2. Checkout the desired tagged version of the examples and the KumuluzEE framework (alternatively skip this step if you want the latest and greatest)

   cd kumuluzee-samples
   git checkout v3.2.0
   

To run a specific sample, please refer to the specific README file of the sample. Most of the time you either build and run it directly with a maven command or build Docker containers and run them.

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.

Issues related to KumuluzEE itself should be submitted at https://github.com/kumuluz/kumuluzee/issues.

License

MIT

kumuluzee-samples's Issues

add testing examples

the examples here look all great. However, one thing I have missed on first sight from all the examples and the website: testing/junit.

is there already something in place? With the Deltaspike CDI Test Runner and the Weld integration, that should be a fairly simple thing to achieve?

[security-cdi-keycloak] Always unauthorized when running in Docker containers

Hi,

I'm following this guide to test KumuluzEE and Keycloak. When I run the CustomerApplication on my own machine everything is fine. But when I try to move it to a Docker container I keep getting 401 Unauthorized when trying to access /v1/customers or any other endpoint.

Here's my docker-compose file

version: '3'

services:
  keycloak:
    image: jboss/keycloak
    environment:
      KEYCLOAK_USER: admin
      KEYCLOAK_PASSWORD: admin
    ports:
      - 8082:8080

  app:
    image: maven:3.6.0-alpine
    command: java -jar /usr/src/app/target/kumuluzee-security-cdi-keycloak-3.5.0-SNAPSHOT.jar
    volumes:
      - ./target:/usr/src/app/target
    ports:
      - 8080:8080

And here's my kumuluz config.

kumuluzee:
  name: customer-service
  env:
    name: dev
  version: 1.0.0
  server:
    base-url: http://localhost:8080
    http:
      port: 8080
  security:
    keycloak:
      json: '{
               "realm": "customers-realm",
               "bearer-only": true,
               "auth-server-url": "http://keycloak:8080/auth",
               "ssl-required": "external",
               "resource": "customers-api",
               "confidential-port": 0
             }'

As you see, I tried using keycloak as the hostname, sadly this did not work.

When I ran this configuration I got the following exception: org.keycloak.adapters.rotation.AdapterTokenVerifier -- Didn't find publicKey for kid: <kid>. So, I added "realm-public-key": "<pubk>" to the config.

The error message is gone, but sadly I still get 401 Unauthorized. I'm fairly new to Keycloak, so maybe I'm making a simple mistake.. either way, I hope you can provide some help :)

Thanks!

Gradle Support/Example

When using kumuluzee from Maven, there is a plugin that packages the application/jar in the right way.
There should also be a plugin for Gradle or at least a gradle sample project that shows how to package the jar in the correct way for kumuluzee.

Based on my first tries, it seems not to be as simple as a shaded jar where all kumuluzee jars are just shaded in the application-jar. When comparing the output of the maven build, it seems, that some select classes are in the main application-jar and the other dependencies are contains as Jars.
It would be good to have a gradle build example that sets this up in exactly the right way.

exceptionSearchingForPersistenceResources - java.lang.NullPointerException

I'm having issue when I try to start JPA example in kumuluzee-samples repository

Not working with Java 9 or later (kumuluzee-swagger and kumuluzee-openapi)

Get this message when running kumuluzee-samples/kumuluzee-swagger:
2018-04-25 09:09:41,331 WARN Multiple JAX-RS applications not supported. Swagger definitions will not be served. {}
And no swagger ui available
Both works without problems with Java 8

java.lang.NoClassDefFoundError: jersey/repackaged/com/google/common/base/Predicate

Hello guys,

I'm creating a Rest Service using Kumuluzee, the service itself it runs fine. Then I included the swagger using the sample project kumuluzee-swagger as a basis.
When I startup the application I get this error:

java.lang.NoClassDefFoundError: jersey/repackaged/com/google/common/base/Predicate at org.glassfish.jersey.servlet.ServletContainer.init(ServletContainer.java:177) at org.glassfish.jersey.servlet.ServletContainer.init(ServletContainer.java:369) at javax.servlet.GenericServlet.init(GenericServlet.java:244) at org.eclipse.jetty.servlet.ServletHolder.initServlet(ServletHolder.java:670) at org.eclipse.jetty.servlet.ServletHolder.initialize(ServletHolder.java:427) at org.eclipse.jetty.servlet.ServletHandler.initialize(ServletHandler.java:760) at org.eclipse.jetty.servlet.ServletContextHandler.startContext(ServletContextHandler.java:374) at org.eclipse.jetty.webapp.WebAppContext.startWebapp(WebAppContext.java:1497) at org.eclipse.jetty.webapp.WebAppContext.startContext(WebAppContext.java:1459) at org.eclipse.jetty.server.handler.ContextHandler.doStart(ContextHandler.java:848) at org.eclipse.jetty.servlet.ServletContextHandler.doStart(ServletContextHandler.java:287) at org.eclipse.jetty.webapp.WebAppContext.doStart(WebAppContext.java:545) at org.eclipse.jetty.util.component.AbstractLifeCycle.start(AbstractLifeCycle.java:68) at org.eclipse.jetty.util.component.ContainerLifeCycle.start(ContainerLifeCycle.java:138) at org.eclipse.jetty.server.Server.start(Server.java:419) at org.eclipse.jetty.util.component.ContainerLifeCycle.doStart(ContainerLifeCycle.java:108) at org.eclipse.jetty.server.handler.AbstractHandler.doStart(AbstractHandler.java:113) at org.eclipse.jetty.server.Server.doStart(Server.java:386) at org.eclipse.jetty.util.component.AbstractLifeCycle.start(AbstractLifeCycle.java:68) at com.kumuluz.ee.jetty.JettyServletServer.startServer(JettyServletServer.java:81) at com.kumuluz.ee.EeApplication.initialize(EeApplication.java:368) at com.kumuluz.ee.EeApplication.<init>(EeApplication.java:73) at com.kumuluz.ee.EeApplication.main(EeApplication.java:85) at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method) at sun.reflect.NativeMethodAccessorImpl.invoke(Unknown Source) at sun.reflect.DelegatingMethodAccessorImpl.invoke(Unknown Source) at java.lang.reflect.Method.invoke(Unknown Source) at com.kumuluz.ee.loader.EeClassLoader.invokeMain(EeClassLoader.java:434) at com.kumuluz.ee.loader.EeBootLoader.launch(EeBootLoader.java:54) at com.kumuluz.ee.loader.EeBootLoader.main(EeBootLoader.java:41) Caused by: java.lang.ClassNotFoundException: Failure to load: jersey.repackaged.com.google.common.base.Predicate at com.kumuluz.ee.loader.EeClassLoader.loadClass(EeClassLoader.java:488) at java.lang.ClassLoader.loadClass(Unknown Source) ... 30 more

The class jersey.repackaged.com.google.common.base.Predicate is not present in the workspace, but the original one it is com.google.common.base.Predicate. Is there any configuration missing?

repository contains no tag

From the usage section:

Clone the Git repository containing the examples:
git clone [email protected]:kumuluz/kumuluzee-samples.git
Checkout the desired tagged version of the examples and the KumuluzEE framework (alternatively skip this step if you want the latest and greatest)

cd kumuluzee-samples
git checkout v3.2.0

Unfortunately this repository doesn't have any tag.

kumuluzee-security-cdi-keycloak issue

kumuluzee:
  security:
      keycloak:
        json: '{"realm": "customers-realm",
                "bearer-only": true,
                "auth-server-url": "http://localhost:8080/auth",
                "ssl-required": "external",
                "resource": "customers-api"}'

auth server url should be as follows(port should be 8082):

"auth-server-url":"http://localhost:8082/auth"

Unsatisfied dependencies for type KeycloakSecurityConfigurationUtilImpl with qualifiers @Default

hello,

i have a wildfly server i just added dependancies as your exemple CDI integration bu i have this error

Unsatisfied dependencies for type KeycloakSecurityConfigurationUtilImpl with qualifiers @default

any idea ?

Kumuluzee Fluentd sample is not working

While try out the Kumuluzee Fluentd faced the first issue as the version of "kumuluzee-logs-fluentd" provided was not valid, so then used the latest version 1.4.2 in the sample project. While trying to run the sample slf4j bidding issue raised and logs are not shipped to fluentd. There is no error in fluentd container, please clarify and direct to working sample I doubt the configurations are outdated

SLF4J: Failed to load class "org.slf4j.impl.StaticLoggerBinder".
SLF4J: Defaulting to no-operation (NOP) logger implementation
SLF4J: See http://www.slf4j.org/codes.html#StaticLoggerBinder for further details.

Using the provided docker command is not created any log file in /tmp folder

docker run --name fluentd-daemon -d -p 24224:24224 -p 24224:24224/udp -v /tmp:/fluentd/log -v /tmp:/fluentd/etc fluent/fluentd:v1.3-debian-1 -c /fluentd/etc/Customers.conf

kumuluzee-logs-fluentd : invalid version

Could not find artifact com.kumuluz.ee.logs:kumuluzee-logs-fluentd:jar:1.5.0-SNAPSHOT -> [Help 1]

Testing for fault tolerance with Hystrix

The documentation for the hystrix is really good, but how would someone test their microservice?
I've got a kumuluzee microservice with JWT-Auth and now i've added the Hystrix fault tolerance, but i dont see anywhere anything about testing these?
Mainly with regards to:

• CircuitBreaker
• Timeout
• BulkHead

I was just wondering how i can go about doing these without having to run my microservice and then have another application hitting the endpoints to test it.

Cheers

LocalDate support

Is there support for LocalDate object through rest interface ?
I get this issue when i pass simple date '2018-07-26' or complex one with '2018-07-26T09:03:44.867Z'
Any solutions or ideas ?

Can not construct instance of java.time.LocalDate: no String-argument constructor/factory method to deserialize from String value ('2018-07-26T09:03:44.867Z')
at [Source: org.glassfish.jersey.message.internal.ReaderInterceptorExecutor$UnCloseableInputStream@3e86c150; line: 5, column: 21] (through reference chain: com.lgim.nexus.omsadapter.domain.object.fx.order.SingleFxOrder["settlementDate"])