Package com.prowidesoftware.swift.model.mx

Class MxParseUtils

  • public class MxParseUtils
extends java.lang.Object
    This class provides utility methods to parse XML content using a fast event based API (no DOM) and to extract specific information from the XML content.
    Since:
    9.1.2

    • Constructor Summary

      Constructors 
      Constructor Description
      MxParseUtils()  

    • Method Summary

      All Methods Static Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      static boolean elementExists​(java.lang.String xml, java.lang.String localName)
      Checks if an element exists in the XML
      static java.util.Optional<java.lang.String> findByPath​(java.lang.String xml, java.lang.String targetPath)
      Finds an XML element within a document by traversing a specified tag hierarchy.
      static java.util.Optional<java.lang.String> findByTags​(java.lang.String xml, java.lang.String... tags)
      Finds an XML element within a document by traversing a specified tag hierarchy with potential any element in between the specified tags.
      static java.util.Optional<javax.xml.stream.XMLStreamReader> findElementByPath​(java.lang.String xml, java.lang.String targetPath)
      Deprecated.
      use findByTags(String, String...) instead
      static java.util.Optional<javax.xml.stream.XMLStreamReader> findElementByTags​(java.lang.String xml, java.lang.String... tags)
      Deprecated.
      use findByTags(String, String...) instead
      static java.lang.String getBICFromDN​(java.lang.String dn)
      Distinguished Name structure: cn=name,ou=payment,o=bank,o=swift
      Example: o=spxainjj,o=swift
      static java.util.Optional<SettlementInfo> getSettlementInfo​(java.lang.String xml)
      Extracts settlement information from the given XML document.
      static java.util.Optional<MxId> identifyMessage​(java.lang.String xml)
      Takes an XML with an MX message and detects the specific message type parsing just the namespace from the Document element.
      static java.lang.String makeXmlLenient​(java.lang.String xml)
      This method is intended to fix some malformed XML content that is not compliant with the XML specification to enable the parsing and processing of the payload to be lenient.
      static java.util.List<java.lang.String> parseComments​(java.lang.String xml)
      Parses all comments from the given XML document.
      static java.util.List<java.lang.String> parseCommentsContains​(java.lang.String xml, java.lang.String contains)
      Parses comments from the given XML document that contains a specific string.
      static java.util.List<java.lang.String> parseCommentsStartsWith​(java.lang.String xml, java.lang.String startWith)
      Parses comments from the given XML document that start with a specific prefix.
      static java.util.Optional<com.prowidesoftware.swift.model.mt.AbstractMT> parseMtFromMultiformatMessage​(java.lang.String xml)
      Parses an AbstractMT message from a multi-format XML message.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Constructor Detail

      • MxParseUtils

        public MxParseUtils()

    • Method Detail

      • getBICFromDN

        public static java.lang.String getBICFromDN​(java.lang.String dn)
        Distinguished Name structure: cn=name,ou=payment,o=bank,o=swift
        Example: o=spxainjj,o=swift
        Parameters:
        dn - the DN element content
        Returns:
        returns capitalized "bank", in the example SPXAINJJ

      • identifyMessage

        public static java.util.Optional<MxId> identifyMessage​(java.lang.String xml)
        Takes an XML with an MX message and detects the specific message type parsing just the namespace from the Document element. If the Document element is not present, or without the namespace or if the namespace url contains invalid content, then attempts to identify the message from the AppHdr. From the header tries to get the message type from the 'MsgDefIdr' that is present in the Business Application Header, and if that is not present tries to get the 'MsgName' assuming it is a legacy Application Header. If none of the above is present or cannot be parsed, then returns empty.

        Example of a recognizable Document element:
        <Doc:Document xmlns:Doc="urn:swift:xsd:camt.003.001.04" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

        The implementation is intended to be lightweight and efficient, based on XMLStreamReader

        Returns:
        id with the detected MX message type or empty if it cannot be determined.

      • makeXmlLenient

        public static java.lang.String makeXmlLenient​(java.lang.String xml)
        This method is intended to fix some malformed XML content that is not compliant with the XML specification to enable the parsing and processing of the payload to be lenient. For the moment, current implementation will just fix invalid case in the XML declaration, if present.
        Parameters:
        xml - original XML content
        Returns:
        modified XML content with the XML declaration fixed to be compliant with the XML specification
        Since:
        9.3.9

      • parseComments

        public static java.util.List<java.lang.String> parseComments​(java.lang.String xml)
        Parses all comments from the given XML document.

        This method uses an XMLStreamReader to parse the provided XML string and extract all comments present in the document. Comments are identified as XML elements of type XMLStreamConstants.COMMENT.

        All extracted comments are trimmed before being added to the result list. Meaning they will not contain any leading or trailing whitespace.

        Parameters:
        xml - the XML document as a String to parse
        Returns:
        a List of comments extracted from the XML document
        Throws:
        java.lang.NullPointerException - if the xml is null
        java.lang.IllegalArgumentException - if the xml is blank or empty
        Since:
        9.5.5

      • parseCommentsStartsWith

        public static java.util.List<java.lang.String> parseCommentsStartsWith​(java.lang.String xml,
                                                                       java.lang.String startWith)
        Parses comments from the given XML document that start with a specific prefix.

        This method uses parseComments(String) to extract all comments from the XML, filters the comments to include only those that start with the specified prefix.

        Parameters:
        xml - the XML document as a String to parse
        startWith - the prefix to filter comments by, leading whitespaces are ignored
        Returns:
        a List of filtered and cropped comments that start with the given prefix
        Throws:
        java.lang.NullPointerException - if the xml is null
        java.lang.IllegalArgumentException - if the xml is blank or empty
        Since:
        9.5.5

      • parseCommentsContains

        public static java.util.List<java.lang.String> parseCommentsContains​(java.lang.String xml,
                                                                     java.lang.String contains)
        Parses comments from the given XML document that contains a specific string.

        This method uses parseComments(String) to extract all comments from the XML, filters the comments to include only those that contains a specific string.

        Parameters:
        xml - the XML document as a String to parse
        contains - the content to filter comments by
        Returns:
        a List of filtered and cropped comments that start with the given prefix
        Throws:
        java.lang.NullPointerException - if the xml is null
        java.lang.IllegalArgumentException - if the xml is blank or empty
        Since:
        9.5.5

      • parseMtFromMultiformatMessage

        public static java.util.Optional<com.prowidesoftware.swift.model.mt.AbstractMT> parseMtFromMultiformatMessage​(java.lang.String xml)
        Parses an AbstractMT message from a multi-format XML message.

        This method searches for MT (Message Type) content within the comments of the provided XML document. Specifically, it extracts comments that start with the prefix "{1:F0", which indicates the presence of an MT message, and attempts to parse the first matching comment into an AbstractMT object.

        If an error occurs during parsing or no matching comments are found, the method returns an empty Optional.

        Parameters:
        xml - the XML document as a String containing the multi-format message
        Returns:
        an Optional containing the parsed AbstractMT if successful; otherwise, an empty Optional
        Throws:
        java.lang.NullPointerException - if the xml is null
        Since:
        9.5.5

      • getSettlementInfo

        public static java.util.Optional<SettlementInfo> getSettlementInfo​(java.lang.String xml)
        Extracts settlement information from the given XML document.

        This method attempts to parse the provided XML and extract information related to the settlement method and clearing system codes. Specifically:

        • SttlmMtd - The settlement method.
        • ClrSys > Cd - The clearing system code.
        • ClrSys > Prtry - The clearing system proprietary.

        If any of these elements are found, a SettlementInfo object is created and populated with the extracted values.

        Parameters:
        xml - the XML document as a String to parse for settlement information.
        Returns:
        an Optional containing the SettlementInfo if at least one of the required elements is found; otherwise, an empty Optional.
        Throws:
        java.lang.NullPointerException - if the xml is null.
        Since:
        9.5.5

      • findByTags

        public static java.util.Optional<java.lang.String> findByTags​(java.lang.String xml,
                                                              java.lang.String... tags)
        Finds an XML element within a document by traversing a specified tag hierarchy with potential any element in between the specified tags.

        This method uses an XMLStreamReader to parse the provided XML document. It searches for an element that matches the specified sequence of tag names (hierarchy). For example, to find the <Cd> tag within <ClrSys>, you would call: 

             findElement(xml, "ClrSys", "Cd");
        Notice that the <Cd> tag does not need to be a direct child of the <ClrSys> tag.

        It is important to remark the last tag in the sequence is the one that is expected to have text content, and not an intermediate tag.

        Parameters:
        xml - the XML document as a String to search.
        tags - the sequence of tag names that define the hierarchy of the target element.
        Returns:
        an Optional containing the matching element value or empty if not found.
        Throws:
        java.lang.NullPointerException - if the xml or tags are null.
        java.lang.IllegalArgumentException - if the xml is a blank string.
        Since:
        9.5.6

      • findElementByTags

        @Deprecated
@ProwideDeprecated(phase2=SRU2025)
public static java.util.Optional<javax.xml.stream.XMLStreamReader> findElementByTags​(java.lang.String xml,
                                                                                     java.lang.String... tags)
        Deprecated.
        use findByTags(String, String...) instead

      • findByPath

        public static java.util.Optional<java.lang.String> findByPath​(java.lang.String xml,
                                                              java.lang.String targetPath)
        Finds an XML element within a document by traversing a specified tag hierarchy.

        This method uses an XMLStreamReader to parse the provided XML document. It searches for an element that matches the specified path. For example, to find the <PgNb> you can call using absolute path or relative path: For relative path parameters you must use "//" as starting segment. 

             findByPath(xml, /Document/BkToCstmrStmt/GrpHdr/MsgPgntn/PgNb);
     findByPath(xml, //BkToCstmrStmt/GrpHdr/MsgPgntn/PgNb);

        It is important to remark the last tag in the sequence is the one that is expected to have text content, and not an intermediate tag.

        Parameters:
        xml - the XML document as a String to search.
        targetPath - the path of the field to find into the xml, could be absolute or relative (indicated with starting double slash)
        Returns:
        an Optional containing the found element value or empty if not found.
        Throws:
        java.lang.NullPointerException - if the xml or tags are null.
        java.lang.IllegalArgumentException - if the xml is a blank string.
        Since:
        9.5.6

      • findElementByPath

        @Deprecated
@ProwideDeprecated(phase2=SRU2025)
public static java.util.Optional<javax.xml.stream.XMLStreamReader> findElementByPath​(java.lang.String xml,
                                                                                     java.lang.String targetPath)
        Deprecated.
        use findByTags(String, String...) instead

      • elementExists

        public static boolean elementExists​(java.lang.String xml,
                                    java.lang.String localName)
        Checks if an element exists in the XML
        Parameters:
        xml - the XML content
        localName - the element name
        Returns:
        true if at least one element with the given name is found
        Since:
        9.5.5