org.springframework.util

## Class SocketUtils

- java.lang.Object
- - org.springframework.util.SocketUtils

-     public abstract class SocketUtils
      extends Object

  Simple utility methods for working with network sockets — for example, for finding available ports on `localhost`.

  Within this class, a TCP port refers to a port for a `ServerSocket`; whereas, a UDP port refers to a port for a `DatagramSocket`.

  Since:
    4.0
  Author:
    Sam Brannen, Ben Hale, Arjen Poutsma, Gunnar Hillert

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `PORT_RANGE_MAX` The default maximum value for port ranges used when finding an available socket port.
    `static int` | `PORT_RANGE_MIN` The default minimum value for port ranges used when finding an available socket port.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `SocketUtils()` Although `SocketUtils` consists solely of static utility methods, this constructor is intentionally `public`.

  - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static int` | `findAvailableTcpPort()` Find an available TCP port randomly selected from the range [1024, 65535].
    `static int` | `findAvailableTcpPort(int minPort)` Find an available TCP port randomly selected from the range [`minPort`, 65535].
    `static int` | `findAvailableTcpPort(int minPort, int maxPort)` Find an available TCP port randomly selected from the range [`minPort`, `maxPort`].
    `static SortedSet<Integer>` | `findAvailableTcpPorts(int numRequested)` Find the requested number of available TCP ports, each randomly selected from the range [1024, 65535].
    `static SortedSet<Integer>` | `findAvailableTcpPorts(int numRequested, int minPort, int maxPort)` Find the requested number of available TCP ports, each randomly selected from the range [`minPort`, `maxPort`].
    `static int` | `findAvailableUdpPort()` Find an available UDP port randomly selected from the range [1024, 65535].
    `static int` | `findAvailableUdpPort(int minPort)` Find an available UDP port randomly selected from the range [`minPort`, 65535].
    `static int` | `findAvailableUdpPort(int minPort, int maxPort)` Find an available UDP port randomly selected from the range [`minPort`, `maxPort`].
    `static SortedSet<Integer>` | `findAvailableUdpPorts(int numRequested)` Find the requested number of available UDP ports, each randomly selected from the range [1024, 65535].
    `static SortedSet<Integer>` | `findAvailableUdpPorts(int numRequested, int minPort, int maxPort)` Find the requested number of available UDP ports, each randomly selected from the range [`minPort`, `maxPort`].

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### PORT_RANGE_MIN

          public static final int PORT_RANGE_MIN

      The default minimum value for port ranges used when finding an available socket port.
      See Also:
        Constant Field Values

    - #### PORT_RANGE_MAX

          public static final int PORT_RANGE_MAX

      The default maximum value for port ranges used when finding an available socket port.
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### SocketUtils

          public SocketUtils()

      Although `SocketUtils` consists solely of static utility methods, this constructor is intentionally `public`.

      #### Rationale

      Static methods from this class may be invoked from within XML configuration files using the Spring Expression Language (SpEL) and the following syntax.

          <bean id="bean1" ... p:port="#{T(org.springframework.util.SocketUtils).findAvailableTcpPort(12000)}" />

      If this constructor were `private`, you would be required to supply the fully qualified class name to SpEL's `T()` function for each usage. Thus, the fact that this constructor is `public` allows you to reduce boilerplate configuration with SpEL as can be seen in the following example.

          <bean id="socketUtils" class="org.springframework.util.SocketUtils" />

          <bean id="bean1" ... p:port="#{socketUtils.findAvailableTcpPort(12000)}" />

          <bean id="bean2" ... p:port="#{socketUtils.findAvailableTcpPort(30000)}" />

  - ### Method Detail

    - #### findAvailableTcpPort

          public static int findAvailableTcpPort()

      Find an available TCP port randomly selected from the range [1024, 65535].
      Returns:
        an available TCP port number
      Throws:
        `IllegalStateException` - if no available port could be found

    - #### findAvailableTcpPort

          public static int findAvailableTcpPort(int minPort)

      Find an available TCP port randomly selected from the range [`minPort`, 65535].
      Parameters:
        `minPort` - the minimum port number
      Returns:
        an available TCP port number
      Throws:
        `IllegalStateException` - if no available port could be found

    - #### findAvailableTcpPort

          public static int findAvailableTcpPort(int minPort,
                                                 int maxPort)

      Find an available TCP port randomly selected from the range [`minPort`, `maxPort`].
      Parameters:
        `minPort` - the minimum port number
        `maxPort` - the maximum port number
      Returns:
        an available TCP port number
      Throws:
        `IllegalStateException` - if no available port could be found

    - #### findAvailableTcpPorts

          public static SortedSet<Integer> findAvailableTcpPorts(int numRequested)

      Find the requested number of available TCP ports, each randomly selected from the range [1024, 65535].
      Parameters:
        `numRequested` - the number of available ports to find
      Returns:
        a sorted set of available TCP port numbers
      Throws:
        `IllegalStateException` - if the requested number of available ports could not be found

    - #### findAvailableTcpPorts

          public static SortedSet<Integer> findAvailableTcpPorts(int numRequested,
                                                                 int minPort,
                                                                 int maxPort)

      Find the requested number of available TCP ports, each randomly selected from the range [`minPort`, `maxPort`].
      Parameters:
        `numRequested` - the number of available ports to find
        `minPort` - the minimum port number
        `maxPort` - the maximum port number
      Returns:
        a sorted set of available TCP port numbers
      Throws:
        `IllegalStateException` - if the requested number of available ports could not be found

    - #### findAvailableUdpPort

          public static int findAvailableUdpPort()

      Find an available UDP port randomly selected from the range [1024, 65535].
      Returns:
        an available UDP port number
      Throws:
        `IllegalStateException` - if no available port could be found

    - #### findAvailableUdpPort

          public static int findAvailableUdpPort(int minPort)

      Find an available UDP port randomly selected from the range [`minPort`, 65535].
      Parameters:
        `minPort` - the minimum port number
      Returns:
        an available UDP port number
      Throws:
        `IllegalStateException` - if no available port could be found

    - #### findAvailableUdpPort

          public static int findAvailableUdpPort(int minPort,
                                                 int maxPort)

      Find an available UDP port randomly selected from the range [`minPort`, `maxPort`].
      Parameters:
        `minPort` - the minimum port number
        `maxPort` - the maximum port number
      Returns:
        an available UDP port number
      Throws:
        `IllegalStateException` - if no available port could be found

    - #### findAvailableUdpPorts

          public static SortedSet<Integer> findAvailableUdpPorts(int numRequested)

      Find the requested number of available UDP ports, each randomly selected from the range [1024, 65535].
      Parameters:
        `numRequested` - the number of available ports to find
      Returns:
        a sorted set of available UDP port numbers
      Throws:
        `IllegalStateException` - if the requested number of available ports could not be found

    - #### findAvailableUdpPorts

          public static SortedSet<Integer> findAvailableUdpPorts(int numRequested,
                                                                 int minPort,
                                                                 int maxPort)

      Find the requested number of available UDP ports, each randomly selected from the range [`minPort`, `maxPort`].
      Parameters:
        `numRequested` - the number of available ports to find
        `minPort` - the minimum port number
        `maxPort` - the maximum port number
      Returns:
        a sorted set of available UDP port numbers
      Throws:
        `IllegalStateException` - if the requested number of available ports could not be found