20250205 ‐ Java 17 more explanation - cywongg/2025 GitHub Wiki

Below is an overview of the various files, configurations, and concepts you’ve mentioned, along with explanations of why they matter when upgrading to Java 17 and a newer Spring Boot version.

Historically, Spring Cloud Config introduced the concept of a bootstrap.yml file to load configurations (such as config-server properties) earlier, before the main application.yml. Starting from Spring Boot 2.4, however, there was a shift in how Spring handles property sources and config data loading. Some of the responsibilities of bootstrap.yml have been folded into Spring Boot’s main configuration mechanism through application.yml.

• Before: You might have had external config or cloud configuration details in bootstrap.yml that were loaded first, and application.yml was loaded after.
• Now: Newer Spring Boot versions prefer using application.yml for config data, and Spring Cloud also aligns with the main Spring Boot config data loader.

Therefore, you often see projects move or rename bootstrap.yml to application.yml. The goal is to reduce duplication and confusion, by having a single Spring configuration layer that automatically includes external config server properties as needed.

You mentioned a snippet like:

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-compiler-plugin</artifactId>
  <configuration>
    <source>${java.version}</source>
    <target>${java.version}</target>
    <annotationProcessorPaths>
      <path>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
        <version>${lombok.version}</version>
      </path>
    </annotationProcessorPaths>
  </configuration>
</plugin>

• Ensures that the Java source code is compiled to match a certain Java version (in your case, Java 17).
• <source> and <target> ensure your source code is recognized and compiled using Java 17 language features and bytecode.

• Lombok, MapStruct, and other libraries that process annotations at compile time require the annotation processing path.
• By specifying Lombok under <annotationProcessorPaths>, Maven will know to run Lombok’s annotation processor so that your IDE and build process properly generate boilerplate code (like getters, setters, etc.).

Without proper configuration of the Maven Compiler Plugin, you could get compilation issues or your Lombok/annotation-based code might not be recognized.

A Maven pom.xml (Project Object Model) has multiple sections. Common sections include:

1. modelVersion: Typically <modelVersion>4.0.0</modelVersion>, indicating the POM model version.
2. groupId: The top-level organization or group name (e.g., com.abc.wa).
3. artifactId: The name of the actual artifact (e.g., wa).
4. version: The version of the artifact (e.g., 1.0.0 or ${app.version}.${revision}).
5. packaging: Typically jar, though it can be war or other types.
6. properties: Holds custom properties such as java.version, lombok.version, or placeholders for external property references.
7. dependencies: A list of libraries your project depends on.
8. dependencyManagement: A central place to define versions of dependencies so child modules can inherit them.
9. build: Where you define plugins, plugin configurations, resources, and so forth.
   • plugins: Where you configure the Maven Compiler Plugin, Spring Boot Maven Plugin, etc.
   • resources: Indicate where resource files are included or filtered.
10. profiles: Part of Maven used to activate different configurations under different conditions (e.g., environment-based builds).

These are just the most common sections. Others exist for reporting, distribution management, etc.

You mentioned something like:

<assembly>
  <id>distribution</id>
  <formats>
    <format>zip</format>
  </formats>
  <fileSets>
    <fileSet>
      <directory>src/main/resources/bin</directory>
      <outputDirectory>.</outputDirectory>
      <includes>
        <include>*</include>
      </includes>
      <lineEnding>unix</lineEnding>
      <fileMode>0555</fileMode>
    </fileSet>
    <fileSet>
      <directory>src/main/resources</directory>
      <outputDirectory>conf</outputDirectory>
      <excludes>
        <exclude>bin/</exclude>
        <exclude>application*.ym</exclude>
        <exclude>dist/</exclude>
      </excludes>
    </fileSet>
    <fileSet>
      <directory>target/classes</directory>
      <outputDirectory>conf</outputDirectory>
      <includes>
        <include>application*.yml</include>
      </includes>
    </fileSet>
  </fileSets>
</assembly>

• The [Maven Assembly Plugin](https://maven.apache.org/plugins/maven-assembly-plugin/) can create a “distro” assembly (e.g., zip, tar, etc.) that contains your application jar plus supporting files, scripts, configs, etc.
• <id>distribution</id>: Identifies the assembly for referencing in the POM.
• <formats>: Declares output format(s), like zip, tar.gz, etc.
• <fileSets>: Tells the assembly plugin which files/folders to include in the final packaged archive, and where to place them.

For instance,

• The lineEnding and fileMode settings tell it to use UNIX line endings and set specific file permissions (e.g., 0555 for scripts).
• The <excludes> section can skip certain files (like bin/ or dist/).
• Placing application*.yml in conf ensures your YAML configs end up in the right place.

Many projects that used Springfox for Swagger documentation are migrating to Springdoc OpenAPI because Springfox ended up lagging behind on some Spring Boot versions and support. Springdoc OpenAPI integrates more smoothly with newer Spring Boot versions and modern OpenAPI 3 features.

So if you see references in the code that “api bank moved swagger from Springfox to open api,” it means:

• They replaced Springfox dependencies, configurations, and annotations with Springdoc OpenAPI dependencies and the corresponding configuration annotations.
• Sometimes you need to update your pom.xml or application.yml (or other config) to handle new endpoints for the OpenAPI docs (e.g., /v3/api-docs, /swagger-ui.html).

As mentioned earlier, new Spring Boot versions unify the config loading process so that external properties or remote config servers can be handled in application.yml without necessarily needing bootstrap.yml.

So, you might see instructions to:

1. Move or rename your old bootstrap.yml content into the main application.yml.
2. Rely on the Spring Boot Config Data API to load external config.

Maven has three main build lifecycles:

1. default (most commonly used, including phases like compile, test, package, verify, install, deploy),
2. clean (with the clean phase),
3. site (for generating project documentation).

Each lifecycle is composed of multiple build phases. During the default lifecycle, you have phases such as:

• compile → compiles source code
• test → runs unit tests
• package → packages to JAR/WAR
• verify → runs checks on the package
• install → installs the package into your local Maven repository
• deploy → deploys the final package to a remote repository

When you run mvn package, Maven automatically runs all previous phases in the correct order (it will do compile → test → then package).

In the pom.xml, these properties define your artifact coordinates:

• groupId: Generally your organization or domain’s reversed name (e.g., com.abc.wa).
• artifactId: The name of the specific module/artifact (e.g., wa).
• version: The version of your project. Here, it uses property placeholders:

  <version>${app.version}.${revision}</version>

  This means the “real” version is resolved by reading the app.version and possibly revision properties from the <properties> section or from a command-line injection. This is a common pattern to unify version management across different modules or CI/CD pipelines.

You gave an example:

spring:
  config:
    import: optional:configserver:${CONFIG_SVC_URL}
  cloud:
    config:
      name: waxpi
      label: "@project.artifactId@-@version@,master"
      retry:
        max-attempts: 200
        initial-interval: 60000
        multiplier: 1.0
        max-interval: 60000

And another snippet:

spring:
  config:
    activate:
      on-profile: local
    import: optional:configserver:https://wa-uat.gslb.cloud.abcn/fig-uat/config
  cloud:
    config:
      label: master

• spring.config.import: Tells Spring Boot where to fetch additional configurations from. configserver:${CONFIG_SVC_URL} indicates that there is a Spring Cloud Config server running at ${CONFIG_SVC_URL}. optional: means if it’s not available, boot won’t fail; it’ll continue with local config.
• spring.cloud.config.name and spring.cloud.config.label: Indicate to the config server which application name and Git label/branch to pull from.
• retry settings: Tells Spring Cloud Config how many times to retry fetching configs, how long to wait between retries, etc.
• on-profile: local: Means these config properties only apply when the local profile is active.
• @project.artifactId@-@version@ placeholders**: Often replaced at build time with the actual artifact ID and version, so your config server can differentiate your environment or version.

In short, these blocks allow your application to fetch configuration from a remote config server or rely on local property files, providing more flexible and centralized config management.

• Upgrading to Java 17 typically involves updating your maven-compiler-plugin configuration and ensuring all dependencies (such as Lombok, Spring Boot, Spring Cloud) are compatible.
• Migrating from bootstrap.yml to application.yml follows the recommended approach in newer Spring Boot versions for config loading.
• Switching from Springfox to Springdoc is a common modern upgrade for API documentation.
• Assembly plugin usage shows how you package distribution artifacts.

All these changes reflect modernization and alignment with the latest Spring Boot and Maven conventions.

Hopefully, this clarifies the purpose and usage of the different files, plugins, and configurations in your project!