Implement Generic Service Java

A Java 11 SDK is needed to develop Generic Service Projects (Java).

Please download either the Oracle 11 JDK from https://www.oracle.com/java/technologies/downloads/#java11 or the Open JDK from https://openjdk.java.net/ and follow the installation instructions of the JDK.

Maven version >=3.6.1 is required to develop custom implementation Java based projects.

Please download and install maven from https://maven.apache.org.

We recommend using Eclipse in the latest version which can be downloaded from: https://www.eclipse.org/downloads/

The downloaded dependencies must be installed in the local maven repository. Here is an example how the dependencies can be installed via maven.

mvn install:install-file -Dfile=cp-framework-sdk-autoconfiguration-x.y.z.jar -DpomFile=cp-framework-sdk-autoconfiguration-x.y.z.pom
mvn install:install-file -Dfile=cp-framework-sdk-parent-x.y.z.pom -DpomFile=cp-framework-sdk-parent-x.y.z.pom

Open Solution Designer and create a new project by clicking on the Create button and select Generic Service Projects (Java). Provide additional information required and click on Create. Once this is created the project should appear in the Solution Designer. Optional: Open that project in Solution Designer and write a proper documentation.

In order to build and run the project, the Git project needs to be cloned to the user's workspace. To check out a project, follow the steps below:

1. Open the project in Solution Designer

2. In the bottom of the page there is the status bar. Click on Git

3. Copy the Git repository URI.

4. Open a terminal and clone the project. You will be prompted for a password. Please use your personal access token as password:

   git clone <URI>

Open your project folder using Eclipse, IntelliJ or preferred IDE.

1. Create an application-local.yaml file and override properties needed for the local profile. As a template you can use the file application-local.template.yaml.

2. Depending on which configuration approach from above add either your OpenShift k5-project namespace or a dummy namespace mock value

   de:
     knowis:
       cp:
         consumer:
           kubernetes:
             namespace: "namespace-name"

3. Load MongoDB configuration from k8s configuration map

   feature:
     mongo:
       enabled: true
   
   #mongoDb configuration from k8s secret
   spring:
     data:
       mongodb:
         secretName: "k5-default-document-storage-service-binding"

4. To access local MongoDB, you can set the spring.data.mongodb.uri property to change the URL and configure additional settings such as the replica set, as shown in the following example:

   feature:
     mongo:
       enabled: true
   
   spring:
     data:
       mongodb:
         database: <database>
         uri: mongodb://<username>:<secret>@<host>:<port>

   Alternatively, you can specify connection details using discrete properties. For example, you might declare the following settings as shown below:

   spring:
     data:
       mongodb:
         host: <host>
         port: <port>
         database: <database>
         username: <username>
         password: <password>

Alternatively, you can also disable MongoDB if it is not needed. See Disabling MongoDB.

1. Load event topic binding configuration from k8s secret(s)

   1. You need to add your k5-project name in step 2.

   2. You need to have proper oc proxy and oc port forwarding to be able to access your OpenShift k5 project event topic binding secret(s) and their configured Kafka cluster.

   feature:
     kafka-events:
       enabled: true
   
   #kafka configuration from k8s secret
   de:
     knowis:
       cp:
         consumer:
           kafka:
             binding:
               secretName: "k5-default-kafka-binding"

2. Alternatively, you can configure to use your Kafka brokers.

   1. Install and configure your Kafka broker. See https://kafka.apache.org/quickstart.

   2. The mandatory parameters for the Kafka events Configuration

   feature:
     kafka-events:
       enabled: true
   
   de:
     knowis:
       cp:
         consumer:
           kafka:
             binding:
               kafka_brokers_sasl: "<kafka SASL>"
               user: ""
               password: ""

   Note: Kafka broker user and password are optional if your Kafka broker is not secured.

   1. The following parameters can be optionally changed.

   de:
     knowis:
       cp:
         consumer:
           kafka:
             binding:
               securityProtocol: SASL_SSL
               saslMechanism: SCRAM-SHA-512
               sslProtocol: TLSv1.2
               sslEnabledProtocols: TLSv1.2
               sslIdentificationAlgorithm: HTTPS
               saslJaasConfigLoginModuleQualifiedName: org.apache.kafka.common.security.scram.ScramLoginModule
               kafka_custom_config: <kafka_custom_config>

3. To configure Swagger UI for local development, use the settings below:

   feature:
     openapi:
       enabled: true
     webmvc:
       enabled: true
   
   springdoc:
     swagger-ui:
       oauth:
         clientId: <client-id>

4. If you have spring-security-oauth2-client on your classpath, you can take advantage of some autoconfiguration to set up an OAuth2/Open ID Connect client, as shown in the following example:

   feature:
     security:
       enabled: true
   
   spring:
     security:
       oauth2:
         client:
           provider: <provider-name>
             default:
               redirect-uri: <redirect-url>
           registration:
             default:
               client-id: <client-id>

5. Build and run the code. Pass the configuration below in jvm arguments to use the local profile.

   -Dspring.profiles.active=local

You can disable MongoDB if its not needed using below steps

1. Disable MongoDB feature flag.

feature:
  mongo:
    enabled: false

1. Remove the DbService.java, DBServiceTest.java

2. Remove DBService dependency from HelloWorldController.java , HelloWorldControllerTest.java

3. In your application entry point exclude MongoAutoConfiguration.class from spring boot application context

   @SpringBootApplication(exclude = MongoAutoConfiguration.class)
   public class SOMEApplication {
     ...
   }

It's highly recommended writing unit tests for your Java projects. The unit tests will be executed during the project pipeline execution as part of the maven build.

By default, JUnit 5 is set as the test library in Spring Boot. If you want to use JUnit 4, you have to add the following dependency in pom.xml.

<dependency>
    <groupId>org.junit.vintage</groupId>
    <artifactId>junit-vintage-engine</artifactId>
    <scope>test</scope>
    <exclusions>
        <exclusion>
            <groupId>org.hamcrest</groupId>
            <artifactId>hamcrest-core</artifactId>
        </exclusion>
    </exclusions>
</dependency>