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 theentry_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 aGateway
instance.- Author:
- Barthelemy Dagenais
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
GatewayServer.GatewayServerBuilder
Helper class to make it easier and self-documenting how aGatewayServer
is constructed.
-
Field Summary
Fields Modifier and Type Field Description protected java.lang.String
authToken
static java.lang.String
DEFAULT_ADDRESS
static int
DEFAULT_CONNECT_TIMEOUT
static java.lang.String
DEFAULT_IPv6_ADDRESS
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 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, 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)
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, 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(Gateway gateway, int port, java.net.InetAddress address, int connectTimeout, int readTimeout, java.util.List<java.lang.Class<? extends Command>> customCommands, javax.net.ServerSocketFactory sSocketFactory)
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method 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()
static java.net.InetAddress
defaultIPv6Address()
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 either a given port or the default one.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 callsGateway.shutdown()
void
shutdown(boolean shutdownCallbackClient)
Stops accepting connections, closes all current connections, and callsGateway.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
-
-
-
-
Field Detail
-
DEFAULT_ADDRESS
public static final java.lang.String DEFAULT_ADDRESS
- See Also:
- Constant Field Values
-
DEFAULT_IPv6_ADDRESS
public static final java.lang.String DEFAULT_IPv6_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
-
authToken
protected final java.lang.String authToken
-
-
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.
-
GatewayServer
public GatewayServer(Gateway gateway, int port, java.net.InetAddress address, int connectTimeout, int readTimeout, java.util.List<java.lang.Class<? extends Command>> customCommands, javax.net.ServerSocketFactory sSocketFactory)
- Parameters:
gateway
- gateway instance (or subclass). Must not benull
.port
- the host port to usuaddress
- the host address to useconnectTimeout
- the connect timeout (ms)readTimeout
- the read timeout (ms)customCommands
- any customCommands to use. May benull
sSocketFactory
- socketFactory to use. Must not benull
-
-
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()
-
defaultIPv6Address
public static java.net.InetAddress defaultIPv6Address()
-
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 interfacePy4JJavaServer
-
connectionStopped
public void connectionStopped(Py4JServerConnection gatewayConnection)
- Specified by:
connectionStopped
in interfaceGatewayServerListener
- Overrides:
connectionStopped
in classDefaultGatewayServerListener
-
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 interfacePy4JJavaServer
-
getCallbackClient
public Py4JPythonClient getCallbackClient()
-
getConnectTimeout
public int getConnectTimeout()
-
getGateway
public Gateway getGateway()
- Specified by:
getGateway
in interfacePy4JJavaServer
-
getListeningPort
public int getListeningPort()
- Specified by:
getListeningPort
in interfacePy4JJavaServer
- 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 interfacePy4JJavaServer
- 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 interfacePy4JJavaServer
-
getPythonPort
public int getPythonPort()
- Specified by:
getPythonPort
in interfacePy4JJavaServer
-
getReadTimeout
public int getReadTimeout()
-
processSocket
protected void processSocket(java.net.Socket socket)
-
removeListener
public void removeListener(GatewayServerListener listener)
- Specified by:
removeListener
in interfacePy4JJavaServer
-
run
public void run()
- Specified by:
run
in interfacejava.lang.Runnable
-
shutdown
public void shutdown()
Stops accepting connections, closes all current connections, and calls
Gateway.shutdown()
- Specified by:
shutdown
in interfacePy4JJavaServer
-
shutdown
public void shutdown(boolean shutdownCallbackClient)
Stops accepting connections, closes all current connections, and calls
Gateway.shutdown()
- Specified by:
shutdown
in interfacePy4JJavaServer
- 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 interfacePy4JJavaServer
-
start
public void start(boolean fork)
Starts to accept connections.
- Specified by:
start
in interfacePy4JJavaServer
- 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 either a given port or the default one. The listening port is printed to stdout so that clients can start servers on ephemeral ports.
If authentication is enabled, the server will create an auth secret with 256 bits of entropy and print it to stdout after the server port. Clients should then provide this secret when connecting to the server. Note that no second line of output is printed if authentication is not enabled.
-
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 interfacePy4JJavaServer
- Returns:
- An unmodifiable list of listeners
-
-