Package org.refcodes.net

Interface PortManager

All Known Implementing Classes:

PortManagerImpl, PortManagerSingleton

public interface PortManager

When implemented as singleton, then resources battling for dynamically assigned ports my use this functionality to get and block a port until it is freed again. The implementation must be thread safe! It is up to the skills of the implementing programmer on how non-blocking the thread safe implementation looks like!

Method Summary

Modifier and Type	Method	Description
Integer	bindAnyPort()	Any free port in the range as defined by PortRange.DYNAMIC_PORTS is bound (reserved) and returned.
default Integer	bindNextPort(int aBeginPortIndex)	The first free port in the range of the given Port-Number and the PortRange.DYNAMIC_PORTS max port number (as of PortRange.getMaxValue()) bound (reserved) and returned.
Integer	bindNextPort(int aBeginPortIndex, int aEndPortIndex)	The first free port in the range of the given begin Port-Number index and the given end Port-Number index is bound (reserved) and returned.
default Integer	bindNextPort(PortRange aPortRange)	The first free port in the range of the given begin Port-Number index and the given end Port-Number index is bound (reserved) and returned.
Integer	bindPort(int aPortNumber)	The port is bound and returned.
default boolean	isPortAvaialble(int aPortNumber)	Tests whether there is already some Server-Socket technically bound to the given port.
boolean	isPortBound(int aPortNumber)	Determines whether the given Port-Number is already in use.
boolean	unbindPort(Integer aPortNumber)	Unbinds a port for the given Port-Number using the Integer as handle for unbinding.

Method Detail

isPortBound

boolean isPortBound(int aPortNumber)

Determines whether the given Port-Number is already in use. This is achieved by testing whether another resource has reserved the port manually (via bindPort(int), bindAnyPort() or bindNextPort(int)) or if the port is already in use and cannot be bound, e.g. there is already some Server-Socket technically bound to the given port.

Parameters:

aPortNumber - The port number to be tested if it is already bound.

Returns:

True in case the port is being bound already, else false if it still available.

bindAnyPort

Integer bindAnyPort()
             throws PortNotFoundRuntimeException

Any free port in the range as defined by PortRange.DYNAMIC_PORTS is bound (reserved) and returned. A port is aught to be free when isPortBound(int) returns false.

Returns:

The free port being reserved. The Integer instance is the handle for unbinding a port via unbindPort(Integer).

Throws:

PortNotFoundRuntimeException - thrown in case no port can be determined.

bindPort

Integer bindPort(int aPortNumber)
          throws PortAlreadyBoundException

The port is bound and returned. A port is aught to be free when isPortBound(int) returns false.

Parameters:

aPortNumber - The Port-Number which to bind (reserve).

Returns:

The port being reserved. The Integerinstance is the handle for unbinding a port via unbindPort(Integer).

Throws:

PortAlreadyBoundException - the port already bound exception

unbindPort

boolean unbindPort(Integer aPortNumber)
            throws IllegalArgumentException

Unbinds a port for the given Port-Number using the Integer as handle for unbinding. This means that another Integer instance with another identity fails to unbind the given port.

Parameters:

aPortNumber - The Port-Number for the port to be unbound.

Returns:

True in case the port has been unbound or false if the port was not bound at all.

Throws:

IllegalArgumentException - thrown in case the ginven Integer identity is not allowed to unbind the given port.

bindNextPort

default Integer bindNextPort(int aBeginPortIndex)
                      throws PortNotFoundRuntimeException

The first free port in the range of the given Port-Number and the PortRange.DYNAMIC_PORTS max port number (as of PortRange.getMaxValue()) bound (reserved) and returned. A port is aught to be free when isPortBound(int) returns false.

Parameters:

aBeginPortIndex - The start index of the Port-Number which to bind (reserve).

Returns:

The next free port being reserved. The Integer instance is the handle for unbinding a port via unbindPort(Integer).

Throws:

PortNotFoundRuntimeException - thrown in case no port can be determined.

bindNextPort

default Integer bindNextPort(PortRange aPortRange)

The first free port in the range of the given begin Port-Number index and the given end Port-Number index is bound (reserved) and returned. A port is aught to be free when isPortBound(int) returns false.

Parameters:

aPortRange - The begin index (included) of the Port-Number which to bind (reserve)and the end index (included) of the Port-Number which to bind (reserve).

Returns:

The next free port being reserved. The Integer instance is the handle for unbinding a port via unbindPort(Integer).

bindNextPort

Integer bindNextPort(int aBeginPortIndex,
                     int aEndPortIndex)
              throws PortNotFoundRuntimeException

The first free port in the range of the given begin Port-Number index and the given end Port-Number index is bound (reserved) and returned. A port is aught to be free when isPortBound(int) returns false.

Parameters:

aBeginPortIndex - The begin index (included) of the Port-Number which to bind (reserve).

aEndPortIndex - The end index (included) of the Port-Number which to bind (reserve).

Returns:

The next free port being reserved. The Integer instance is the handle for unbinding a port via unbindPort(Integer).

Throws:

PortNotFoundRuntimeException - thrown in case no port can be determined.

isPortAvaialble

default boolean isPortAvaialble(int aPortNumber)

Tests whether there is already some Server-Socket technically bound to the given port. This method does not test if the port is reserved, it just tests if a Server-Socket could still technically bind to this port.

Parameters:

aPortNumber - The Port-Number to be technically tested if a Server-Socket could still bind to it.

Returns:

True if the port could technically be bound to, else false if some Server-Socket is already bound to this port (or the Security-Manager prevents binding to the port).