ConnectionAcceptor.java 2.36 KB
Newer Older
1 2 3
package org.jivesoftware.openfire.spi;

/**
4
 * ConnectionAcceptors are responsible for accepting new (typically socket) connections from peers.
5
 *
6
 * The configuration (but not the state) of an instance is intended to be immutable. When configuration changes are
7 8 9 10
 * needed, an instance needs to be replaced by a new instance.
 *
 * @author Guus der Kinderen, guus.der.kinderen@gmail.com
 */
11
public abstract class ConnectionAcceptor
12
{
13
    protected final ConnectionConfiguration configuration;
14 15

    /**
16 17 18 19
     * Constructs a new instance which will accept new connections based on the provided configuration.
     *
     * The provided configuration is expected to be immutable. ConnectionAcceptor instances are not expected to handle
     * changes in configuration. When such changes are to be applied, an instance is expected to be replaced.
20
     *
21 22 23
     * Newly instantiated ConnectionAcceptors will not accept any connections before {@link #start()} is invoked.
     *
     * @param configuration The configuration for connections to be accepted (cannot be null).
24 25 26
     */
    public ConnectionAcceptor( ConnectionConfiguration configuration )
    {
27
        if (configuration == null)
28
        {
29
            throw new IllegalArgumentException( "Argument 'configuration' cannot be null" );
30
        }
31
        this.configuration = configuration;
32 33 34
    }

    /**
35 36 37 38
     * Makes the instance start accepting connections.
     *
     * An invocation of this method on an instance that is already started should have no effect (to the extend that the
     * instance should continue to accept connections without interruption or configuration changes).
39
     */
40
    abstract void start();
41 42

    /**
43 44 45 46 47 48
     * Halts connection acceptation and gracefully releases resources.
     *
     * An invocation of this method on an instance that was not accepting connections should have no effect.
     *
     * Instances of this class do not support configuration changes (see class documentation). As a result, there is no
     * requirement that an instance that is stopped after it was running can successfully be restarted.
49
     */
50
    abstract void stop();
51 52 53 54 55 56

    /**
     * Determines if this instance is currently in a state where it is actively serving connections.
     *
     * @return false when this instance is started and is currently being used to serve connections (otherwise true)
     */
57
    abstract boolean isIdle();
58
}