Implement Domain Service Java

At this point it is assumed that the initial setup and the mandatory commands of the Solution CLI have been performed and executed as described.

Prerequisites

Be sure you have set up and installed all pre-requisites and development tools.

Create a new project workspace

After you have created a project in Solution Designer and modelled it according to Domain Driven Design principles, create a folder for your workspace. Then, open a terminal and navigate to your development workspace folder.

Example:

cd /my/workspace/

Clone project to local workspace

Inside Solution Designer, open the project and click on Project CLI in the task bar located at the bottom of the page.

There, you will find instructions on how to set up the CLI and connect it with your k5-project. The section Implementation provides the necessary information for the k5 clone command to clone the project to your local workspace.

Note:

You will be prompted for your username and password for this k5-project. A folder in your workspace will be created for the cloned project, where the folder name will be the project acronym.

Example:

/my/workspace/SOL

Open project

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

Open project with Eclipse

You can use the Import Wizard to import Domain Service Projects (Java) 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 IntelliJ

You can use the Welcome screen to import Domain Service Projects (Java).

  1. Launch IntelliJ.
    • 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 project and click Open.

For projects based on Java Spring Boot Stack 1.0

If you encounter an error related to missing maven dependency de.knowis.cp.sdk:cp-framework-sdk-parent:pom:x.y.z, then you have to update the project's pom.xml file in the Git repository due to updates in the cp-framework. There is only the root level pom.xml file that has to be changed.

  • First, see upgrade overview to find the current version of the cp-framework-managed-sdk-parent-x.y.z
  • Then, inside the project search for the root pom.xml, search for the <parent> attribute and change it according to the following snippet:
<parent>
    <groupId>de.knowis.cp.sdk</groupId>
    <artifactId>cp-framework-managed-sdk-parent</artifactId>
    <version>x.y.z</version>
    <relativePath>
        ./.framework/repo/de/knowis/cp/sdk/cp-framework-managed-sdk-parent/x.y.z/cp-framework-managed-sdk-parent-x.y.z.pom
    </relativePath>
</parent>

Project structure

Note:

The base project structure is depending on whether the project is based on Java Spring Boot Stack 1.0 or Java Spring Boot Stack 2.0

Java Spring Boot Stack 2.0

The project is structured into several source folders and some configuration files inside the projects root directory:

  • src/main/generated-java: Holds the generated files for API and Domain Namespaces.
  • src/main/generated-resources: Holds the generated resources files.
  • src/main/generated-sdk: Holds the generated SDK files.
  • src/main/java: Holds the project's spring boot entry point and also stub files where solution engineer needs to implement logic for API, services, commands, agents and external entities services.
  • src/main/resources: Holds the resources files such as application.yaml, application-local-template.yaml, API specifications and schema definitions.
  • src/test/generated-sdk: Holds the generated SDK test files.
  • src/test/java: Holds the test files (currently only one test file for database service).
  • src/test/resources: Holds the resources files for running tests.
  • src-design: Holds the DDD model files.
  • target: The maven default output folder. When a project is built or packaged, all the content of the sources, resources and web files will be put inside.
  • pom.xml: XML file that contains information about the project and configuration details used by Maven to build the project.

Managed pom.xml

In Java Spring Boot Stack 2.0, the pom.xml of the project is highly dependent on the enabled extensions. The pom file therefore is updated automatically when code generation is triggered (e. g. on k5 clone, k5 pull, k5 generate-code or while running the pipeline). The auto managed parts in pom.xml are separated from other content by using XML-comments. Anything inside these comments is managed and updated by code generation, whereas anything outside the comments is treated as custom and needs to be updated manually.

Warning:

Please ensure that the below described comments are always present in pom.xml. Otherwise, the pom file might get inconsistent.

Managed parent in pom.xml

Every project relies on an auto generated parent which is added to the pom.xml.

Note:

It is not allowed to modify the generated parent entry in the pom file

Example:

<project>
  <parent>
    <!-- Generated Parent - code-generation-provider -->
    <!-- This part will be overwritten -->
    <artifactId>spring-boot-starter-parent</artifactId>
    <groupId>org.springframework.boot</groupId>
    <version>3.1.7</version>
    <relativePath />
    <!-- Generated Parent - code-generation-provider -->
  </parent>
</project>
Managed properties in pom.xml

Some of the available extensions expect certain properties to exist in the pom file. They are auto generated and shouldn't be modified by hand.

Example:

<project>
  <properties>
    ...
    <!-- Generated Properties - code-generation-provider -->
    <!-- This part will be overwritten -->
    <prop1>someValue</prop1>
    <!-- Generated Properties - code-generation-provider -->
    ...
  </properties>
</project>
Tip:

Custom properties can be added to your pom.xml by adding them outside the XML-comment

Managed dependencies in pom.xml

An enabled extension usually comes with dependencies which are added to the pom file. It is also quite common, that there are version upgrades of some dependencies performed with new versions of IBM Industry Solutions Workbench.

Some of the dependencies are added under dependencies, whereas others are added under dependencyManagement (see Apache Maven: Introduction to the Dependency Mechanism for futher details). To ensure a working service, the auto generated dependencies are not allowed to be modified by hand.

Example:

<project>
  <dependencies>
    ...
    <!-- Generated Dependencies - code-generation-provider -->
    <!-- This part will be overwritten -->
    <dependency>
      <groupId>org.springframework</groupId>
      <artifactId>spring-beans</artifactId>
    </dependency>
    <dependency>
      <groupId>org.springframework.cloud</groupId>
      <artifactId>spring-cloud-starter-kubernetes-fabric8</artifactId>
    </dependency>
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-actuator</artifactId>
    </dependency>
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-data-mongodb</artifactId>
    </dependency>
    <!-- Generated Dependencies - code-generation-provider -->
    ...
  </dependencies>
  <dependencyManagement>
      ...
      <!-- Generated Dependency Management - code-generation-provider -->
      <!-- This part will be overwritten -->
      <dependency>
        <groupId>org.springframework.cloud</groupId>
        <artifactId>spring-cloud-dependencies</artifactId>
        <version>2022.0.4</version>
        <type>pom</type>
        <scope>import</scope>
      </dependency>
      <!-- Generated Dependency Management - code-generation-provider -->
      ...
    </dependencies>
  </dependencyManagement>
</project>
Tip:

Custom dependencies can be added to your pom.xml by adding them outside the XML-comment

Managed plugins in pom.xml

Some of the available extensions require additional plugins, which are also automatically generated.

Example:

<project>
  <build>
    <plugins>
      ...
      <!-- Generated Plugins - code-generation-provider -->
      <!-- This part will be overwritten -->
      <plugin>
        <groupId>org.jsonschema2pojo</groupId>
        <artifactId>jsonschema2pojo-maven-plugin</artifactId>
        <version>1.1.2</version>
        <configuration>
          <sourceDirectory>${basedir}/src/main/resources/schemas</sourceDirectory>
          <targetPackage>k5.springboot.tstk5stckjvsprnglcm.sdk.domain.schemas</targetPackage>
          <outputDirectory>${basedir}/src/main/generated-java</outputDirectory>
        </configuration>
        <executions>
          <execution>
            <goals>
              <goal>generate</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
      <!-- Generated Plugins - code-generation-provider -->
      ...
    </plugins>
  </build>
</project>
Tip:

Custom plugins can be added to your pom.xml by adding them outside the XML-comment.

Java Spring Boot Stack 1.0 (Deprecated)

The project is structured into several source folders and some configuration files inside the ProjectAcronym-application folder:

  • src/main/java: Holds the project's spring boot entry point and also stub files where solution engineer needs to implement logic for API, services, commands, agents and external entities services.
  • src/main/generated: Holds the generated SDK files for API and Domain Namespaces.
  • src/test/java: Holds the test files (currently only one test file for database service).
  • src/main/resources: Holds the resources files such as application.yaml, application-local-template.yaml, API specifications and schema definitions.
  • src/test/resources: Holds the resources files for running tests.
  • target: The maven default output folder. When a project is built or packaged, all the content of the sources, resources and web files will be put inside.
  • pom.xml: XML file that contains information about the project and configuration details used by Maven to build the project.

Project local profile configuration setup

To setup your project local profile configuration, please see Setup Java local profile.

Project stubs package structure

Contains Java stub (implementation files) classes where solution engineers can implement logic for modelled operations, services, commands, agents and external entities.

The base package for stubs is named according to package name that is set in the project's General Information and the project acronym, for example: com.mycompany.cnr

It consists of two main sub-packages Api and Domain, where each package groups several namespaces. Api and domain sub-packages correspond to the namespace types that are described in Introduction to Namespaces.

Each namespace will get its own sub-package with its own prefix.

Example:

  • com.mycompany.cnr.api.apins1: corresponds to an API Namespace with prefix APIns1
  • com.mycompany.cnr.domain.dns1: corresponds to a domain namespace with prefix dns1

Project SDK package structure

Contains SDK classes that provide base classes for modelled operations, services, commands, agents and external entities as well as necessary configuration and services needed to run application.

The base package for SDK is named according to the package name that is set in the project's Master Data and the project acronym with addition of "sdk/API" to distinguish it from project stubs, for example: com.mycompany.cnr.sdk

It consists of two main sub-packages Api and Domain, where each package groups several namespaces. Api and domain sub-packages correspond to the namespace types that are described in Introduction to Namespaces. Each namespace will get its own sub-package with its own prefix.

Example:

  • com.mycompany.cnr.api.apins1.api: corresponds to an API Namespace with prefix APIns1
  • com.mycompany.cnr.sdk.domain.dns1: corresponds to a domain namespace with prefix dns1

Unit tests for Domain Service Projects (Java)

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>

Disable git-commit-id-plugin for local development (optional)

You can disable the git-commit-id-plugin for local development, if you experience a negative performance impact:

  1. Open {USER_HOME}/.m2/settings.xml

  2. Add following profile with any unique id, e.g., gitcommitidskip

    <settings ...>
  <!-- ... -->
  <profiles>
    <!-- ... -->
    <!-- New profile gitcommitidskip start -->
        <profile>
            <id>gitcommitidskip</id>
            <activation>
                <property>
                    <name>!skipgitcommitidskip</name>
                </property>
            </activation>
            <properties>
                <maven.gitcommitid.skip>true</maven.gitcommitid.skip>
            </properties>
        </profile>
    <!-- New profile gitcommitidskip end -->