Runtime Considerations - phax/phase4 GitHub Wiki

phase4 is a Java library

Java versions

It is developed on Windows but works without (known) problems on Windows, Linux, Mac and AWS. For development I use the Eclipse Temurin Java version.

The minimum Java version is 17 but it is recommended to use at least Java 21 for performance reasons. See https://github.com/phax/phase4/discussions/132#discussioncomment-11224517 for the details on why Java 21 is recommended.

Proxy setup

The inbound proxy connection is usually best handled by a Reverse Proxy.

The outbound proxy connection is configured per HttpClientSettings instance. phase4 deliberately applies no proxy implicitly: the HttpClientSettings instance is owned by the calling code, and the different outbound channels may need different proxy servers - or none at all.

Consider the following actions when setting the proxy server:

• Sending AS4 messages
• Performing SMP lookups
• Download CRL (Certificate Revocation Lists)

Configuration properties

The class HttpClientSettingsConfig of ph-httpclient reads the following configuration properties. They are the same ones that the Peppol SMP client and the Peppol Directory client use.

Property	Fallback names	Meaning
http.proxy.host	http.proxyHost, http.proxy.address	Proxy host name
http.proxy.port	http.proxyPort	Proxy port
http.proxy.username	http.proxyUsername	Proxy user name
http.proxy.password	http.proxyPassword	Proxy password
http.proxy.nonProxyHosts	http.nonProxyHosts, http.proxy.non-proxy	Pipe separated list of hosts to be excluded, e.g. localhost|127.0.0.1
http.proxy.enabled	-	Explicit kill-switch - only an explicit false value disables the proxy

A non-empty http.proxy.host together with an http.proxy.port > 0 is sufficient to activate the proxy. http.proxy.enabled=true is not required - needing it was a regression in v4.5.0 that was fixed in v4.5.1.

Applying the configuration properties

final HttpClientSettings aHCS = new HttpClientSettings ();

// All supported settings: proxy, timeouts, retries, TLS, revocation checking, ...
HttpClientSettingsConfig.assignConfigValues (aHCS, AS4Configuration.getConfig (), "");

// ... or only the proxy part
final HttpClientSettingsConfig.HttpClientConfig aHCC = HttpClientSettingsConfig.HttpClientConfig.create (AS4Configuration.getConfig (),
                                                                                                        "");
if (aHCC != null)
  HttpClientSettingsConfig.assignConfigValuesForProxy (aHCS.getGeneralProxy (), aHCC);

See the method APConfig.applyHttpProxySettings(...) and its usages in Phase4PeppolWebAppListener of the phase4-peppol-server-webapp submodule for a complete example that covers AS4 sending, SMP lookup and CRL download.

Setting a proxy programmatically

HttpClientSettings differentiates between a general proxy and separate proxies for http and https target URLs:

aHCS.getGeneralProxy ().setProxyHost (new HttpHost ("proxy.example.org", 8080));
aHCS.getGeneralProxy ().setProxyCredentials (new UsernamePasswordCredentials ("user", "password".toCharArray ()));
aHCS.getGeneralProxy ().setNonProxyHostsFromPipeString ("localhost|127.0.0.1");

Use getHttpProxy() or getHttpsProxy() instead of getGeneralProxy(), to limit the settings to a single protocol.