py4j
Class GatewayServer

java.lang.Object
  extended by py4j.DefaultGatewayServerListener
      extended by 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
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
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 py4j.commands.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 py4j.commands.Command>> customCommands)
           
GatewayServer(Object entryPoint, int port, int connectTimeout, int readTimeout, List<Class<? extends py4j.commands.Command>> customCommands, CallbackClient cbClient)
           
 
Method Summary
 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()
           
 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 py4j.commands.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 py4j.commands.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 py4j.commands.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.