py4j

## Class GatewayServer

- java.lang.Object
- - py4j.DefaultGatewayServerListener
  - - py4j.GatewayServer

- All Implemented Interfaces:
    Runnable, GatewayServerListener

      public class GatewayServer
      extends DefaultGatewayServerListener
      implements Runnable

  This class enables Python programs to access a Java program. When a GatewayServer instance is started, Python programs can connect to the JVM by calling:

  `gateway = JavaGateway()`

  The `entryPoint` passed to a GatewayServer can be accessed with the `entry_point` member:

  `gateway.entry_point`

  Technically, a GatewayServer is only responsible for accepting connection. Each connection is then handled by a `GatewayConnection` instance and the various states (e.g., entryPoint, reference to returned objects) are managed by a `Gateway` instance.

  Author:
    Barthelemy Dagenais

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static String` | `DEFAULT_ADDRESS`
    `static int` | `DEFAULT_CONNECT_TIMEOUT`
    `static int` | `DEFAULT_PORT`
    `static int` | `DEFAULT_PYTHON_PORT`
    `static int` | `DEFAULT_READ_TIMEOUT`
    `static String` | `GATEWAY_SERVER_ID`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `GatewayServer(Object entryPoint)` Creates a GatewayServer instance with default port (25333), default address (127.0.0.1), and default timeout value (no timeout).
    `GatewayServer(Object entryPoint, int port)`
    `GatewayServer(Object entryPoint, int port, int pythonPort, InetAddress address, InetAddress pythonAddress, int connectTimeout, int readTimeout, List<Class<? extends Command>> customCommands)`
    `GatewayServer(Object entryPoint, int port, int connectTimeout, int readTimeout)`
    `GatewayServer(Object entryPoint, int port, int pythonPort, int connectTimeout, int readTimeout, List<Class<? extends Command>> customCommands)`
    `GatewayServer(Object entryPoint, int port, int connectTimeout, int readTimeout, List<Class<? extends Command>> customCommands, CallbackClient cbClient)`

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addListener(GatewayServerListener listener)`
    `void` | `connectionStopped(GatewayConnection gatewayConnection)`
    `protected GatewayConnection` | `createConnection(Gateway gateway, Socket socket)`
    `protected void` | `fireConnectionError(Exception e)`
    `protected void` | `fireConnectionStarted(GatewayConnection gatewayConnection)`
    `protected void` | `fireServerError(Exception e)`
    `protected void` | `fireServerPostShutdown()`
    `protected void` | `fireServerPreShutdown()`
    `protected void` | `fireServerStarted()`
    `protected void` | `fireServerStopped()`
    `InetAddress` | `getAddress()`
    `CallbackClient` | `getCallbackClient()`
    `int` | `getConnectTimeout()`
    `List<Class<? extends Command>>` | `getCustomCommands()`
    `List<GatewayServerListener>` | `getListeners()`
    `int` | `getListeningPort()`
    `int` | `getPort()`
    `InetAddress` | `getPythonAddress()`
    `int` | `getPythonPort()`
    `int` | `getReadTimeout()`
    `static void` | `main(String[] args)` Main method to start a local GatewayServer on a given port.
    `void` | `removeListener(GatewayServerListener listener)`
    `void` | `run()`
    `void` | `shutdown()` Stops accepting connections, closes all current connections, and calls `Gateway.shutdown()`
    `void` | `start()` Starts to accept connections in a second thread (non-blocking call).
    `void` | `start(boolean fork)` Starts to accept connections.
    `protected void` | `startSocket()` Starts the ServerSocket.
    `static void` | `turnAllLoggingOn()` Utility method to turn logging on.
    `static void` | `turnLoggingOff()` Utility method to turn logging off.
    `static void` | `turnLoggingOn()` Utility method to turn logging on.

    - ### Methods inherited from class py4j.DefaultGatewayServerListener

      `connectionError, connectionStarted, serverError, serverPostShutdown, serverPreShutdown, serverStarted, serverStopped`

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

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

- - ### Field Detail

    - #### DEFAULT_ADDRESS

          public static final String DEFAULT_ADDRESS

      See Also:
        Constant Field Values

    - #### DEFAULT_PORT

          public static final int DEFAULT_PORT

      See Also:
        Constant Field Values

    - #### DEFAULT_PYTHON_PORT

          public static final int DEFAULT_PYTHON_PORT

      See Also:
        Constant Field Values

    - #### DEFAULT_CONNECT_TIMEOUT

          public static final int DEFAULT_CONNECT_TIMEOUT

      See Also:
        Constant Field Values

    - #### DEFAULT_READ_TIMEOUT

          public static final int DEFAULT_READ_TIMEOUT

      See Also:
        Constant Field Values

    - #### GATEWAY_SERVER_ID

          public static final String GATEWAY_SERVER_ID

      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### GatewayServer

          public GatewayServer(Object entryPoint)

      Creates a GatewayServer instance with default port (25333), default address (127.0.0.1), and default timeout value (no timeout).

      Parameters:
        `entryPoint` - The entry point of this Gateway. Can be null.

    - #### GatewayServer

          public GatewayServer(Object entryPoint,
                               int port)

      Parameters:
        `entryPoint` - The entry point of this Gateway. Can be null.
        `port` - The port the GatewayServer is listening to.

    - #### GatewayServer

          public GatewayServer(Object entryPoint,
                               int port,
                               int pythonPort,
                               InetAddress address,
                               InetAddress pythonAddress,
                               int connectTimeout,
                               int readTimeout,
                               List<Class<? extends Command>> customCommands)

      Parameters:
        `entryPoint` - The entry point of this Gateway. Can be null.
        `port` - The port the GatewayServer is listening to.
        `pythonPort` - The port used by a PythonProxyHandler to connect to a Python gateway. Essentially the port used for Python callbacks.
        `address` - The address the GatewayServer is listening to.
        `pythonAddress` - The address used by a PythonProxyHandler to connect to a Python gateway.
        `connectTimeout` - Time in milliseconds (0 = infinite). If a GatewayServer does not receive a connection request after this time, it closes the server socket and no other connection is accepted.
        `readTimeout` - Time in milliseconds (0 = infinite). Once a Python program is connected, if a GatewayServer does not receive a request (e.g., a method call) after this time, the connection with the Python program is closed.
        `customCommands` - A list of custom Command classes to augment the Server features. These commands will be accessible from Python programs. Can be null.

    - #### GatewayServer

          public GatewayServer(Object entryPoint,
                               int port,
                               int connectTimeout,
                               int readTimeout)

      Parameters:
        `entryPoint` - The entry point of this Gateway. Can be null.
        `port` - The port the GatewayServer is listening to.
        `connectTimeout` - Time in milliseconds (0 = infinite). If a GatewayServer does not receive a connection request after this time, it closes the server socket and no other connection is accepted.
        `readTimeout` - Time in milliseconds (0 = infinite). Once a Python program is connected, if a GatewayServer does not receive a request (e.g., a method call) after this time, the connection with the Python program is closed.

    - #### GatewayServer

          public GatewayServer(Object entryPoint,
                               int port,
                               int pythonPort,
                               int connectTimeout,
                               int readTimeout,
                               List<Class<? extends Command>> customCommands)

      Parameters:
        `entryPoint` - The entry point of this Gateway. Can be null.
        `port` - The port the GatewayServer is listening to.
        `pythonPort` - The port used by a PythonProxyHandler to connect to a Python gateway. Essentially the port used for Python callbacks.
        `connectTimeout` - Time in milliseconds (0 = infinite). If a GatewayServer does not receive a connection request after this time, it closes the server socket and no other connection is accepted.
        `readTimeout` - Time in milliseconds (0 = infinite). Once a Python program is connected, if a GatewayServer does not receive a request (e.g., a method call) after this time, the connection with the Python program is closed.
        `customCommands` - A list of custom Command classes to augment the Server features. These commands will be accessible from Python programs. Can be null.

    - #### GatewayServer

          public GatewayServer(Object entryPoint,
                               int port,
                               int connectTimeout,
                               int readTimeout,
                               List<Class<? extends Command>> customCommands,
                               CallbackClient cbClient)

  - ### Method Detail

    - #### turnAllLoggingOn

          public static void turnAllLoggingOn()

      Utility method to turn logging on. Logging is turned off by default. All log messages will be logged.

    - #### turnLoggingOff

          public static void turnLoggingOff()

      Utility method to turn logging off. Logging is turned off by default.

    - #### turnLoggingOn

          public static void turnLoggingOn()

      Utility method to turn logging on. Logging is turned off by default. Log messages up to INFO level will be logged.

    - #### addListener

          public void addListener(GatewayServerListener listener)

    - #### connectionStopped

          public void connectionStopped(GatewayConnection gatewayConnection)

      Specified by:
        `connectionStopped` in interface `GatewayServerListener`
      Overrides:
        `connectionStopped` in class `DefaultGatewayServerListener`

    - #### createConnection

          protected GatewayConnection createConnection(Gateway gateway,
                                                       Socket socket)
                                                throws IOException

      Throws:
        `IOException`

    - #### fireConnectionError

          protected void fireConnectionError(Exception e)

    - #### fireConnectionStarted

          protected void fireConnectionStarted(GatewayConnection gatewayConnection)

    - #### fireServerError

          protected void fireServerError(Exception e)

    - #### fireServerPostShutdown

          protected void fireServerPostShutdown()

    - #### fireServerPreShutdown

          protected void fireServerPreShutdown()

    - #### fireServerStarted

          protected void fireServerStarted()

    - #### fireServerStopped

          protected void fireServerStopped()

    - #### getAddress

          public InetAddress getAddress()

    - #### getCallbackClient

          public CallbackClient getCallbackClient()

    - #### getConnectTimeout

          public int getConnectTimeout()

    - #### getListeningPort

          public int getListeningPort()

      Returns:
        The port the server socket is listening on. It will be different than the specified port if the socket is listening on an ephemeral port (specified port = 0). Returns -1 if the server socket is not listening on anything.

    - #### getPort

          public int getPort()

      Returns:
        The port specified when the gateway server is initialized. This is the port that is passed to the server socket.

    - #### getPythonAddress

          public InetAddress getPythonAddress()

    - #### getPythonPort

          public int getPythonPort()

    - #### getReadTimeout

          public int getReadTimeout()

    - #### removeListener

          public void removeListener(GatewayServerListener listener)

    - #### run

          public void run()

      Specified by:
        `run` in interface `Runnable`

    - #### shutdown

          public void shutdown()

      Stops accepting connections, closes all current connections, and calls `Gateway.shutdown()`

    - #### start

          public void start()

      Starts to accept connections in a second thread (non-blocking call).

    - #### start

          public void start(boolean fork)

      Starts to accept connections.

      Parameters:
        `fork` - If true, the GatewayServer accepts connection in another thread and this call is non-blocking. If False, the GatewayServer accepts connection in this thread and the call is blocking (until the Gateway is shutdown by another thread).
      Throws:
        `Py4JNetworkException` - If the server socket cannot start.

    - #### startSocket

          protected void startSocket()
                              throws Py4JNetworkException

      Starts the ServerSocket.

      Throws:
        `Py4JNetworkException` - If the port is busy.

    - #### main

          public static void main(String[] args)

      Main method to start a local GatewayServer on a given port. The listening port is printed to stdout so that clients can start servers on ephemeral ports.

    - #### getCustomCommands

          public List<Class<? extends Command>> getCustomCommands()

      Returns:
        An unmodifiable list of custom commands

    - #### getListeners

          public List<GatewayServerListener> getListeners()

      Returns:
        An unmodifiable list of listeners