Class ConnectionListener


  • public class ConnectionListener
    extends Object
    As a server, Openfire accepts connection requests from other network entities. The exact functionality is subject to configuration details (eg: TCP port on which connections are accepted, TLS policy that is applied, etc). An instance of this class is used to manage this configuration for one type of connection (on one TCP port), and is responsible for managing the lifecycle of the entity that implements the acceptance of new connections.
    Author:
    Guus der Kinderen, guus.der.kinderen@gmail.com
    • Constructor Detail

      • ConnectionListener

        public ConnectionListener​(ConnectionType type,
                                  String tcpPortPropertyName,
                                  int defaultPort,
                                  String isEnabledPropertyName,
                                  String maxPoolSizePropertyName,
                                  String maxReadBufferPropertyName,
                                  String tlsPolicyPropertyName,
                                  String clientAuthPolicyPropertyName,
                                  InetAddress bindAddress,
                                  CertificateStoreConfiguration identityStoreConfiguration,
                                  CertificateStoreConfiguration trustStoreConfiguration,
                                  String compressionPolicyPropertyName)
        Instantiates a new connection listener.
        Parameters:
        type - the connection type
        tcpPortPropertyName - the name of the system property holding the TCP port
        defaultPort - the default port number if the property is not set
        isEnabledPropertyName - Property name (of a boolean) that toggles availability. Null to indicate that this listener is 'always on'
        maxPoolSizePropertyName - Property name (of an int) that defines maximum IO processing threads. Null causes an unconfigurable default amount to be used.
        maxReadBufferPropertyName - Property name (of an int) that defines maximum amount (in bytes) of IO data can be cached, pending processing. Null to indicate boundless caches.
        tlsPolicyPropertyName - Property name (of a string) that defines the applicable TLS Policy. Or, the value Connection.TLSPolicy to indicate unconfigurable TLS Policy. Cannot be null.
        clientAuthPolicyPropertyName - Property name (of an string) that defines maximum IO processing threads. Null causes a unconfigurabel value of 'wanted' to be used.
        bindAddress - the address to bind to
        identityStoreConfiguration - the certificates the server identify as
        trustStoreConfiguration - the certificates the server trusts
        compressionPolicyPropertyName - the name of the system property indicating if compression is enabled or not
    • Method Detail

      • isEnabled

        public boolean isEnabled()
        Return if the configuration allows this listener to be enabled (but does not verify that the listener is indeed active).
        Returns:
        true if configuration allows this listener to be enabled, otherwise false.
      • enable

        public void enable​(boolean enable)
        Activates or deactivates the listener, and changes the configuration accordingly. This configuration change is persisted. An invocation of this method has no effect if the listener is already in the provided state.
        Parameters:
        enable - to enable or disable the listener
      • start

        public void start()
        Attempts to start the connection acceptor, creating a new instance when needed. An invocation of this method does not change the configuration for this connection. As a result, an acceptor will not be started when the listener is not enabled (in such cases, an invocation of this method has no effect). In order to start this listener and persist this as the desired state for this connection, use #enable(true). This method should not be called when an acceptor has already been started (instead, restart() should be used to explicitly define the need to stop a previous connection). The current implementation of this method will stop a pre-existing acceptor, but only when it is currently not serving connections. When the acceptor is not idle, this method has no effect. This behavior might change in the future.
      • generateConnectionConfiguration

        public ConnectionConfiguration generateConnectionConfiguration()
        Generates an immutable ConnectionConfiguration based on the current state.
        Returns:
        an immutable configuration, never null.
      • stop

        public void stop()
        Attempts to stop the connection acceptor. If the connection acceptor has not been started, an invocation of this method has no effect. An invocation of this method does not change the configuration for this connection. As a result, the acceptor for this connection can be restarted when this ConnectionListener instance is replaced. In order to stop this listener (and persist this as the desired state for this connection, use #enable(false).
      • restart

        public void restart()
        Starts or restarts this instance (typically used to put into effect a configuration change). A connection that was started, but is disabled by configuration will be stopped but not restarted by an invocation of this method.
      • reloadConfiguration

        public void reloadConfiguration()
        Reconfigures the acceptor without breaking existing connections. Note that not all configuration changes can be applied. These changes will be applied after a restart.
      • getBindAddress

        public InetAddress getBindAddress()
        Returns the network address on which connections are accepted when this listener is enabled. This method can return null, which indicates that connections are accepted on any local address (typically 0.0.0.0 or ::0).
        Returns:
        A network address or null.
      • getType

        public ConnectionType getType()
        Returns the type of connection that is accepted by this listener.
        Returns:
        A connection type (never null).
      • getPort

        public int getPort()
        The TCP port number on which connections will be accepted when this listener is enabled.
        Returns:
        A port number.
      • setPort

        public void setPort​(int port)
        Changes the TCP port on which connections are accepted, This configuration change is persisted. If the listener is currently enabled, this configuration change will be applied immediately (which will cause a restart of the underlying connection acceptor). An invocation of this method has no effect if the new port value is equal to the existing value.
        Parameters:
        port - A port number.
      • getTLSPolicy

        public Connection.TLSPolicy getTLSPolicy()
        Returns whether TLS is mandatory, optional, disabled or mandatory immediately for new connections. When TLS is mandatory connections are required to be encrypted or otherwise will be closed. When TLS is disabled connections are not allowed to be (or become) encrypted. In this case, connections will be closed when encryption is attempted.
        Returns:
        An encryption policy, never null.
      • setTLSPolicy

        public void setTLSPolicy​(Connection.TLSPolicy policy)
        Sets whether TLS is mandatory, optional, disabled or mandatory immediately for new connections. When TLS is mandatory connections are required to be encrypted or otherwise will be closed. This configuration change is persisted. If the listener is currently enabled, this configuration change will be applied immediately (which will cause a restart of the underlying connection acceptor). When TLS is disabled connections are not allowed to be (or become) encrypted. In this case, connections will be closed when encryption is attempted. This method disallows changing the policy from or into Direct TLS mode. Such a change is logged but otherwise ignored. An invocation of this method has no effect if the new policy value is equal to the existing value.
        Parameters:
        policy - an encryption policy (not null).
      • getCompressionPolicy

        public Connection.CompressionPolicy getCompressionPolicy()
        Returns whether compression is optional or disabled for new connections.
        Returns:
        A compression policy (never null)
      • setCompressionPolicy

        public void setCompressionPolicy​(Connection.CompressionPolicy policy)
        Sets whether compression is optional or disabled for new connections. This configuration change is persisted. If the listener is currently enabled, this configuration change will be applied immediately (which will cause a restart of the underlying connection acceptor). An invocation of this method has no effect if the new policy value is equal to the existing value.
        Parameters:
        policy - a compression policy (not null).
      • getIdentityStoreConfiguration

        public CertificateStoreConfiguration getIdentityStoreConfiguration()
        Returns the configuration for the identity store that identifies this instance of Openfire to the peer on connections created by this listener.
        Returns:
        The configuration of the identity store (not null)
      • setIdentityStoreConfiguration

        public void setIdentityStoreConfiguration​(CertificateStoreConfiguration configuration)
        Replaces the configuration for the identity store that identifies this instance of Openfire to the peer on connections created by this listener. If the listener is currently enabled, this configuration change will be applied immediately (which will cause a restart of the underlying connection acceptor).
        Parameters:
        configuration - The identity store configuration (not null)
      • getTrustStoreConfiguration

        public CertificateStoreConfiguration getTrustStoreConfiguration()
        Returns the configuration for the trust store that is used to identify/trust peers on connections created by this listener.
        Returns:
        The configuration of the identity store (not null)
      • setTrustStoreConfiguration

        public void setTrustStoreConfiguration​(CertificateStoreConfiguration configuration)
        Replaces the configuration for the trust store that is used to identify/trust peers on connections created by this listener. If the listener is currently enabled, this configuration change will be applied immediately (which will cause a restart of the underlying connection acceptor).
        Parameters:
        configuration - The configuration of the identity store (not null)
      • acceptSelfSignedCertificates

        public boolean acceptSelfSignedCertificates()
        A boolean that indicates if self-signed peer certificates can be used to establish an encrypted connection.
        Returns:
        true when self-signed certificates are accepted, otherwise false.
      • setAcceptSelfSignedCertificates

        public void setAcceptSelfSignedCertificates​(boolean accept)
        Configuresif self-signed peer certificates can be used to establish an encrypted connection.
        Parameters:
        accept - true when self-signed certificates are accepted, otherwise false.
      • verifyCertificateValidity

        public boolean verifyCertificateValidity()
        A boolean that indicates if the current validity of certificates (based on their 'notBefore' and 'notAfter' property values) is used when they are used to establish an encrypted connection.
        Returns:
        true when certificates are required to be valid to establish a encrypted connection, otherwise false.
      • setVerifyCertificateValidity

        public void setVerifyCertificateValidity​(boolean verify)
        Configures if the current validity of certificates (based on their 'notBefore' and 'notAfter' property values) is used when they are used to establish an encrypted connection.
        Parameters:
        verify - true when certificates are required to be valid to establish a encrypted connection, otherwise false.
      • getEncryptionProtocols

        public Set<String> getEncryptionProtocols()
        A collection of protocol names that can be used for encryption of connections. When non-empty, the list is intended to specify those protocols (from a larger collection of implementation- supported protocols) that can be used to establish encryption. The order over which values are iterated in the result is equal to the order of values in the comma-separated configuration string. This can, but is not guaranteed to, indicate preference.
        Returns:
        An (ordered) set of protocols, never null but possibly empty.
      • getEncryptionProtocolsCommaSeparated

        protected String getEncryptionProtocolsCommaSeparated()
      • setEncryptionProtocols

        public void setEncryptionProtocols​(Set<String> protocols)
        Defines the collection of protocols (by name) that can be used for encryption of connections. When non-empty, the list is intended to specify those protocols (from a larger collection of implementation- supported protocols) that can be used to establish encryption. An empty list will cause an implementation default to be used. The order over which values are presented can, but is not guaranteed to, indicate preference.
        Parameters:
        protocols - An (ordered) set of protocol names, can be null.
      • setEncryptionProtocols

        public void setEncryptionProtocols​(String[] protocols)
        Defines the collection of protocols (by name) that can be used for encryption of connections. When non-empty, the list is intended to specify those protocols (from a larger collection of implementation- supported protocols) that can be used to establish encryption. An empty list will cause an implementation default to be used. The order over which values are presented can, but is not guaranteed to, indicate preference.
        Parameters:
        protocols - An array of protocol names, can be null.
      • getEncryptionCipherSuites

        public Set<String> getEncryptionCipherSuites()
        A collection of cipher suite names that can be used for encryption of connections. When non-empty, the list is intended to specify those cipher suites (from a larger collection of implementation- supported cipher suites) that can be used to establish encryption. The order over which values are iterated in the result is equal to the order of values in the comma-separated configuration string. This can, but is not guaranteed to, indicate preference.
        Returns:
        An (ordered) set of cipher suite names, never null but possibly empty.
      • getEncryptionCipherSuitesCommaSeparated

        protected String getEncryptionCipherSuitesCommaSeparated()
      • setEncryptionCipherSuites

        public void setEncryptionCipherSuites​(Set<String> cipherSuites)
        Defines the collection of cipher suite (by name) that can be used for encryption of connections. When non-empty, the list is intended to specify those cipher suites (from a larger collection of implementation- supported cipher suites) that can be used to establish encryption. An empty list will cause an implementation default to be used. The order over which values are presented can, but is not guaranteed to, indicate preference.
        Parameters:
        cipherSuites - An (ordered) set of cipher suite names, can be null.
      • setEncryptionCipherSuites

        public void setEncryptionCipherSuites​(String[] cipherSuites)
        Defines the collection of cipher suite (by name) that can be used for encryption of connections. When non-empty, the list is intended to specify those cipher suites (from a larger collection of implementation- supported cipher suites) that can be used to establish encryption. An empty list will cause an implementation default to be used. The order over which values are presented can, but is not guaranteed to, indicate preference.
        Parameters:
        cipherSuites - An array of cipher suite names, can be null.
      • setStrictCertificateValidation

        public void setStrictCertificateValidation​(boolean strictCertificateValidation)
        Defines whether a connection should be aborted if certificate validation fails. When set to true Openfire strictly follows RFC 6120, section 13.7.2.
        Parameters:
        strictCertificateValidation - true to abort connections if certificate validation fails, otherwise false
      • add

        public void add​(ConnectionListener.SocketAcceptorEventListener eventListener)
        Adds an event listener that is invoked when the SocketAcceptor managed by this instance is being stopped or started.
        Parameters:
        eventListener - The event listener that is to be notified.