Implement Java pro-code projects

Prerequisites

Maven

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

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

Download dependencies

In order to build and run Java based pro-code projects, some Solution Envoy dependencies are required that come with many already configured tools.

  1. Open the Solution Envoy dashboard (you can find the link in Solution Designer on the CI/CD page after you have set up at least one deploy pipeline or inside Solution Hub after selecting a k5-project and opening the tab " Service Deployments")

  2. Navigate to the Infrastructure page and download all the dependencies listed under Maven Dependencies (Java).

Install dependencies

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

Tip: You can find the latest version information of the cp-framework-sdk in the upgrade overview
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

Running / building projects

Before you can start working on your pro-code project you have to create the project in Solution Designer and download all necessary artifacts and dependencies.

Create pro-code projects

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

Clone Git project to local machine

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>
Note: In order to be able to interact with the Git repository you have to provide the credentials for your Git system.

Open project

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

Open project with Eclipse

You can use the Import Wizard to command link import Java low-code projects into workspace.

  1. Launch Eclipse.

  2. Open or create a Workspace.

  3. From the main menu bar, select command link File > Import.... The Import wizard opens.

  4. Select General > Projects from Folder or Archive and click Next.

  5. Click the Directory button on the next page of the wizard to select the directory the name of the project acronym.

  6. Under Folder select all projects.

  7. Click Finish to start the import.

The imported project named project acronym-application is the working project it is automatically recognized and created as a Maven project. Alternatively, only the project acronym-application directory can be imported.

Open project with Eclipse

You can use the Welcome screen to import Java low-code projects.

  1. Launch IntelliJ IDEA.

    • If the Welcome screen opens, click Open.

    • Otherwise, from the main menu, select File | Open.

  2. In the dialog that opens, select the pom.xml file from the directory with the name of the project acronym-application and click Open.

Alternatively, project acronym can be opened and Maven set up.

Local Setup

  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
Note: Refer to Spring Boot's official documentation for more details on MongoDB and Kafka additional configuration.

Unit tests for pro-code projects

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>