Package py4j

Class Protocol

  • public class Protocol
extends java.lang.Object

    This class defines the protocol used to communicate between two virtual machines (e.g., Python and Java).

    Currently, the protocol requires type information (e.g., is this string an integer, an object reference or a boolean?) to be embedded with each command part. The rational is that the source virtual machine is usually better at determining the type of objects it sends.

    An input command is usually composed of:

    • A command name (e.g., c for call)
    • Optionally, a sub command name (e.g., 'a' for concatenate in the list command)
    • A list of command parts (e.g., the name of a method, the value of a parameter, etc.)
    • The End of Command marker (e)

    The various parts of a command are separated by \n characters. These characters are automatically escaped and unescaped in Strings on both sides (Java and Python).

    An output command is usually composed of:

    • A success or error code (y for yes, x for exception)
    • A return value (e.g., n for null, v for void, or any other value like a String)

    This class should be used only if the user creates new commands.

    • Constructor Detail

      • Protocol

        public Protocol()

    • Method Detail

      • encodeBytes

        public static java.lang.String encodeBytes​(byte[] bytes)

        Transform the byte array into Base64 characters.

        Parameters:
        bytes -
        Returns:

      • getBoolean

        public static final boolean getBoolean​(java.lang.String commandPart)

        Assumes that commandPart is not empty.

        Parameters:
        commandPart -
        Returns:
        The boolean value corresponding to this command part.

      • getBytes

        public static final byte[] getBytes​(java.lang.String commandPart)

        Assumes that commandPart is not empty.

        Parameters:
        commandPart -
        Returns:
        The byte array corresponding to this command part.

      • getDecimal

        public static final java.math.BigDecimal getDecimal​(java.lang.String commandPart)

        Assumes that commandPart is not empty.

        Parameters:
        commandPart -
        Returns:
        The decimal value corresponding to this command part.

      • getDouble

        public static final double getDouble​(java.lang.String commandPart)

        Assumes that commandPart is not empty.

        Parameters:
        commandPart -
        Returns:
        The double value corresponding to this command part.

      • getInteger

        public static final int getInteger​(java.lang.String commandPart)

        Assumes that commandPart is not empty.

        Parameters:
        commandPart -
        Returns:
        The integer value corresponding to this command part.

      • getLong

        public static final long getLong​(java.lang.String commandPart)

        Assumes that commandPart is not empty.

        Parameters:
        commandPart -
        Returns:
        The long value corresponding to this command part.

      • getMemberOutputCommand

        public static final java.lang.String getMemberOutputCommand​(char memberType)

      • getMemberOutputCommand

        public static final java.lang.String getMemberOutputCommand​(char memberType,
                                                            java.lang.String fqn)

      • getNoSuchFieldOutputCommand

        public static java.lang.String getNoSuchFieldOutputCommand()

      • getNull

        public static final java.lang.Object getNull​(java.lang.String commandPart)

        Method provided for consistency. Just returns null.

        Parameters:
        commandPart -
        Returns:
        null.

      • getObject

        public static final java.lang.Object getObject​(java.lang.String commandPart,
                                               Gateway gateway)

      • getOutputCommand

        public static final java.lang.String getOutputCommand​(ReturnObject rObject)

      • getOutputErrorCommand

        public static final java.lang.String getOutputErrorCommand()

      • getOutputErrorCommand

        public static final java.lang.String getOutputErrorCommand​(java.lang.String errorMessage)

      • getOutputErrorCommand

        public static final java.lang.String getOutputErrorCommand​(java.lang.Throwable throwable)

      • getOutputFatalErrorCommand

        public static final java.lang.String getOutputFatalErrorCommand​(java.lang.Throwable throwable)

      • getOutputVoidCommand

        public static final java.lang.String getOutputVoidCommand()

      • getAuthCommand

        public static final java.lang.String getAuthCommand​(java.lang.String authToken)

      • getPrimitiveType

        public static char getPrimitiveType​(java.lang.Object primitiveObject)

      • getPythonProxy

        public static java.lang.Object getPythonProxy​(java.lang.String commandPart,
                                              Gateway gateway)

        Assumes that commandPart is not empty.

        Parameters:
        commandPart -
        Returns:
        A Python proxy specified in this command part.

      • getPythonProxyHandler

        public static java.lang.Object getPythonProxyHandler​(java.lang.ClassLoader classLoader,
                                                     java.lang.Class[] interfacesToImplement,
                                                     java.lang.String objectId,
                                                     Gateway gateway)
        Deprecated.

        Legacy method. Please use Gateway.createProxy.

        Parameters:
        classLoader -
        interfacesToImplement -
        objectId -
        gateway -
        Returns:

      • getReference

        public static final java.lang.Object getReference​(java.lang.String commandPart,
                                                  Gateway gateway)

        Assumes that commandPart is not empty.

        Parameters:
        commandPart -
        Returns:
        The object referenced in this command part.

      • getReturnValue

        public static final java.lang.Object getReturnValue​(java.lang.String returnMessage,
                                                    Gateway gateway)
                                             throws java.lang.Throwable
        Throws:
        java.lang.Throwable

      • getRootThrowable

        public static final java.lang.Throwable getRootThrowable​(java.lang.Throwable throwable,
                                                         boolean skipInvocation)

      • getString

        public static final java.lang.String getString​(java.lang.String commandPart)

        Assumes that commandPart is not empty.

        Parameters:
        commandPart -
        Returns:
        The reference contained in this command part.

      • getThrowableAsString

        public static final java.lang.String getThrowableAsString​(java.lang.Throwable throwable)

      • isBoolean

        public static final boolean isBoolean​(java.lang.String commandPart)

        Assumes that commandPart is not empty.

        Parameters:
        commandPart -
        Returns:
        True if the command part is a boolean

      • isReturnMessage

        public static final boolean isReturnMessage​(java.lang.String commandPart)
        Parameters:
        commandPart -
        Returns:
        True if the command part is a return message

      • isBytes

        public static final boolean isBytes​(java.lang.String commandPart)

        Assumes that commandPart is not empty.

        Parameters:
        commandPart -
        Returns:
        True if the command part is a byte array

      • isDecimal

        public static final boolean isDecimal​(java.lang.String commandPart)

        Assumes that commandPart is not empty.

        Parameters:
        commandPart -
        Returns:
        True if the command part is a decimal

      • isDouble

        public static final boolean isDouble​(java.lang.String commandPart)

        Assumes that commandPart is not empty.

        Parameters:
        commandPart -
        Returns:
        True if the command part is a double

      • isEmpty

        public static final boolean isEmpty​(java.lang.String commandPart)

      • isEnd

        public static final boolean isEnd​(java.lang.String commandPart)

        Assumes that commandPart is not empty.

        Parameters:
        commandPart -
        Returns:
        True if the command part is the end token

      • isError

        public static final boolean isError​(java.lang.String returnMessage)

        Assumes that commandPart is not null.

        Parameters:
        returnMessage -
        Returns:
        True if the return message is an error

      • isInteger

        public static final boolean isInteger​(java.lang.String commandPart)

        Assumes that commandPart is not empty.

        Parameters:
        commandPart -
        Returns:
        True if the command part is an integer

      • isLong

        public static final boolean isLong​(java.lang.String commandPart)

        Assumes that commandPart is not empty.

        Parameters:
        commandPart -
        Returns:
        True if the command part is a long

      • isNull

        public static final boolean isNull​(java.lang.String commandPart)

        Assumes that commandPart is not empty.

        Parameters:
        commandPart -
        Returns:
        True if the command part is null

      • isPythonProxy

        public static final boolean isPythonProxy​(java.lang.String commandPart)

        Assumes that commandPart is not empty.

        Parameters:
        commandPart -
        Returns:
        True if the command part is a python proxy

      • isReference

        public static final boolean isReference​(java.lang.String commandPart)

        Assumes that commandPart is not empty.

        Parameters:
        commandPart -
        Returns:
        True if the command part is a reference

      • isString

        public static final boolean isString​(java.lang.String commandPart)

        Assumes that commandPart is not empty.

        Parameters:
        commandPart -
        Returns:
        True if the command part is a reference