SRU2024 v9.5

CHANGELOG.md

@@ -1,8 +1,22 @@
 # Prowide ISO 20022 - CHANGELOG
 
-#### 9.4.6 - May 2024
+#### 9.5.2 - SNAPSHOT
   * (PW-1875) Fixed the `ZuluDateTimeAdapter` to convert the datetime to UTC offset if needed
-
+
+#### 9.5.1 - June 2024
+  * Enhanced the AppHdrFactory to honor the business service set in the parameter MxId
+  * Enhanced the MxParseUtils#identifyMessage to set the business service in the MxId when present
+
+#### 9.5.0 - May 2024
+  * SWIFT Standard release update 2024 (live 16 November 2024)
+  * Yearly revision of deprecation phase (see https://dev.prowidesoftware.com/SRU2024/getting-started/deprecation/)
+  * Added message categories for File Management (cafm), Fraud Reporting and Disposition (cafm), Network Management (canm) and Settlement Reporting (casr)
+  * Add support in the MxWriteConfiguration to use standard envelopes for SWIFT and ISO 20022
+  * Changed the default Document prefix to the message category; "camt", "pacs", etc...
+  * Enhanced MxId with optional and transient businessService field to act as a message type discriminator
+  * Dependency update: commons-lang3 -> 3.14.0
+  * Dependency update: gson -> 2.11.0
+
 #### 9.4.5 - May 2024
   * (PW-1875) Changed the BusinessApplicationHeaderV01 marshaller to always use Zulu timezone with "Z" indicator
 

build.gradle

@@ -6,7 +6,7 @@ buildscript {
 	dependencies {
 		classpath 'ru.vyarus:gradle-quality-plugin:4.7.0'
 		classpath 'pl.allegro.tech.build:axion-release-plugin:1.13.6'
-		classpath 'io.github.gradle-nexus:publish-plugin:1.1.0'
+		classpath 'io.github.gradle-nexus:publish-plugin:2.0.0'
 		classpath 'com.diffplug.spotless:spotless-plugin-gradle:6.13.0' // above this version requires Java 11
 	}
 }
@@ -23,7 +23,7 @@ archivesBaseName = 'pw-iso20022'
 group 'com.prowidesoftware'
 
 project.ext {
-	SRU = 'SRU2023'
+	SRU = 'SRU2024'
 }
 
 scmVersion {
@@ -134,21 +134,21 @@ configure(subprojects.findAll {it.name.endsWith('-mx')}) {
 project(':iso20022-core') {
 	dependencies {
 		// included build
-		api 'com.prowidesoftware:pw-swift-core:SRU2023-9.4.16'
+		api 'com.prowidesoftware:pw-swift-core:SRU2024-9.5.0'
 
-		implementation 'org.apache.commons:commons-lang3:3.12.0'
-		implementation 'com.google.code.gson:gson:2.9.0'
+		implementation 'org.apache.commons:commons-lang3:3.14.0'
+		implementation 'com.google.code.gson:gson:2.11.0'
 
 		compileOnly 'javax.persistence:javax.persistence-api:2.2'
 		compileOnly 'javax.validation:validation-api:2.0.1.Final'
 
 		testImplementation 'javax.persistence:javax.persistence-api:2.2'
-		testImplementation('org.junit.jupiter:junit-jupiter:5.8.2')
-		testImplementation group: 'com.google.guava', name: 'guava', version: '31.1-jre'
-		testImplementation group: 'org.assertj', name: 'assertj-core', version: '3.22.0'
-		testImplementation group: 'org.xmlunit', name: 'xmlunit-core', version: '2.9.0'
-		testImplementation group: 'org.xmlunit', name: 'xmlunit-matchers', version: '2.9.0'
-		testImplementation group: 'org.xmlunit', name: 'xmlunit-assertj', version: '2.9.0'
+		testImplementation 'org.junit.jupiter:junit-jupiter:5.10.2'
+		testImplementation 'com.google.guava:guava:33.2.0-jre'
+		testImplementation 'org.assertj:assertj-core:3.25.3'
+		testImplementation 'org.xmlunit:xmlunit-core:2.10.0'
+		testImplementation 'org.xmlunit:xmlunit-matchers:2.9.0'
+		testImplementation 'org.xmlunit:xmlunit-assertj:2.9.0'
 		testImplementation project(':model-acmt-mx')
 		testImplementation project(':model-acmt-types')
 		testImplementation project(':model-camt-mx')
@@ -313,9 +313,9 @@ artifacts {
 // declared dependencies for pom generation
 dependencies {
 	// included build (keep in sync with the latest Prowide Core version)
-	api 'com.prowidesoftware:pw-swift-core:SRU2023-9.4.16'
-	implementation 'org.apache.commons:commons-lang3:3.12.0'
-	implementation 'com.google.code.gson:gson:2.9.0'
+	api 'com.prowidesoftware:pw-swift-core:SRU2024-9.5.0'
+	implementation 'org.apache.commons:commons-lang3:3.14.0'
+	implementation 'com.google.code.gson:gson:2.10'
 }
 
 // repo for publishing

iso20022-core/src/main/java/com/prowidesoftware/swift/model/MxBusinessProcess.java

@@ -31,9 +31,13 @@ public enum MxBusinessProcess {
     caad("Card Administration"),
     caam("ATM Management"),
     cafc("Fee Collection"),
+    cafm("File Management"),
+    cafr("Fraud Reporting and Disposition"),
     cain("Acquirer to Issuer Card Transactions"),
     camt("Cash Management"),
+    canm("Network Management"),
     casp("Sale to POI Card Transactions"),
+    casr("Settlement Reporting"),
     catm("Terminal Management"),
     catp("ATM Card Transactions"),
     cbrf(""),
@@ -57,7 +61,7 @@ public enum MxBusinessProcess {
     /**
      * @deprecated Obsolete to be withdrawn (non-ISO)
      */
-    @ProwideDeprecated(phase3 = TargetYear.SRU2024)
+    @ProwideDeprecated(phase4 = TargetYear.SRU2025)
     @Deprecated
     trea("Treasury"),
 
@@ -66,7 +70,7 @@ public enum MxBusinessProcess {
     tsrv("Trade Services"),
     xsys("System Message");
 
-    private String description = null;
+    private String description;
 
     private MxBusinessProcess(final String description) {
         this.description = description;

iso20022-core/src/main/java/com/prowidesoftware/swift/model/MxId.java

@@ -16,6 +16,7 @@
 package com.prowidesoftware.swift.model;
 
 import java.util.Objects;
+import java.util.Optional;
 import java.util.regex.Matcher;
 import java.util.regex.Pattern;
 import org.apache.commons.lang3.StringUtils;
@@ -24,9 +25,8 @@
  * Class for identification of MX messages.
  *
  * <p>It is composed by the business process (business area), functionality (message type), variant and version.
- * For a better understanding of ISO 20022 variants check https://www.iso20022.org/variants.page
+ * For a better understanding of ISO 20022 variants check https://www.iso20022.org/variants page
  *
- * @author miguel
  * @since 7.7
  */
 public class MxId {
@@ -35,13 +35,12 @@ public class MxId {
     private String functionality;
     private String variant;
     private String version;
+    /**
+     * @since 9.5.0
+     */
+    private transient String businessService;
 
-    public MxId() {
-        this.businessProcess = null;
-        this.functionality = StringUtils.EMPTY;
-        this.variant = StringUtils.EMPTY;
-        this.version = StringUtils.EMPTY;
-    }
+    public MxId() {}
 
     /**
      * Creates a new object getting data from an MX message namespace.
@@ -59,8 +58,8 @@ public MxId(final String namespace) {
                 this.businessProcess = MxBusinessProcess.valueOf(bpStr);
             } catch (final Exception e) {
                 throw new IllegalArgumentException(
-                        "Illegal value for business process: '" + bpStr + "' see enum values in "
-                                + MxBusinessProcess.class.getName() + " for valid options",
+                        "Unrecognized value for business process: '" + bpStr + "' see enum values in "
+                                + MxBusinessProcess.class.getName() + " for expected options",
                         e);
             }
             this.functionality = matcher.group(2);
@@ -152,15 +151,15 @@ public String camelized() {
     }
 
     public int getVersionInt() {
-        return Integer.valueOf(getVersion());
+        return Integer.valueOf(this.version);
     }
 
     public int getVariantInt() {
-        return Integer.valueOf(getVariant());
+        return Integer.valueOf(this.variant);
     }
 
     public int getFunctionalityInt() {
-        return Integer.valueOf(getFunctionality());
+        return Integer.valueOf(this.functionality);
     }
 
     /**
@@ -209,6 +208,19 @@ public String toString() {
         return id();
     }
 
+    /**
+     * Indicates whether some other object is "equal to" this one.
+     *
+     * <p>Overrides the default implementation of {@link Object#equals(Object)}.
+     * This method considers two {@code MxId} objects equal if their
+     * {@code businessProcess}, {@code functionality}, {@code variant},
+     * and {@code version} fields are equal.
+     *
+     * <p>Notice the business service field is not included in the comparison.
+     *
+     * @param o the reference object with which to compare
+     * @return {@code true} if this object is the same as the obj argument; {@code false} otherwise
+     */
     @Override
     public boolean equals(Object o) {
         if (this == o) return true;
@@ -220,6 +232,17 @@ public boolean equals(Object o) {
                 && Objects.equals(version, mxId.version);
     }
 
+    /**
+     * Returns a hash code value for the object.
+     *
+     * <p>Overrides the default implementation of {@link Object#hashCode()}.
+     * This method generates a hash code based on the {@code businessProcess},
+     * {@code functionality}, {@code variant}, and {@code version} fields.
+     *
+     * <p>Notice the business service field is not included in the hash code calculation.
+     *
+     * @return a hash code value for this object
+     */
     @Override
     public int hashCode() {
         return Objects.hash(businessProcess, functionality, variant, version);
@@ -270,4 +293,38 @@ public boolean matches(MxId other) {
                         || StringUtils.isBlank(other.getVersion())
                         || StringUtils.equals(this.version, other.getVersion()));
     }
+
+    /**
+     * Get the category of the message, which is the business process name.
+     * @return the business process name or null if not set
+     * @since 9.5.0
+     */
+    public String category() {
+        return this.businessProcess != null ? this.businessProcess.name() : null;
+    }
+
+    /**
+     * Get the optional business service, which could be an additional value to differentiate messages within the same
+     * message type. For example "swift.cbprplus.cov.02". Notice when the MxId is created from the namespace this value
+     * is not set. This value must be set manually by the application when the MxId is extracted from a whole message
+     * and the AppHdr is available. Alternatively, the application can set this value with any other context information
+     *  and use it as a discriminator.
+     * @return the business service value or null if not set
+     * @since 9.5.0
+     */
+    public Optional<String> getBusinessService() {
+        return Optional.ofNullable(StringUtils.trimToNull(this.businessService));
+    }
+
+    /**
+     * Set the business service, which could be an additional value to differentiate messages within the same message
+     * type. This is mainly intended to contain the business services from the message AppHdr, but could potentially
+     * be used to hold any other value that helps to differentiate messages within the same message type.
+     * @param businessService a string value to set as discriminator, for example "swift.cbprplus.cov.02"
+     * @since 9.5.0
+     */
+    public MxId setBusinessService(String businessService) {
+        this.businessService = businessService;
+        return this;
+    }
 }

iso20022-core/src/main/java/com/prowidesoftware/swift/model/MxSwiftMessage.java

@@ -247,6 +247,7 @@ private void _updateFromMessage(final MxId id, final MessageMetadataStrategy met
             AppHdr header = getAppHdr();
             if (identifier == null && header != null && header.messageName() != null) {
                 identifier = new MxId(header.messageName());
+                identifier.setBusinessService(header.serviceName());
             }
 
             extractMetadata(identifier, header, metadataStrategy);
@@ -456,6 +457,9 @@ public int hashCode() {
      * @since 9.0.1
      */
     public AppHdr getAppHdr() {
+        if (this.message() == null) {
+            return null;
+        }
         return AppHdrParser.parse(this.message()).orElse(null);
     }
 
@@ -491,7 +495,12 @@ public String toString() {
      * @since 7.10.4
      */
     public MxId getMxId() {
-        return new MxId(this.businessProcess, this.functionality, this.variant, this.version);
+        MxId mxId = new MxId(this.businessProcess, this.functionality, this.variant, this.version);
+        AppHdr header = getAppHdr();
+        if (header != null) {
+            mxId.setBusinessService(header.serviceName());
+        }
+        return mxId;
     }
 
     /**
@@ -503,6 +512,9 @@ public MxId getMxId() {
      */
     @Override
     public String getCategory() {
+        if (this.businessProcess != null) {
+            return this.businessProcess.name();
+        }
         if (!StringUtils.isBlank(this.identifier)) {
             MxBusinessProcess proc = (new MxId(this.identifier)).getBusinessProcess();
             if (proc != null) {