org.terracotta.utilities.test.net

Class PortManager

java.lang.Object

org.terracotta.utilities.test.net.PortManager

public class PortManager
extends java.lang.Object

Manages TCP port reservation/de-reservation while attempting to avoid intra- and extra-JVM interference.

The port manager maintains two levels of reservation -- intra-JVM using an internal BitSet and inter-JVM using locks against a RandomAccessFile allocated in a system-wide, world-writable, system-dependent location. To avoid reservation/use races, ephemeral ports are not used.

All users of PortManager in a JVM must use the same PortManager instance to ensure proper intra-JVM reservations.

By default, release of an assigned port back to PortManager (via PortManager.PortRef.close() or garbage collection of a weakly-reachable PortRef instance) performs a check that the port is actually unused. This involves querying both the in-use ports and active processes on the system and, on some systems, could be a time-consuming activity. While the check is intended to identify "outside" interference with ports assigned by PortManager, it is possible to disable this check by setting the "org.terracotta.disablePortReleaseCheck" property or "DISABLE_PORT_RELEASE_CHECK" environment variable to true. The property value is examined each time the release check is performed so the check may be disabled for some tests and left enabled for others; the environment variable is only examined when the PortManger class is loaded.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	PortManager.PortRef Represents a reserved TCP port.

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	DISABLE_PORT_RELEASE_CHECK_ENV_VARIABLE Environment variable checked for disabling the port release check performed at the time a port obtained from PortManager is returned to PortManger.
static java.lang.String	DISABLE_PORT_RELEASE_CHECK_PROPERTY Property checked for disabling the port release check performed at the time a port obtained from PortManager is returned to PortManager.

Method Summary

Modifier and Type	Method and Description
static PortManager	getInstance() Gets the singleton instance of PortManager to use in a JVM.
java.util.Optional<PortManager.PortRef>	getPortRef(int port) Gets the active PortManager.PortRef instance for the designated port.
boolean	isReservablePort(int port) Indicates if the designated port is in the range of ports that may be allocated by this class.
java.util.Optional<PortManager.PortRef>	reserve(int port) Attempts to reserve the specified port.
PortManager.PortRef	reservePort() Reserve a single, randomly selected port.
java.util.List<PortManager.PortRef>	reservePorts(int portCount) Reserves the specified number of ports returning a list of PortManager.PortRef instances for those reserved.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DISABLE_PORT_RELEASE_CHECK_PROPERTY

public static final java.lang.String DISABLE_PORT_RELEASE_CHECK_PROPERTY

Property checked for disabling the port release check performed at the time a port obtained from PortManager is returned to PortManager.

See Also:

Constant Field Values

DISABLE_PORT_RELEASE_CHECK_ENV_VARIABLE

public static final java.lang.String DISABLE_PORT_RELEASE_CHECK_ENV_VARIABLE

Environment variable checked for disabling the port release check performed at the time a port obtained from PortManager is returned to PortManger.

See Also:

Constant Field Values

Method Detail

getInstance

public static PortManager getInstance()

Gets the singleton instance of PortManager to use in a JVM.

Returns:

the singleton PortManager instance

isReservablePort

public boolean isReservablePort(int port)

Indicates if the designated port is in the range of ports that may be allocated by this class. If the designated port is in the range of ports that may be allocated, the reserve(int) method may be used to attempt to allocate the port. The port may also be returned from the reservePort() and reservePorts(int) methods.

Parameters:

port - the port number to test

Returns:

true if port may be reserved using reserve(int); false if port is not a reservable port. A true result is not an indication that port is currently available to be reserved.

Throws:

java.lang.IllegalArgumentException - if port is not between 0 and (inclusive)

getPortRef

public java.util.Optional<PortManager.PortRef> getPortRef(int port)

Gets the active PortManager.PortRef instance for the designated port.

This method returns a reference to the most recent PortRef created for the designated port if the PortRef is both strongly reachable and not closed. The result of this method may be immediately stale -- the PortRef may be closed between the time the PortRef is checked and the reference returned to the called.

Parameters:

port - the port number for which the PortRef is returned

Returns:

an Optional of the PortRef for port if the PortRef is both strongly reachable and not closed; Optional.empty if the PortRef for port is either not strongly reachable or closed

Throws:

java.lang.IllegalArgumentException - if port is not between 0 and (inclusive) or is not a reservable port

reserve

public java.util.Optional<PortManager.PortRef> reserve(int port)

Attempts to reserve the specified port.

The PortManager.PortRef.close() method should be called when the port is no longer needed. However, the returned PortRef instance must strongly-referenced as long as the port is required -- once the PortRef instance becomes weakly-referenced, the port reservation may be released.

Parameters:

port - the port number to reserve

Returns:

an Optional containing the PortManager.PortRef if the port was successfully reserved; Optional.empty if the port could not be reserved

Throws:

java.lang.IllegalArgumentException - if port is not between 0 and (inclusive) or is not a reservable port

java.lang.IllegalStateException - if reservation fails due to an error

reservePorts

public java.util.List<PortManager.PortRef> reservePorts(int portCount)

Reserves the specified number of ports returning a list of PortManager.PortRef instances for those reserved.

The PortManager.PortRef.close() method should be called on each port when no longer needed. However, each returned PortRef instance must strongly-referenced as long as the port is required -- once the PortRef instance becomes weakly-referenced, the port reservation may be released.

Parameters:

portCount - the number of ports to reserve

Returns:

the list of PortRef instances for the reserved ports; the ports are not assigned sequentially

Throws:

java.lang.IllegalArgumentException - if portCount is less than 1 or greater than the number of reservable ports

java.lang.IllegalStateException - if the reservable ports are exhausted or reservation fails due to an error

reservePort

public PortManager.PortRef reservePort()

Reserve a single, randomly selected port.

The PortManager.PortRef.close() method should be called on the port when no longer needed. However, the returned PortRef instance must strongly-referenced as long as the port is required -- once the PortRef instance becomes weakly-referenced, the port reservation may be released.

Returns:

a PortRef instance identifying the reserved port

Throws:

java.lang.IllegalStateException - if the reservable ports are exhausted or reservation fails due to an error