py4j

## Class GatewayServer

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

- All Implemented Interfaces:
    java.lang.Runnable, GatewayServerListener, Py4JJavaServer
  Direct Known Subclasses:
    JavaServer

      public class GatewayServer
      extends DefaultGatewayServerListener
      implements Py4JJavaServer, java.lang.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.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `GatewayServer.GatewayServerBuilder` Helper class to make it easier and self-documenting how a `GatewayServer` is constructed.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `DEFAULT_ADDRESS`
    `static int` | `DEFAULT_CONNECT_TIMEOUT`
    `static int` | `DEFAULT_PORT`
    `static int` | `DEFAULT_PYTHON_PORT`
    `static int` | `DEFAULT_READ_TIMEOUT`
    `static java.lang.String` | `GATEWAY_SERVER_ID`
    `static java.util.logging.Logger` | `PY4J_LOGGER`

  - ### Constructor Summary

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

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addListener(GatewayServerListener listener)`
    `void` | `connectionStopped(Py4JServerConnection gatewayConnection)`
    `protected Py4JServerConnection` | `createConnection(Gateway gateway, java.net.Socket socket)` Creates a server connection from a Python call to the Java side.
    `static java.net.InetAddress` | `defaultAddress()`
    `protected void` | `fireConnectionError(java.lang.Exception e)`
    `protected void` | `fireConnectionStarted(Py4JServerConnection gatewayConnection)`
    `protected void` | `fireServerError(java.lang.Exception e)`
    `protected void` | `fireServerPostShutdown()`
    `protected void` | `fireServerPreShutdown()`
    `protected void` | `fireServerStarted()`
    `protected void` | `fireServerStopped()`
    `java.net.InetAddress` | `getAddress()`
    `Py4JPythonClient` | `getCallbackClient()`
    `int` | `getConnectTimeout()`
    `java.util.List<java.lang.Class<? extends Command>>` | `getCustomCommands()`
    `Gateway` | `getGateway()`
    `java.util.List<GatewayServerListener>` | `getListeners()`
    `int` | `getListeningPort()`
    `int` | `getPort()`
    `java.net.InetAddress` | `getPythonAddress()`
    `int` | `getPythonPort()`
    `java.lang.Object` | `getPythonServerEntryPoint(java.lang.Class[] interfacesToImplement)` Gets a reference to the entry point on the Python side.
    `int` | `getReadTimeout()`
    `static void` | `main(java.lang.String[] args)` Main method to start a local GatewayServer on a given port.
    `protected void` | `processSocket(java.net.Socket socket)`
    `void` | `removeListener(GatewayServerListener listener)`
    `void` | `resetCallbackClient(java.net.InetAddress pythonAddress, int pythonPort)` Replace the callback client with the new one which connects to the given address and port.
    `void` | `run()`
    `void` | `shutdown()` Stops accepting connections, closes all current connections, and calls `Gateway.shutdown()`
    `void` | `shutdown(boolean shutdownCallbackClient)` 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 java.lang.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 java.lang.String GATEWAY_SERVER_ID

      See Also:
        Constant Field Values

    - #### PY4J_LOGGER

          public static final java.util.logging.Logger PY4J_LOGGER

  - ### Constructor Detail

    - #### GatewayServer

          public GatewayServer()

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

    - #### GatewayServer

          public GatewayServer(java.lang.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(java.lang.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(java.lang.Object entryPoint,
                               int port,
                               int pythonPort,
                               java.net.InetAddress address,
                               java.net.InetAddress pythonAddress,
                               int connectTimeout,
                               int readTimeout,
                               java.util.List<java.lang.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(java.lang.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(java.lang.Object entryPoint,
                               int port,
                               int pythonPort,
                               int connectTimeout,
                               int readTimeout,
                               java.util.List<java.lang.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(java.lang.Object entryPoint,
                               int port,
                               int connectTimeout,
                               int readTimeout,
                               java.util.List<java.lang.Class<? extends Command>> customCommands,
                               Py4JPythonClient cbClient)

      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.
        `customCommands` - A list of custom Command classes to augment the Server features. These commands will be accessible from Python programs. Can be null.
        `cbClient` - An instance of a callback client.

    - #### GatewayServer

          public GatewayServer(java.lang.Object entryPoint,
                               int port,
                               java.net.InetAddress address,
                               int connectTimeout,
                               int readTimeout,
                               java.util.List<java.lang.Class<? extends Command>> customCommands,
                               Py4JPythonClient cbClient)

      Parameters:
        `entryPoint` - The entry point of this Gateway. Can be null.
        `port` - The port the GatewayServer is listening to.
        `address` - The address 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.
        `customCommands` - A list of custom Command classes to augment the Server features. These commands will be accessible from Python programs. Can be null.
        `cbClient` - An instance of a callback client.

    - #### GatewayServer

          public GatewayServer(java.lang.Object entryPoint,
                               int port,
                               java.net.InetAddress address,
                               int connectTimeout,
                               int readTimeout,
                               java.util.List<java.lang.Class<? extends Command>> customCommands,
                               Py4JPythonClient cbClient,
                               javax.net.ServerSocketFactory sSocketFactory)

      Parameters:
        `entryPoint` - The entry point of this Gateway. Can be null.
        `port` - The port the GatewayServer is listening to.
        `address` - The address 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.
        `customCommands` - A list of custom Command classes to augment the Server features. These commands will be accessible from Python programs. Can be null.
        `sSocketFactory` - A factory that creates the server sockets that we listen on.

  - ### 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.

    - #### defaultAddress

          public static java.net.InetAddress defaultAddress()

    - #### resetCallbackClient

          public void resetCallbackClient(java.net.InetAddress pythonAddress,
                                          int pythonPort)

      Replace the callback client with the new one which connects to the given address and port. This method is useful if for some reason your CallbackServer changes its address or you come to know of the address after Gateway has already instantiated.

      This method is not thread-safe! Make sure that only one thread calls this method.

      Parameters:
        `pythonAddress` - The address used by a PythonProxyHandler to connect to a Python gateway.
        `pythonPort` - The port used by a PythonProxyHandler to connect to a Python gateway. Essentially the port used for Python callbacks.

    - #### addListener

          public void addListener(GatewayServerListener listener)

      Specified by:
        `addListener` in interface `Py4JJavaServer`

    - #### connectionStopped

          public void connectionStopped(Py4JServerConnection gatewayConnection)

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

    - #### createConnection

          protected Py4JServerConnection createConnection(Gateway gateway,
                                                          java.net.Socket socket)
                                                   throws java.io.IOException

      Creates a server connection from a Python call to the Java side.

      Parameters:
        `gateway` -
        `socket` -
      Returns:
      Throws:
        `java.io.IOException`

    - #### fireConnectionError

          protected void fireConnectionError(java.lang.Exception e)

    - #### fireConnectionStarted

          protected void fireConnectionStarted(Py4JServerConnection gatewayConnection)

    - #### fireServerError

          protected void fireServerError(java.lang.Exception e)

    - #### fireServerPostShutdown

          protected void fireServerPostShutdown()

    - #### fireServerPreShutdown

          protected void fireServerPreShutdown()

    - #### fireServerStarted

          protected void fireServerStarted()

    - #### fireServerStopped

          protected void fireServerStopped()

    - #### getAddress

          public java.net.InetAddress getAddress()

      Specified by:
        `getAddress` in interface `Py4JJavaServer`

    - #### getCallbackClient

          public Py4JPythonClient getCallbackClient()

    - #### getConnectTimeout

          public int getConnectTimeout()

    - #### getGateway

          public Gateway getGateway()

      Specified by:
        `getGateway` in interface `Py4JJavaServer`

    - #### getListeningPort

          public int getListeningPort()

      Specified by:
        `getListeningPort` in interface `Py4JJavaServer`
      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()

      Specified by:
        `getPort` in interface `Py4JJavaServer`
      Returns:
        The port specified when the gateway server is initialized. This is the port that is passed to the server socket.

    - #### getPythonAddress

          public java.net.InetAddress getPythonAddress()

      Specified by:
        `getPythonAddress` in interface `Py4JJavaServer`

    - #### getPythonPort

          public int getPythonPort()

      Specified by:
        `getPythonPort` in interface `Py4JJavaServer`

    - #### getReadTimeout

          public int getReadTimeout()

    - #### processSocket

          protected void processSocket(java.net.Socket socket)

    - #### removeListener

          public void removeListener(GatewayServerListener listener)

      Specified by:
        `removeListener` in interface `Py4JJavaServer`

    - #### run

          public void run()

      Specified by:
        `run` in interface `java.lang.Runnable`

    - #### shutdown

          public void shutdown()

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

      Specified by:
        `shutdown` in interface `Py4JJavaServer`

    - #### shutdown

          public void shutdown(boolean shutdownCallbackClient)

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

      Specified by:
        `shutdown` in interface `Py4JJavaServer`
      Parameters:
        `shutdownCallbackClient` - If True, shuts down the CallbackClient instance.

    - #### start

          public void start()

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

      Specified by:
        `start` in interface `Py4JJavaServer`

    - #### start

          public void start(boolean fork)

      Starts to accept connections.

      Specified by:
        `start` in interface `Py4JJavaServer`
      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.

    - #### getPythonServerEntryPoint

          public java.lang.Object getPythonServerEntryPoint(java.lang.Class[] interfacesToImplement)

      Gets a reference to the entry point on the Python side. This is often necessary if Java is driving the communication because Java cannot call static methods, initialize Python objects or load Python modules yet.

      Parameters:
        `interfacesToImplement` -
      Returns:

    - #### main

          public static void main(java.lang.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 java.util.List<java.lang.Class<? extends Command>> getCustomCommands()

      Returns:
        An unmodifiable list of custom commands

    - #### getListeners

          public java.util.List<GatewayServerListener> getListeners()

      Specified by:
        `getListeners` in interface `Py4JJavaServer`
      Returns:
        An unmodifiable list of listeners