Upgrading from 4.0.5 to 4.1.0

Generic Service Java projects use several functionalities provided by the dependency "cp-framework-sdk", which has been updated to include new fixes, and versions of underlying used dependencies.

All existing Generic Service Java projects have to download this new version and migrate to this new version.

With version 4.1.0 of IBM Industry Solutions Workbench the accessibility of Swagger has changed. In order to use it for existing Java projects, the configuration has to be migrated.

Domain Service Java projects use several functionalities provided by the dependency "cp-framework-sdk", which has been updated to include new fixes, and versions of underlying used dependencies.

All existing Domain Service Java projects are required to migrate to this new version.

1. Clone (k5 clone) or update (k5 pull) your service project

2. Open your service project

3. Navigate to pom.xml file

4. Search for the parent attribute and change it to match the new "cp-framework-sdk" version, see the following snippet example:

   <parent>
       <groupId>de.knowis.cp.sdk</groupId>
       <artifactId>cp-framework-managed-sdk-parent</artifactId>
       <version>4.0.247</version>
       <relativePath>
           ./.framework/repo/de/knowis/cp/sdk/cp-framework-managed-sdk-parent/4.0.247/cp-framework-managed-sdk-parent-4.0.247.pom
       </relativePath>
   </parent>

   NOTE Current latest version of "cp-framework-sdk" that is shipped with the IBM Industry Solutions Workbench 4.1 is 4.0.247.

5. Push your adjustment and run your pipeline(s) to make sure your projects deploy successfully

Since IBM Industry Solutions Workbench 4.1.0, some method signatures of API Operations changed, as the order of the parameters during generation was adjusted.

Before 4.1.0, required header parameters were not sorted before the not-required parameters in the generated method signature of API operations (unlike required query or path parameters). With 4.1.0 this bug got fixed and therefore the signature of some API operations will now changed. Please find below an example of how the signatures used to look and how they look since 4.1.0

Before:

@Override
public ResponseEntity<Void> myOperation(String reqPathParam, String reqQueryParam, MyRequestBody reqRequestBody, String someQueryParam, String reqHeaderParam, String, someHeaderParam) {
  ...
}

After:

@Override
public ResponseEntity<Void> myOperation(String reqPathParam, String reqQueryParam, String reqHeaderParam, MyRequestBody reqRequestBody, String someQueryParam, String, someHeaderParam) {
  ...
}

There are 2 options to handle this change:

• Option 1: Change your implemenation code
  • The easiest and safest way is to let the system re-generate the signature of your API method
  • Clone the project to your local machine
  • Open your APIProvider-Class
  • Comment out the API operation methods, so that your IDE will complain, that not all methods are implemented
  • Add all unimplemented methods (this way you get the new method signature)
  • Move your implementation code from your the commented methods to the new methods
  • Run k5 compile to ensure your code is working and run k5 push to push your changes to the remote git afterwards
• Option 2: Change your header parameters to be not required
  • If you don't want to adapt the code of your project, you could also change your required header parameters to be not required anylonger
  • After commiting and pushing the change through the Solution Designer, the project should compile again and no adaption in the code is necessary

Since IBM Industry Solutions Workbench 4.1.0, it is possible to use Date and Datetime properties within schemas that are used as event payloads (see related resolved issue Using the date type for sending events is blocked by the sender due to wrong validation). To allow this, existing projects have to be adjusted to have special settings defined.

Please execute the following steps:

• Open your pom.xml file of your application and find the plugin jsonschema2pojo-maven-plugin

• Add some additional configuration regarding formatting of Date and Datetime to the plugin

  <formatDates>true</formatDates>
  <formatDateTimes>true</formatDateTimes>
  <dateType>java.util.Date</dateType>
  <dateTimeType>java.time.OffsetDateTime</dateTimeType>

• After adjusting, the plugin should look similar to this:

  <plugin>
      <groupId>org.jsonschema2pojo</groupId>
      <artifactId>jsonschema2pojo-maven-plugin</artifactId>
      <version>1.1.2</version>
      <configuration>
          <sourceDirectory>${basedir}/src/main/generated-resources/schemas</sourceDirectory>
          <targetPackage>yourPackageName.yourProjectAcronym.sdk.domain.schemas</targetPackage>
          <outputDirectory>${basedir}/src/main/generated</outputDirectory>
          <formatDates>true</formatDates>
          <formatDateTimes>true</formatDateTimes>
          <dateType>java.util.Date</dateType>
          <dateTimeType>java.time.OffsetDateTime</dateTimeType>
      </configuration>
      <executions>
          <execution>
              <goals>
              <goal>generate</goal>
              </goals>
          </execution>
      </executions>
  </plugin>

• Run command k5 generate-code again to re-trigger code generation

• Adjust your implementation code wherever needed.

  Example:

  @Override
  public ResponseEntity<Void> publish() {
  
    // create new instance of event
    MyEventWithDateProperty ev = pubEventBuilder.getMyEventWithDateProperty().build();
  
    MySchema payload = new MySchema();
  
    // set date property
    payload.setDate(new Date());
  
    // publish event
    eventProducer.publish(ev);
  
    // further code
    ...
  }

If your Java project was created before IBM Industry Solutions Workbench 4.1.0, the project is based on Java Spring Boot Stack 1.0 which comes with Java Spring Boot 2 and Java 11. From IBM Industry Solutions Workbench 4.1.0 all projects that are created from scratch will by default use Java Spring Boot Stack 2.0 as a base which comes with Java Spring Boot 2 and Java 11.

To migrate your existing projects from Java Spring Boot Stack 1.0 to Java Spring Boot Stack 2.0 please check the following Upgrade Instructions