Implement Java pro-code projects

A Java 11 SDK is needed to develop Java based pro-code projects.

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. The "Create project" dialog lets you create several types of projects. Be sure to choose one of the "Generic Service Project" project types.

Next fill out all required fields, check on "Open after creation" and click on "Create".

In order to build and run the project, the Git project needs to be cloned to the user's workspace. To check out a pro-code 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>

5. 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"

6. 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>

7. 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>

8. 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>

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

   -Dspring.profiles.active=local

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>