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

      All Methods Instance Methods Abstract Methods Default Methods 
      Modifier and Type Method Description
      java.lang.Integer bindAnyPort​()
      Any free port in the range as defined by PortRange.DYNAMIC_PORTS is bound (reserved) and returned.
      default java.lang.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.
      java.lang.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 java.lang.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.
      java.lang.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​(java.lang.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.

      • bindPort

        java.lang.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​(java.lang.Integer aPortNumber)
            throws java.lang.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:
        java.lang.IllegalArgumentException - thrown in case the ginven Integer identity is not allowed to unbind the given port.

      • bindNextPort

        default java.lang.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

        java.lang.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).