The py4j.java_gateway module defines most of the classes that are needed to use Py4J. Py4J users are expected to only use explicitly JavaGateway and optionally, CommChannelFactory, get_field, and get_method. The other module members are documented to support the extension of Py4J.
A JavaGateway is the main interaction point between a Python VM and a JVM.
Methods that are not defined by JavaGateway are always redirected to entry_point. For example, gateway.doThat() is equivalent to gateway.entry_point.doThat(). This is a trade-off between convenience and potential confusion.
Parameters: |
|
---|
Makes the Java Gateway dereference this object.
The equivalent of this method is called when a JavaObject instance is garbage collected on the Python side. This method, or gc.collect() should still be invoked when memory is limited or when too many objects are created on the Java side. :param java_object: The JavaObject instance to dereference (free) on the Java side.
Displays a help page about a class or an object.
Parameters: |
|
---|
Creates a Java array of type java_class of dimensions
Parameters: |
|
---|
Using the jvm property:
>>> gateway = JavaGateway()
>>> jvm = gateway.jvm
>>> l = jvm.java.util.ArrayList()
>>> l.append(10)
>>> l.append(1)
>>> jvm.java.util.Collections.sort(l)
>>> l
[1, 10]
>>> l.append(5)
>>> l.sort()
>>> l
[1, 5, 10]
Using auto_field:
First we declare a class that has a field AND a method called member:
package py4j.examples;
public class ExampleWithField {
public int member = 1;
public String member() {
return "Hello World";
}
}
Then we play with the class using the two possible values of auto_field:
>>> java_gateway = JavaGateway() # auto_field = False
>>> example = java_gateway.jvm.py4j.examples.ExampleWithField()
>>> example.member()
u'Hello World'
>>> get_field(example,'member')
1
>>> java_gateway2 = JavaGateway(auto_field=True)
>>> example2 = java_gateway2.jvm.py4j.examples.ExampleWithField()
>>> example2.member
1
>>> get_method(example2,'member')()
u'Hello World'
Responsible for managing connections to the JavaGateway.
This implementation is thread-safe and connections are created on-demand. This means that Py4J-Python can be accessed by multiple threads and messages are sent to and processed concurrently by the Java Gateway.
When creating a custom JavaGateway, it is recommended to pass an instance of CommChannelFactory instead of a CommChannel: both have the same interface, but the factory supports multiple threads and connections, which is essential when using callbacks.
Parameters: |
|
---|
Closes all currently opened communication channels.
This operation is not thread safe and is only a best effort strategy to close active channels. All channels are guaranteed to be closed only if no other thread is accessing the factory and no call is pending.
Sends a command to the JVM. This method is not intended to be called directly by Py4J users: it is usually called by JavaMember instances.
Parameter: | command – the string command to send to the JVM. The command must follow the Py4J protocol. |
---|---|
Return type: | the string answer received from the JVM. The answer follows the Py4J protocol. |
Default communication channel (socket based) responsible for communicating with the Java Virtual Machine.
Parameters: |
|
---|
Sends a command to the JVM. This method is not intended to be called directly by Py4J users: it is usually called by JavaMember instances.
Parameter: | command – the string command to send to the JVM. The command must follow the Py4J protocol. |
---|---|
Return type: | the string answer received from the JVM. The answer follows the Py4J protocol. |
Exception thrown when a problem occurs with Py4J.
Parameter: | value – the error message |
---|
Represents a Java object from which you can call methods or access fields.
Parameters: |
|
---|
A JavaClass represents a Java Class from which static members can be retrieved. JavaClass instances are also needed to initialize an array.
Usually, JavaClass are not initialized using their constructor, but they are created while accessing the jvm property of a gateway, e.g., gateway.jvm.java.lang.String.
A JavaPackage represents part of a Java package from which Java classes can be accessed.
Usually, JavaPackage are not initialized using their constructor, but they are created while accessing the jvm property of a gateway, e.g., gateway.jvm.java.lang.
The following two functions get be used to get a particular field or method when fields and methods in a Java class have the same name:
Retrieves the field named field_name from the java_object.
This function is useful when auto_field=false in a gateway or Java object.
Parameters: |
|
---|
Retrieves a reference to the method of an object.
This function is useful when auto_field=true and an instance field has the same name as a method. The full signature of the method is not required: it is determined when the method is called.
Parameters: |
|
---|
The following functions can be used to extend Py4J (e.g., to create new commands):
Replaces new line characters by a backslash followed by a n.
Backslashes are also escaped by another backslash.
Parameter: | original – the string to escape |
---|---|
Return type: | an escaped string |
Replaces escaped characters by unescaped characters.
For example, double backslashes are replaced by a single backslash.
Parameter: | escaped – the escaped string |
---|---|
Return type: | the original string |
Converts a Python object into a string representation respecting the Py4J protocol.
For example, the integer 1 is converted to u’i1’
Parameter: | parameter – the object to convert |
---|---|
Return type: | the string representing the command part |
Converts an answer received from the Java gateway into a Python object.
For example, string representation of integers are converted to Python integer, string representation of objects are converted to JavaObject instances, etc.
Parameters: |
|
---|