Module org.shredzone.acme4j
Package org.shredzone.acme4j

Class Session

java.lang.Object
org.shredzone.acme4j.Session
public class Session extends Object
A Session tracks the entire communication with a CA.

To create a session instance, use its constructor. It requires the URI of the ACME server to connect to. This can be the location of the CA's directory (via http or https protocol), or a special URI (via acme protocol). See the documentation about valid URIs.

Starting with version 4.0.0, a session instance can be shared between multiple threads. A session won't perform parallel HTTP connections. For high-load scenarios, it is recommended to use multiple sessions.

  • Field Details

  • Constructor Details

    • Session

      public Session(String serverUri)
      Creates a new Session.
      Parameters:
      serverUri - URI string of the ACME server to connect to. This is either the location of the CA's ACME directory (using http or https protocol), or a special URI (using the acme protocol).
      Throws:
      IllegalArgumentException - if no ACME provider was found for the server URI.

    • Session

      public Session(URI serverUri)
      Creates a new Session.
      Parameters:
      serverUri - URI of the ACME server to connect to. This is either the location of the CA's ACME directory (using http or https protocol), or a special URI (using the acme protocol).
      Throws:
      IllegalArgumentException - if no ACME provider was found for the server URI.

    • Session

      public Session(URI serverUri, AcmeProvider provider)
      Creates a new Session using the given AcmeProvider.

      This constructor is only to be used for testing purposes.

      Parameters:
      serverUri - URI of the ACME server
      provider - AcmeProvider to be used
      Since:
      2.8

  • Method Details

    • login

      public Login login(URL accountLocation, KeyPair accountKeyPair)
      Logs into an existing account.
      Parameters:
      accountLocation - Location URL of the account
      accountKeyPair - Account KeyPair
      Returns:
      Login to this account

    • getServerUri

      public URI getServerUri()
      Gets the ACME server URI of this session.

    • lockNonce

      public NonceHolder lockNonce()
      Locks the Session for the current thread, and returns a NonceHolder.

      The current thread can lock the nonce multiple times. Other threads have to wait until the current thread unlocks the nonce.

      Since:
      4.0.0

    • getLocale

      @Nullable public Locale getLocale()
      Gets the current locale of this session, or null if no special language is selected.

    • setLocale

      public void setLocale(@Nullable Locale locale)
      Sets the locale used in this session. The locale is passed to the server as Accept-Language header. The server may respond with localized messages. The default is the system's language. If set to null, any language will be accepted.

    • getLanguageHeader

      public String getLanguageHeader()
      Gets an Accept-Language header value that matches the current locale. This method is mainly for internal use.
      Since:
      3.0.0

    • networkSettings

      public NetworkSettings networkSettings()
      Returns the current NetworkSettings.
      Returns:
      NetworkSettings
      Since:
      2.8

    • provider

      public AcmeProvider provider()
      Returns the AcmeProvider that is used for this session.
      Returns:
      AcmeProvider

    • connect

      public Connection connect()
      Returns a new Connection to the ACME server.
      Returns:
      Connection

    • getHttpClient

      public HttpClient getHttpClient()
      Returns the shared HttpClient instance for this session. The instance is created lazily on first access and then cached for reuse. This allows multiple connections to share the same HTTP client, improving resource utilization and connection pooling.
      Returns:
      Shared HttpClient instance
      Since:
      4.0.0

    • resourceUrl

      public URL resourceUrl(Resource resource) throws AcmeException
      Gets the URL of the given Resource. This may involve connecting to the server and fetching the directory. The result is cached.
      Parameters:
      resource - Resource to get the URL of
      Returns:
      URL of the resource
      Throws:
      AcmeException - if the server does not offer the Resource

    • resourceUrlOptional

      public Optional<URL> resourceUrlOptional(Resource resource) throws AcmeException
      Gets the URL of the given Resource. This may involve connecting to the server and fetching the directory. The result is cached.
      Parameters:
      resource - Resource to get the URL of
      Returns:
      URL of the resource, or empty if the resource is not available.
      Throws:
      AcmeException
      Since:
      3.0.0

    • getMetadata

      public Metadata getMetadata() throws AcmeException
      Gets the metadata of the provider's directory. This may involve connecting to the server and fetching the directory. The result is cached.
      Returns:
      Metadata. May contain no data, but is never null.
      Throws:
      AcmeException

    • getDirectoryLastModified

      @Nullable public ZonedDateTime getDirectoryLastModified()
      Returns the date when the directory has been modified the last time.
      Returns:
      The last modification date of the directory, or null if unknown (directory has not been read yet or did not provide this information).
      Since:
      2.10

    • setDirectoryLastModified

      public void setDirectoryLastModified(@Nullable ZonedDateTime directoryLastModified)
      Sets the date when the directory has been modified the last time. Should only be invoked by AcmeProvider implementations.
      Parameters:
      directoryLastModified - The last modification date of the directory, or null if unknown (directory has not been read yet or did not provide this information).
      Since:
      2.10

    • getDirectoryExpires

      @Nullable public ZonedDateTime getDirectoryExpires()
      Returns the date when the current directory records will expire. A fresh copy of the directory will be fetched automatically after that instant.
      Returns:
      The expiration date, or null if the server did not provide this information.
      Since:
      2.10

    • setDirectoryExpires

      public void setDirectoryExpires(@Nullable ZonedDateTime directoryExpires)
      Sets the date when the current directory will expire. Should only be invoked by AcmeProvider implementations.
      Parameters:
      directoryExpires - Expiration date, or null if the server did not provide this information.
      Since:
      2.10

    • hasDirectory

      public boolean hasDirectory()
      Returns true if a copy of the directory is present in a local cache. It is not evaluated if the cached copy has expired though.
      Returns:
      true if a directory is available.
      Since:
      2.10

    • purgeDirectoryCache

      public void purgeDirectoryCache()
      Purges the directory cache. Makes sure that a fresh copy of the directory will be read from the CA on the next time the directory is accessed.
      Since:
      3.0.0

    • finalize

      protected final void finalize()
      Overrides:
      finalize in class Object