Skip to content

Migrations

Jump to bottom
Philip Helger edited this page Dec 5, 2024 · 22 revisions

This page contains everything necessary related to migrating phase4 versions

Upgrade from 2.x to 3.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.

My personal Coding Styleguide | It is appreciated if you star the GitHub project if you like it.

Logo

Clone this wiki locally