Builder API (Java to XML)

The MX messages builder API is provided to create new MX messages from Java, and serialize its content into XML.

Message model

The creation of a new message basically consists of creating an object that represents the message, and the subsequent addition of inner elements.

The order is not important because the model is already constrained to the correspondent tree structure of the XML. Although this does not mean the builder API will verify validation constraints of the message but the model will naturally allow only proper elements to be appended.

A comprehensive list of all the available MX messages and their inner elements can be found in the library. This model covers all the MX messages defined in the ISO 20022 standard. It is generated by a customized JAXB process that transforms the ISO 20022 XSD files into Java classes building a reusable dictionary of all the messages and elements, share across message types.

This Sample code shows how to create an MX ACMT.001.001.03 message:

MxAcmt00100103 mx = new MxAcmt00100103()
    .setAcctOpngInstr(new AccountOpeningInstructionV03()
        .setAcctPties(new AccountParties6()
            .setAdmstr(new InvestmentAccountOwnershipInformation6()
                .setClntId("clntId"))
            .setPrncplAcctPty(new AccountParties1Choice()
                .setNmnee(new InvestmentAccountOwnershipInformation6()
                    .setPty(new Party14Choice()
                        .setOrg(new Organisation13().setNm("orgName"))
                    )
                )
            )
        )
    );

String mxXml = mx.message();
System.out.println(mxXml);

To simplify the resulting builder code, all setters in the business dictionary allow chained method calls.

Also, inner element class names match the exact names as defined in the MX standard documentation.

The resulting XML is:

<?xml version="1.0" encoding="UTF-8" ?>
<acmt:Document xmlns:acmt="urn:swift:xsd:acmt.001.001.03">
    <acmt:AcctOpngInstr>
        <acmt:AcctPties>
            <acmt:PrncplAcctPty>
                <acmt:Nmnee>
                    <acmt:Pty>
                        <acmt:Org>
                            <acmt:Nm>orgName</acmt:Nm>
                        </acmt:Org>
                    </acmt:Pty>
                </acmt:Nmnee>
            </acmt:PrncplAcctPty>
            <acmt:Admstr>
                <acmt:ClntId>clntId</acmt:ClntId>
            </acmt:Admstr>
        </acmt:AcctPties>
    </acmt:AcctOpngInstr>
</acmt:Document>

Notice the message category is used as default prefix for the document elements. And if the message contains an application header the prefix "head" is used as default prefix for the header elements.

XML Customization

The builder API is designed to be flexible and allow customization of the resulting XML. This example shows how to customize the previous result.

MxAcmt00100103 mx = new MxAcmt00100103()
    .setAcctOpngInstr(new AccountOpeningInstructionV03()
        .setAcctPties(new AccountParties6()
            .setAdmstr(new InvestmentAccountOwnershipInformation6()
                .setClntId("clntId"))
            .setPrncplAcctPty(new AccountParties1Choice()
                .setNmnee(new InvestmentAccountOwnershipInformation6()
                    .setPty(new Party14Choice()
                        .setOrg(new Organisation13().setNm("orgName"))
                    )
                )
            )
        )
    );

MxWriteConfiguration conf = new MxWriteConfiguration();
conf.useCategoryAsDocumentPrefix = false;   // do not use the category as prefix
conf.documentPrefix = null;                 // remove the default prefix
conf.indent = " ";                          // use 1 space for indentation
conf.includeXMLDeclaration = false;         // remove the default XML declaration

String mxXml = mx.message(conf);
System.out.println(mxXml);

This will result in the following XML:

<Document xmlns="urn:swift:xsd:acmt.001.001.03">
 <AcctpngInstr>
  <AcctPties>
   <PrncplAcctPty>
    <Nmnee>
     <Pty>
      <Org>
       <Nm>orgName</Nm>
      </Org>
     </Pty>
    </Nmnee>
   </PrncplAcctPty>
   <Admstr>
    <ClntId>clntId</ClntId>
   </Admstr>
  </AcctPties>
 </AcctpngInstr>
</Document>

Note that the prefix is removed (by setting it to null) and switching off the usage of the message category as prefix. Then in the example the indentation is changed to be 1 single space, the XML declaration is removed.

Envelopes

When the message model contains both the Document and the optional Application Header, the resulting XML will have the AppHdr and Document elements as siblings, at the same level in the XML hierarchy. Thus, they must be enclosed in a parent root element or envelope structure.

With the same MxWriteConfiguration object, it is possible to specify the envelope type to use. Or event to define a custom root element name such as "RequestPayload".

In the following example, the message is wrapped using a standard Business Message Envelope V2:

final MxPacs00800110 mx = new MxPacs00800110();
mx.setAppHdr(new BusinessAppHdrV02());
mx.setFIToFICstmrCdtTrf(new FIToFICustomerCreditTransferV10());
mx.getFIToFICstmrCdtTrf().setGrpHdr(new GroupHeader96());
mx.getFIToFICstmrCdtTrf().getGrpHdr().setMsgId("123");

MxWriteConfiguration conf = new MxWriteConfiguration();
conf.useCategoryAsDocumentPrefix = false;   // do not use the category as prefix
conf.envelopeType = EnvelopeType.BME_V2;    // urn:iso:std:iso:20022:tech:xsd:nvlp.001.001.02

String mxXml = mx.message(conf);
System.out.println(mxXml);

This will result in the following XML:

<?xml version="1.0" encoding="UTF-8" ?>
<env:BizMsgEnvlp xmlns="urn:iso:std:iso:20022:tech:xsd:nvlp.001.001.02" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <env:Hdr>
        <head:AppHdr xmlns:head="urn:iso:std:iso:20022:tech:xsd:head.001.001.02"></head:AppHdr>
    </env:Hdr>
    <env:Doc>
        <doc:Document xmlns:doc="urn:iso:std:iso:20022:tech:xsd:pacs.008.001.10">
            <doc:FIToFICstmrCdtTrf>
                <doc:GrpHdr>
                    <doc:MsgId>123</doc:MsgId>
                </doc:GrpHdr>
            </doc:FIToFICstmrCdtTrf>
        </doc:Document>
    </env:Doc>
</env:BizMsgEnvlp>

Variables and switches

The following table summarizes the variables and switches that can be used to customize the resulting XML with the MxWriteConfiguration object:

Variable	Description	Default Value & Usage
`String rootElement`	The root element name used when the `envelopeType` is set to `CUSTOM`. If no value is provided, the default value `"RequestPayload"` is used.	Default: `"RequestPayload"` Usage: Defines the custom root element for `CUSTOM` envelope types.
`boolean includeXMLDeclaration`	Determines whether the XML includes an XML declaration as the first line.	Default: `true` Usage: Set to `false` when the generated XML will be part of another XML wrapper.
`EscapeHandler escapeHandler`	Handler to control how element and attribute values are escaped in XML. Can be customized for specific charsets or escaping rules.	Default: `DefaultEscapeHandler` Usage: Customize escaping logic based on specific requirements.
`String headerPrefix`	Prefix for the header namespace. If set to `null`, no prefix will be applied.	Default: `"head"` Usage: Defines the prefix for header-related elements in XML.
`String documentPrefix`	Prefix for the document namespace. If set to `null`, no prefix is used. If `useCategoryAsDocumentPrefix` is `true`, this value is overridden by the category.	Default: `"doc"` Usage: Determines the prefix for document elements.
`TypeAdaptersConfiguration adapters`	Configuration for JAXB type adapters used during marshalling.	Default: `new TypeAdaptersConfiguration()` Usage: Enables customization of type adapters.
`JAXBContext context`	Optional instance of `JAXBContext`. If `null`, a new instance will be created during XML marshalling.	Default: `null` Usage: Allows preconfigured `JAXBContext` for marshalling operations.
`String indent`	Indentation string used for formatting XML output. If `null`, defaults to four spaces.	Default: `" "` (4 spaces) Usage: Defines the formatting style for indented XML.
`EnvelopeType envelopeType`	Specifies the envelope type to use during XML serialization. Custom envelope types use parameters like `rootElement`.	Default: `EnvelopeType.CUSTOM` Usage: Selects predefined or custom envelope structures.
`boolean useCategoryAsDocumentPrefix`	If `true`, the category code (e.g., "camt", "pacs") is used as the prefix for the `Document` element. Has no effect if `documentPrefix` is `null`.	Default: `true` Usage: Controls whether the category is used as a prefix for document elements.

Refer to the MxWriteConfiguration javadoc to review all the available customization options in detail.