This short tutorial assumes that you have already installed Py4J and that you are using the latest version. In this tutorial, you will write a simple Stack class in Java and then, you will write a Python program that accesses the stack.
You will also see how Java lists can be manipulated as Python lists.
The first step is to write a short Java program. Here you will create a Stack class that offers two basic services and two advanced services:
Here is the code of the stack:
package py4j.examples;
import java.util.LinkedList;
import java.util.List;
public class Stack {
private List<String> internalList = new LinkedList<String>();
public void push(String element) {
internalList.add(0, element);
}
public String pop() {
return internalList.remove(0);
}
public List<String> getInternalList() {
return internalList;
}
public void pushAll(List<String> elements) {
for (String element : elements) {
this.push(element);
}
}
}
To make the stack available to a Python program, you need something that will allow Python programs to:
These features are provided by two objects. The first object is a GatewayServer instance: it allows Python programs to communicate with the JVM through a local network socket. The second object is called an entry point and it can be any object (e.g., a Facade, a singleton, a list, etc.).
The GatewayServer provided by Py4J can be used as is but you can also configure it and specify a network address and port, if the defaults (localhost, 25333) do not work for you. The GatewayServer constructor takes an object (the entry point) as a parameter.
Here is an example of an example of an entry point that would allow a Python program to access a pre-configured stack:
package py4j.examples;
import py4j.GatewayServer;
public class StackEntryPoint {
private Stack stack;
public StackEntryPoint() {
stack = new Stack();
stack.push("Initial Item");
}
public Stack getStack() {
return stack;
}
public static void main(String[] args) {
GatewayServer gatewayServer = new GatewayServer(new StackEntryPoint());
gatewayServer.start();
System.out.println("Gateway Server Started");
}
}
There are a few important lines in this code. First, you declare a class that will provide an access to a pre-configured stack:
public Stack getStack() {
return stack;
}
Then, you create a main method. This main method could be located in another class. The first thing you do in the main method is to initialize a GatewayServer and link it to an entry point.
public static void main(String[] args) {
GatewayServer gatewayServer = new GatewayServer(new StackEntryPoint());
Finally, you need to start the gateway so it can accept incoming Python requests:
gatewayServer.start();
You are now ready to try your Java program. Just execute the StackGateway class in your favorite development environment and check that you see the message Gateway Server Started
Warning
When running your application, you may get a java.net.BindException: Address already in use exception. There are two common causes: either you are already running another instance of your program or another program on your computer is listening to the port 25333. To change the port, replace this line:
GatewayServer gatewayServer = new GatewayServer(new StackEntryPoint());
by this line (use any port number):
GatewayServer gatewayServer = new GatewayServer(new StackEntryPoint(), 25334);
You are now done. Because your program will wait for connections, it will never exit. To terminate your program, you have to kill it (e.g., Ctrl-C). If you initialize the GatewayServer in another method, you can also call gatewayServer.shutdown().
You will now write the python program that will access your Java program. Start a Python interpreter and make sure that Py4J is in your PYTHONPATH.
The first step is to import the necessary Py4J class:
>>> from py4j.java_gateway import JavaGateway
Next, initialize a JavaGateway. The default parameters are usually sufficient for common cases. When you create a JavaGateway, Python tries to connect to a JVM with a gateway (localhost on port 25333).
>>> gateway = JavaGateway()
Warning
If you receive the following error: socket.error: [Errno 111] Connection refused, it means that there is no JVM waiting for a connection. Check that your Java program is still running, or if you did not start it, now would be a good time to do so :-)
From the gateway object, we can access the entry point by referring to its entry_point member:
>>> stack = gateway.entry_point.getStack()
The stack variable now contains a stack. Try to push and pop a few elements:
>>> stack.push("First %s" % ('item'))
>>> stack.push("Second item")
>>> stack.pop()
u'Second item'
>>> stack.pop()
u'First item'
>>> stack.pop()
u'Initial Item'
Now the stack is supposed to be empty. Here is what happens if you try to pop it again.
>>> stack.pop()
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
File "py4j/java_gateway.py", line 161, in __call__
return_value = get_return_value(answer, self.gateway_client, self.target_id, self.name)
File "py4j/java_gateway.py", line 74, in get_return_value
raise Py4JError('An error occurred while calling %s%s%s' % (target_id, '.', name))
py4j.java_gateway.Py4JError: An error occurred while calling o0.pop. Trace:
java.lang.IndexOutOfBoundsException: Index: 0, Size: 0
at java.util.LinkedList.entry(LinkedList.java:365)
at java.util.LinkedList.remove(LinkedList.java:357)
at py4j.examples.Stack.pop(Stack.java:42)
at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39)
at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25)
at java.lang.reflect.Method.invoke(Method.java:597)
at py4j.reflection.MethodInvoker.invoke(MethodInvoker.java:117)
at py4j.reflection.ReflectionEngine.invoke(ReflectionEngine.java:392)
at py4j.Gateway.invoke(Gateway.java:239)
at py4j.AbstractCommand.invokeMethod(AbstractCommand.java:120)
at py4j.CallCommand.execute(CallCommand.java:77)
at py4j.GatewayConnection.run(GatewayConnection.java:158)
at java.lang.Thread.run(Thread.java:619)
You get a Py4JError because there was an exception on the JVM side. In addition, you can see the type of exception that was thrown on the Java side and its stack trace.
Now, you will experiment with lists. Add another element and get the internal list of the stack:
>>> stack.push('First item')
>>> internal_list = stack.getInternalList()
>>> len(internal_list)
1
>>> internal_list[0]
u'First item'
>>> internal_list.append('Second item')
>>> internal_list
[u'First item', u'Second item']
>>> stack.getInternalList()
[u'First item', u'Second item']
As you can see, lists created on the JVM act like Python lists: you can use the [] operator and the usual list methods like len and append. Notice that when you change the list on the Python side, it is also changed on the Java side. Now try to slice the list:
>>> sliced_list = internal_list[0:1]
>>> sliced_list
[u'First item']
>>> sliced_list.append('Third item')
>>> sliced_list
[u'First item', u'Third item']
>>> internal_list
[u'First item', u'Second item']
>>> stack.getInternalList()
[u'First item', u'Second item']
>>> stack.pushAll(sliced_list)
>>> stack.getInternalList()
[u'Third item', u'First item', u'First item', u'Second item']
Slices act like real Python slices: they are a copy of the original list, no more, no less. This is why the original list is not modified when you modify the slice. When you create a slice, Py4J first creates the slice on the JVM side so you are really accessing a Java list contained in the JVM.
Note
For the keen Java programmers among you, note that the slice operation is NOT implemented with the subList method in Java, because subList returns a view, not a copy, of the list: when the original list changes, the view generally becomes invalid so this is not a suitable replacement for a slice.
In the previous example, you also tried to pass a list as a parameter of the pushAll method. See what happens if you try to pass a pure Python list that was not returned by the JVM:
>>> stack.pushAll(['Fourth item'])
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
File "py4j/java_gateway.py", line 158, in __call__
args_command = ''.join([get_command_part(arg) for arg in args])
File "py4j/java_gateway.py", line 68, in get_command_part
command_part = REFERENCE_TYPE + parameter.get_object_id()
AttributeError: 'list' object has no attribute 'get_object_id'
>>> stack.getInternalList()
[u'Third item', u'First item', u'First item', u'Second item']
By default, Py4J does not support the conversion from pure Python lists to Java list. It is possible to ask Py4J to automatically perform this conversion or to use one of the explicit converter. See Collections Conversion for more information.
Python has powerful introspection abilities that are slowly being replicated by Py4J. For example, a JavaGateway allows you to list all the members available in an object:
>>> gateway.help(stack)
Help on class Stack in package py4j.examples:
Stack {
|
| Methods defined here:
|
| getInternalList() : List
|
| pop() : String
|
| push(String) : void
|
| pushAll(List) : void
|
| ------------------------------------------------------------
| Fields defined here:
|
| ------------------------------------------------------------
| Internal classes defined here:
|
}
Finally, you do not need an entry point to create and access objects. You can use the jvm member to call constructors and static members:
>>> java_list = gateway.jvm.java.util.ArrayList()
>>> java_list.append(214)
>>> java_list.append(120)
>>> gateway.jvm.java.util.Collections.sort(java_list)
>>> java_list
[120, 214]