Migrations

This page contains everything necessary related to migrating phase4 versions

Upgrade from 4.x to 5.x (in development)

• The usage of the configuration file phase4.properties and private-phase4.properties was removed. Use application.properties or private-application.properties, environment variables or system properties instead.

Upgrade from 4.1.x to 4.2.x (in development)

• The SPI interface for receiving was slightly changed for error handling:
  • Instead of ICommonsList <Ebms3Error> the error list is now of type AS4ErrorList
  • Each individual error is now of type AS4Error instead of Ebms3Error

Upgrade from 4.0.x to 4.1.x (current)

• The @NonNull and @Nullable annotations are now taken from JSpecify and no longer from Jakarta-Annotations

Upgrade from 3.x to 4.0.x

• It requires at least Java 17 for building and execution
• It was updated to the JakartaEE 10 specifications
  • Uses Servlet Specification 6.0.x
• The minimum requirements for application servers are
  • Tomcat 10.1.x
  • Jetty 12.x

Upgrade from 3.1.x to 3.2.x

• Make sure that all dependent libraries are updated to the required versions (see the release for details)
• All interfaces that declared their methods are throwing Phase4PeppolException are now throwing Phase4Exception instead
• [Peppol] The support for Peppol Policy for use of Identifiers v4.2.0 was dropped

Upgrade from 3.0.x to 3.1.x

• Make sure that all dependent libraries are updated to the required versions (see the release for details)
• Class PeppolCAChecker was replaced with class TrustedCAChecker
• The predefined trusted CAs of Peppol were moved from PeppolCertificateChecker to PeppolTrustedCA
• Enum EPeppolCertificateCheckResult was replaced with ECertificateCheckResult
• Some methods were moved from class PeppolCertificateHelper to class CertificateHelper
• [DBNAlliance] Moved class Phase4DBNAllianceHttpClientSettings to module phase4-profile-dbnalliance
• The method AbstractAS4MessageBuilder.finishFields (and in all derived classes) now have an AS4ResourceHelper parameter

Upgrade from 3.0.x to 3.0.4 or later

• Due to a change to peppol-commons v10 some classes were moved. See https://github.com/phax/peppol-commons/releases/tag/peppol-commons-parent-pom-10.0.0 for details

Upgrade from 2.x to 3.0.x

• The phase4-profile-bpc submodule was removed in favour of phase4-profile-dbnalliance

• The phase4-spring-boot-demo submodule was removed in favour of https://github.com/phax/phase4-peppol-standalone

• All deprecated methods marked for removal have been removed

• Configuration related changes

  • The configuration files private-crypto.properties and crypto.properties are deprecated. Please move the properties to application.properties, environment variables or Java system properties instead.
  • The configuration property phase4.profile was renamed to phase4.default.profile - the old property is still evaluated as a secondary option
  • In case you are using AS4CryptoFactoryProperties and
    1. read the configuration from a file: use AS4CryptoFactoryConfiguration instead (as a drop-in replacement)
    2. provide the properties manually: use AS4CryptoFactoryInMemoryKeyStore instead (and see below)

• Here are the main coding related changes

  • Renamed packages
    • Renamed package com.helger.phase4.error to com.helger.phase4.model.error
    • Renamed package com.helger.phase4.http to com.helger.phase4.messaging.http
    • Renamed package com.helger.phase4.messaging.domain to com.helger.phase4.model.message
  • Moved classes
    • Moved classes from com.helger.phase4.servlet to com.helger.phase4.incoming
    • Moved classes from com.helger.phase4.servlet.mgr to com.helger.phase4.incoming.mgr
    • Moved classes from com.helger.phase4.servlet.soap to com.helger.phase4.incoming.soap
    • Moved classes from com.helger.phase4.servlet.spi to com.helger.phase4.incoming.spi
    • Moved class AbstractAS4RawResponseConsumer to com.helger.phase4.sender
    • Moved class AS4IncomingDumperFileBased.IFileProvider to IAS4IncomingDumperFileProvider
    • Moved class AS4OutgoingDumperFileBased.IFileProvider to IAS4OutgoingDumperFileProvider
    • Moved class AS4RequestHandler.ISoapProcessingFinalizedCallback to IAS4SoapProcessingFinalizedCallback
    • Moved class ESoapVersion to com.helger.phase4.model`
    • Moved classes IAS4IncomingSecurityConfiguration and AS4IncomingSecurityConfiguration to com.helger.phase4.incoming.crypto
    • Moved class IAS4IncomingMessageMetadata to com.helger.phase4.incoming
    • Moved class IAS4RawResponseConsumer to com.helger.phase4.sender
    • Moved class IAS4SignalMessageConsumer to com.helger.phase4.incoming
    • Moved class IAS4UserMessageConsumer to com.helger.phase4.incoming
  • Renamed classes
    • Renamed class AbstractAS4UserMessageBuilder.ESimpleUserMessageSendResult to EAS4UserMessageSendResult
    • Renamed class AS4DuplicateManager to AS4DuplicateManagerXML
    • Renamed class AS4MessageState to AS4IncomingMessageState
    • Renamed class AS4MessagingHelper to AS4IncomingHelper
      • And moved to com.helger.phase4.incoming
    • Renamed class AS4ServletMessageProcessorManager to AS4IncomingMessageProcessorManager
    • Renamed class AS4ServletPullRequestProcessorManager to AS4IncomingPullRequestProcessorManager
    • Renamed class AS4SingleSOAPHeader to AS4SingleSoapHeader (casing only)
    • Renamed class AS4XServletHandler.IHandlerCustomizer to IAS4ServletRequestHandlerCustomizer
      • Made method customizeAfterHandling non-default
    • Renamed class DefaultPModeResolver to AS4DefaultPModeResolver
    • Renamed SPI class IAS4ServletMessageProcessorSPI to IAS4IncomingMessageProcessorSPI
      • Was also moved to a different package - see above
      • Made method IAS4IncomingMessageProcessorSPI non-default
    • Renamed SPI class IAS4ServletPullRequestProcessorSPI to IAS4IncomingPullRequestProcessorSPI
      • Was also moved to a different package - see above
    • Renamed class IAS4MessageState to IAS4IncomingMessageState
    • Renamed class IPModeResolver to IAS4PModeResolver
    • Renamed class ISOAPHeaderElementProcessor to ISoapHeaderElementProcessor (casing only)
    • Renamed class MimeMessageCreator to AS4MimeMessageHelper
    • Renamed class MPCManager to MPCManagerXML
    • Renamed class Phase4PeppolServletConfiguration to Phase4PeppolDefaultReceiverConfiguration
    • Renamed class Phase4PeppolReceiverCheckData to Phase4PeppolReceiverConfiguration
    • Renamed class Phase4PeppolSender.Builder to Phase4PeppolSender.PeppolUserMessageBuilder
    • Renamed class Phase4PeppolSender.SBDHBuilder to Phase4PeppolSender.PeppolUserMessageSBDHBuilder
    • Renamed class PModeManager to PModeManagerXML
    • Renamed class SoapMimeMultipart to AS4SoapMimeMultipart
    • Renamed class SOAPHeaderElementProcessorExtractEbms3Messaging to SoapHeaderElementProcessorExtractEbms3Messaging (casing only)
    • Renamed class SOAPHeaderElementProcessorRegistry to SoapHeaderElementProcessorRegistry (casing only)
    • Renamed class SOAPHeaderElementProcessorWSS4J to SoapHeaderElementProcessorWSS4J (casing only)
  • Removed classes
    • Removed class Phase4PeppolClientException
  • Altered classes
    • Added template parameter to class AbstractAS4IncomingDumperWithHeaders
    • Added template parameter to class AbstractAS4OutgoingDumperWithHeaders
    • Removed constant DefaultPModeResolver.DEFAULT_PMODE_RESOLVER in favour of new instances with an AS4 profile ID
  • Moved methods
    • Moved methods AS4ReceiptMessage.getAllDSigReferenceNodes and AS4ReceiptMessage.getAllDSigReferences to class MessageHelperMethods
    • Moved all setters from AS4XServletHandler to AS4RequestHandler
    • Moved method IAS4ResponseAbstraction.wrap to AS4XServletHandler.createResponseAbstraction
    • Moved methods MessageHelperMethods.forEachHeaderAndRemoveAfterwards and MessageHelperMethods.getAndRemoveAllHeaders to class AS4MimeMessageHelper
  • Renamed methods
    • Renamed methods AbstractAS4Client.(get|set)AS4CryptoFactory* to (get|set)CryptoFactory...
    • Renamed methods AS4ClientBuiltMessage.getCustomHeaders to getAllCustomHttpHeaders
    • Renamed method AS4ClientErrorMessage.isReceiptShouldBeSigned to isErrorShouldBeSigned
    • Renamed method AS4ClientSentMessage.getResponse to getResponseContent
    • Renamed method AS4ClientSentMessage.hasResponse to hasResponseContent
    • Renamed method AS4Configuration.getAS4ProfileIDto getDefaultAS4ProfileID
    • Renamed method AS4ProfileSelector.getAS4ProfileID to getDefaultAS4ProfileID
    • Renamed methods AS4ProfileSelector.(get|set)CustomAS4ProfileID to (get|set)CustomDefaultAS4ProfileID
    • Renamed methods AS4XServletHandler.(get|set)HandlerCustomizer to (get|set)RequestHandlerCustomizer
    • Renamed method IAS4IncomingDumperFileProvider.getFilename to getDefaultDirectoryAndFilename
    • Renamed method IAS4OutgoingDumperFileProvider.getFilename to getDefaultDirectoryAndFilename
    • Renamed method IPModeResolver.getPModeOfID to findPMode
  • Altered methods
    • Extended method AS4DumpReader.decryptAS4In to include an AS4 profile ID parameter
    • Made method IAS4CryptoFactory.getKeyPasswordPerAlias(String) non-default
    • Made method IAS4IncomingDumper.onEndRequest non-default and added optional "caughtException" parameter
    • Made method IAS4OutgoingDumper.onEndRequest non-default and added optional "caughtException" parameter
    • Extended method IAS4ProfileValidator.validatePMode with an additional parameter to differentiate UserMessage and SignalMessage
  • Removed methods
    • Removed method IAS4ProfileManager.hasDefaultProfile
    • Removed method IAS4ProfileManager.getDefaultProfileOrNull
    • Removed method IAS4ProfileManager.getDefaultProfile
    • Removed method IAS4ProfileManager.setDefaultProfileID
    • Removed method IAS4ProfileRegistrar.setDefaultProfile

• The most common form of CryptoFactory creation got reworked.

Instead of

final AS4CryptoProperties aCP = new AS4CryptoProperties ().setKeyStoreType (EKeyStoreType.PKCS12)
                                                          .setKeyStorePath ("path.p12")
                                                          .setKeyStorePassword ("pw")
                                                          .setKeyAlias ("cert")
                                                          .setKeyPassword ("pw")
                                                          .setTrustStoreType (EKeyStoreType.JKS)
                                                          .setTrustStorePath ("truststore/complete-truststore.jks")
                                                          .setTrustStorePassword ("peppol");
new AS4CryptoFactoryProperties (aCP);

use this code now:

new AS4CryptoFactoryInMemoryKeyStore (KeyStoreAndKeyDescriptor.builder ()
                                                              .type (EKeyStoreType.PKCS12)
                                                              .path ("path.p12")
                                                              .password ("pw")
                                                              .keyAlias ("cert")
                                                              .keyPassword ("pw")
                                                              .build (),
                                      TrustStoreDescriptor.builder ()
                                                          .type (EKeyStoreType.JKS)
                                                          .path ("truststore/complete-truststore.jks")
                                                          .password ("peppol")
                                                          .build ());

In case of problems of PMode resolution, most likely you are missing a default AS4 profiles. Use the following code snippet in your global initialization to pick the correct AS4 profile.

// Example on how to globally use the AS4 Peppol profile
AS4ProfileSelector.setCustomDefaultAS4ProfileID (AS4PeppolProfileRegistarSPI.AS4_PROFILE_ID);

Upgrade from 1.x to 2.x

The major change in v2.x is the new software baseline.

• It requires at least Java 11 for building and execution
• It was updated to the JakartaEE 9 specifications
  • Uses Servlet Specification 5.0.x
  • All the namespaces javax.servlet where changed to jakarta.servlet
  • Uses Eclipse Angus instead of Jakarta Mail
• The minimum requirements for application servers are
  • Tomcat 10.0.x or Tomcat 10.1.x
  • Jetty 11.x

All other potentially breaking changes are listed in News and noteworthy.