Package org.apache.hadoop.ipc

Class RPC

java.lang.Object

org.apache.hadoop.ipc.RPC

@LimitedPrivate({"Common","HDFS","MapReduce","Yarn"})
@Evolving
public class RPC
extends java.lang.Object

A simple RPC mechanism. A protocol is a Java interface. All parameters and return types must be one of:

• a primitive type, boolean, byte, char, short, int, long, float, double, or void; or
• a String; or
• a Writable; or
• an array of the above types

All methods in the protocol should throw only IOException. No field data of the protocol instance is transmitted.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	RPC.Builder	Class to construct instances of RPC server with specific options.
static class	RPC.RpcKind
static class	RPC.Server	An RPC Server.
static class	RPC.VersionMismatch	A version mismatch for the RPC protocol.

Method Summary

Modifier and Type	Method	Description
static Client.ConnectionId	getConnectionIdForProxy(java.lang.Object proxy)	Return the connection ID of the given object.
static java.lang.String	getProtocolName(java.lang.Class<?> protocol)	Get the protocol name.
static <T> ProtocolProxy<T>	getProtocolProxy(java.lang.Class<T> protocol, long clientVersion, java.net.InetSocketAddress addr, Configuration conf)	Get a protocol proxy that contains a proxy connection to a remote server and a set of methods that are supported by the server
static <T> ProtocolProxy<T>	getProtocolProxy(java.lang.Class<T> protocol, long clientVersion, java.net.InetSocketAddress addr, Configuration conf, javax.net.SocketFactory factory)	Get a protocol proxy that contains a proxy connection to a remote server and a set of methods that are supported by the server.
static <T> ProtocolProxy<T>	getProtocolProxy(java.lang.Class<T> protocol, long clientVersion, java.net.InetSocketAddress addr, UserGroupInformation ticket, Configuration conf, javax.net.SocketFactory factory)	Get a protocol proxy that contains a proxy connection to a remote server and a set of methods that are supported by the server
static <T> ProtocolProxy<T>	getProtocolProxy(java.lang.Class<T> protocol, long clientVersion, java.net.InetSocketAddress addr, UserGroupInformation ticket, Configuration conf, javax.net.SocketFactory factory, int rpcTimeout, RetryPolicy connectionRetryPolicy)	Get a protocol proxy that contains a proxy connection to a remote server and a set of methods that are supported by the server.
static <T> ProtocolProxy<T>	getProtocolProxy(java.lang.Class<T> protocol, long clientVersion, java.net.InetSocketAddress addr, UserGroupInformation ticket, Configuration conf, javax.net.SocketFactory factory, int rpcTimeout, RetryPolicy connectionRetryPolicy, java.util.concurrent.atomic.AtomicBoolean fallbackToSimpleAuth)	Get a protocol proxy that contains a proxy connection to a remote server and a set of methods that are supported by the server.
static <T> ProtocolProxy<T>	getProtocolProxy(java.lang.Class<T> protocol, long clientVersion, java.net.InetSocketAddress addr, UserGroupInformation ticket, Configuration conf, javax.net.SocketFactory factory, int rpcTimeout, RetryPolicy connectionRetryPolicy, java.util.concurrent.atomic.AtomicBoolean fallbackToSimpleAuth, AlignmentContext alignmentContext)	Get a protocol proxy that contains a proxy connection to a remote server and a set of methods that are supported by the server.
static <T> ProtocolProxy<T>	getProtocolProxy(java.lang.Class<T> protocol, long clientVersion, Client.ConnectionId connId, Configuration conf, javax.net.SocketFactory factory)	Get a protocol proxy that contains a proxy connection to a remote server and a set of methods that are supported by the server.
static <T> ProtocolProxy<T>	getProtocolProxy(java.lang.Class<T> protocol, long clientVersion, Client.ConnectionId connId, Configuration conf, javax.net.SocketFactory factory, AlignmentContext alignmentContext)	Get a protocol proxy that contains a proxy connection to a remote server and a set of methods that are supported by the server.
static long	getProtocolVersion(java.lang.Class<?> protocol)	Get the protocol version from protocol class.
static <T> T	getProxy(java.lang.Class<T> protocol, long clientVersion, java.net.InetSocketAddress addr, Configuration conf)	Construct a client-side proxy object with the default SocketFactory.
static <T> T	getProxy(java.lang.Class<T> protocol, long clientVersion, java.net.InetSocketAddress addr, Configuration conf, javax.net.SocketFactory factory)	Construct a client-side proxy object that implements the named protocol, talking to a server at the named address.
static <T> T	getProxy(java.lang.Class<T> protocol, long clientVersion, java.net.InetSocketAddress addr, UserGroupInformation ticket, Configuration conf, javax.net.SocketFactory factory)	Construct a client-side proxy object that implements the named protocol, talking to a server at the named address.
static <T> T	getProxy(java.lang.Class<T> protocol, long clientVersion, java.net.InetSocketAddress addr, UserGroupInformation ticket, Configuration conf, javax.net.SocketFactory factory, int rpcTimeout)	Construct a client-side proxy that implements the named protocol, talking to a server at the named address.
static int	getRpcTimeout(Configuration conf)	Get the RPC time from configuration; If not set in the configuration, return the default value.
static java.net.InetSocketAddress	getServerAddress(java.lang.Object proxy)
static void	setProtocolEngine(Configuration conf, java.lang.Class<?> protocol, java.lang.Class<?> engine)	Set a protocol to use a non-default RpcEngine if one is not specified in the configuration.
static void	stopProxy(java.lang.Object proxy)	Stop the proxy.
static <T> ProtocolProxy<T>	waitForProtocolProxy(java.lang.Class<T> protocol, long clientVersion, java.net.InetSocketAddress addr, Configuration conf)	Get a protocol proxy that contains a proxy connection to a remote server and a set of methods that are supported by the server.
static <T> ProtocolProxy<T>	waitForProtocolProxy(java.lang.Class<T> protocol, long clientVersion, java.net.InetSocketAddress addr, Configuration conf, int rpcTimeout, RetryPolicy connectionRetryPolicy, long timeout)	Get a protocol proxy that contains a proxy connection to a remote server and a set of methods that are supported by the server.
static <T> ProtocolProxy<T>	waitForProtocolProxy(java.lang.Class<T> protocol, long clientVersion, java.net.InetSocketAddress addr, Configuration conf, long connTimeout)	Get a protocol proxy that contains a proxy connection to a remote server and a set of methods that are supported by the server
static <T> T	waitForProxy(java.lang.Class<T> protocol, long clientVersion, java.net.InetSocketAddress addr, Configuration conf)	Get a proxy connection to a remote server.
static <T> T	waitForProxy(java.lang.Class<T> protocol, long clientVersion, java.net.InetSocketAddress addr, Configuration conf, int rpcTimeout, long timeout)	Get a proxy connection to a remote server.
static <T> T	waitForProxy(java.lang.Class<T> protocol, long clientVersion, java.net.InetSocketAddress addr, Configuration conf, long connTimeout)	Get a proxy connection to a remote server.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getProtocolName

public static java.lang.String getProtocolName(java.lang.Class<?> protocol)

Get the protocol name. If the protocol class has a ProtocolAnnotation, then get the protocol name from the annotation; otherwise the class name is the protocol name.

Parameters:

protocol - input protocol.

Returns:

protocol name.

getProtocolVersion

public static long getProtocolVersion(java.lang.Class<?> protocol)

Get the protocol version from protocol class. If the protocol class has a ProtocolAnnotation, then get the protocol version from the annotation; otherwise get it from the versionID field of the protocol class.

Parameters:

protocol - input protocol.

Returns:

ProtocolVersion.

setProtocolEngine

public static void setProtocolEngine(Configuration conf,
                                     java.lang.Class<?> protocol,
                                     java.lang.Class<?> engine)

Set a protocol to use a non-default RpcEngine if one is not specified in the configuration.

Parameters:

conf - configuration to use

protocol - the protocol interface

engine - the RpcEngine impl

waitForProxy

public static <T> T waitForProxy(java.lang.Class<T> protocol,
                                 long clientVersion,
                                 java.net.InetSocketAddress addr,
                                 Configuration conf)
                          throws java.io.IOException

Get a proxy connection to a remote server.

Type Parameters:

T - Generics Type T.

Parameters:

protocol - protocol class

clientVersion - client version

addr - remote address

conf - configuration to use

Returns:

the proxy

Throws:

java.io.IOException - if the far end through a RemoteException

waitForProtocolProxy

public static <T> ProtocolProxy<T> waitForProtocolProxy(java.lang.Class<T> protocol,
                                                        long clientVersion,
                                                        java.net.InetSocketAddress addr,
                                                        Configuration conf)
                                                 throws java.io.IOException

Get a protocol proxy that contains a proxy connection to a remote server and a set of methods that are supported by the server.

Type Parameters:

T - Generics Type T.

Parameters:

protocol - protocol class

clientVersion - client version

addr - remote address

conf - configuration to use

Returns:

the protocol proxy

Throws:

java.io.IOException - if the far end through a RemoteException

waitForProxy

public static <T> T waitForProxy(java.lang.Class<T> protocol,
                                 long clientVersion,
                                 java.net.InetSocketAddress addr,
                                 Configuration conf,
                                 long connTimeout)
                          throws java.io.IOException

Get a proxy connection to a remote server.

Type Parameters:

T - Generics Type T.

Parameters:

protocol - protocol class

clientVersion - client version

addr - remote address

conf - configuration to use

connTimeout - time in milliseconds before giving up

Returns:

the proxy

Throws:

java.io.IOException - if the far end through a RemoteException

waitForProtocolProxy

public static <T> ProtocolProxy<T> waitForProtocolProxy(java.lang.Class<T> protocol,
                                                        long clientVersion,
                                                        java.net.InetSocketAddress addr,
                                                        Configuration conf,
                                                        long connTimeout)
                                                 throws java.io.IOException

Get a protocol proxy that contains a proxy connection to a remote server and a set of methods that are supported by the server

Type Parameters:

T - Generics Type T.

Parameters:

protocol - protocol class

clientVersion - client version

addr - remote address

conf - configuration to use

connTimeout - time in milliseconds before giving up

Returns:

the protocol proxy

Throws:

java.io.IOException - if the far end through a RemoteException

waitForProxy

public static <T> T waitForProxy(java.lang.Class<T> protocol,
                                 long clientVersion,
                                 java.net.InetSocketAddress addr,
                                 Configuration conf,
                                 int rpcTimeout,
                                 long timeout)
                          throws java.io.IOException

Get a proxy connection to a remote server.

Type Parameters:

T - Generics Type T.

Parameters:

protocol - protocol class

clientVersion - client version

addr - remote address

conf - configuration to use

rpcTimeout - timeout for each RPC

timeout - time in milliseconds before giving up

Returns:

the proxy

Throws:

java.io.IOException - if the far end through a RemoteException

waitForProtocolProxy

public static <T> ProtocolProxy<T> waitForProtocolProxy(java.lang.Class<T> protocol,
                                                        long clientVersion,
                                                        java.net.InetSocketAddress addr,
                                                        Configuration conf,
                                                        int rpcTimeout,
                                                        RetryPolicy connectionRetryPolicy,
                                                        long timeout)
                                                 throws java.io.IOException

Get a protocol proxy that contains a proxy connection to a remote server and a set of methods that are supported by the server.

Type Parameters:

T - Generics Type.

Parameters:

protocol - protocol class

clientVersion - client version

addr - remote address

conf - configuration to use

rpcTimeout - timeout for each RPC

connectionRetryPolicy - input connectionRetryPolicy.

timeout - time in milliseconds before giving up

Returns:

the proxy

Throws:

java.io.IOException - if the far end through a RemoteException.

getProxy

public static <T> T getProxy(java.lang.Class<T> protocol,
                             long clientVersion,
                             java.net.InetSocketAddress addr,
                             Configuration conf,
                             javax.net.SocketFactory factory)
                      throws java.io.IOException

Construct a client-side proxy object that implements the named protocol, talking to a server at the named address.

Type Parameters:

T - Generics Type T.

Parameters:

protocol - input protocol.

clientVersion - input clientVersion.

addr - input addr.

conf - input Configuration.

factory - input factory.

Returns:

proxy.

Throws:

java.io.IOException - raised on errors performing I/O.

getProtocolProxy

public static <T> ProtocolProxy<T> getProtocolProxy(java.lang.Class<T> protocol,
                                                    long clientVersion,
                                                    java.net.InetSocketAddress addr,
                                                    Configuration conf,
                                                    javax.net.SocketFactory factory)
                                             throws java.io.IOException

Get a protocol proxy that contains a proxy connection to a remote server and a set of methods that are supported by the server.

Type Parameters:

T - Generics Type T.

Parameters:

protocol - protocol class

clientVersion - client version

addr - remote address

conf - configuration to use

factory - socket factory

Returns:

the protocol proxy

Throws:

java.io.IOException - if the far end through a RemoteException

getProxy

public static <T> T getProxy(java.lang.Class<T> protocol,
                             long clientVersion,
                             java.net.InetSocketAddress addr,
                             UserGroupInformation ticket,
                             Configuration conf,
                             javax.net.SocketFactory factory)
                      throws java.io.IOException

Construct a client-side proxy object that implements the named protocol, talking to a server at the named address.

Type Parameters:

T - Generics Type T.

Parameters:

protocol - input protocol.

clientVersion - input clientVersion.

addr - input addr.

ticket - input tocket.

conf - input conf.

factory - input factory.

Returns:

the protocol proxy.

Throws:

java.io.IOException - raised on errors performing I/O.

getProtocolProxy

public static <T> ProtocolProxy<T> getProtocolProxy(java.lang.Class<T> protocol,
                                                    long clientVersion,
                                                    java.net.InetSocketAddress addr,
                                                    UserGroupInformation ticket,
                                                    Configuration conf,
                                                    javax.net.SocketFactory factory)
                                             throws java.io.IOException

Get a protocol proxy that contains a proxy connection to a remote server and a set of methods that are supported by the server

Type Parameters:

T - Generics Type T.

Parameters:

protocol - protocol class

clientVersion - client version

addr - remote address

ticket - user group information

conf - configuration to use

factory - socket factory

Returns:

the protocol proxy

Throws:

java.io.IOException - if the far end through a RemoteException

getProtocolProxy

public static <T> ProtocolProxy<T> getProtocolProxy(java.lang.Class<T> protocol,
                                                    long clientVersion,
                                                    Client.ConnectionId connId,
                                                    Configuration conf,
                                                    javax.net.SocketFactory factory)
                                             throws java.io.IOException

Get a protocol proxy that contains a proxy connection to a remote server and a set of methods that are supported by the server.

Type Parameters:

T - Generics Type T

Parameters:

protocol - protocol class

clientVersion - client's version

connId - client connection identifier

conf - configuration

factory - socket factory

Returns:

the protocol proxy

Throws:

java.io.IOException - if the far end through a RemoteException

getProtocolProxy

public static <T> ProtocolProxy<T> getProtocolProxy(java.lang.Class<T> protocol,
                                                    long clientVersion,
                                                    Client.ConnectionId connId,
                                                    Configuration conf,
                                                    javax.net.SocketFactory factory,
                                                    AlignmentContext alignmentContext)
                                             throws java.io.IOException

Get a protocol proxy that contains a proxy connection to a remote server and a set of methods that are supported by the server.

Type Parameters:

T - Generics Type T

Parameters:

protocol - protocol class

clientVersion - client's version

connId - client connection identifier

conf - configuration

factory - socket factory

alignmentContext - StateID alignment context

Returns:

the protocol proxy

Throws:

java.io.IOException - if the far end through a RemoteException

getProxy

public static <T> T getProxy(java.lang.Class<T> protocol,
                             long clientVersion,
                             java.net.InetSocketAddress addr,
                             UserGroupInformation ticket,
                             Configuration conf,
                             javax.net.SocketFactory factory,
                             int rpcTimeout)
                      throws java.io.IOException

Construct a client-side proxy that implements the named protocol, talking to a server at the named address.

Type Parameters:

T - Generics Type T.

Parameters:

protocol - protocol

clientVersion - client's version

addr - server address

ticket - security ticket

conf - configuration

factory - socket factory

rpcTimeout - max time for each rpc; 0 means no timeout

Returns:

the proxy

Throws:

java.io.IOException - if any error occurs

getProtocolProxy

public static <T> ProtocolProxy<T> getProtocolProxy(java.lang.Class<T> protocol,
                                                    long clientVersion,
                                                    java.net.InetSocketAddress addr,
                                                    UserGroupInformation ticket,
                                                    Configuration conf,
                                                    javax.net.SocketFactory factory,
                                                    int rpcTimeout,
                                                    RetryPolicy connectionRetryPolicy)
                                             throws java.io.IOException

Get a protocol proxy that contains a proxy connection to a remote server and a set of methods that are supported by the server.

Type Parameters:

T - Generics Type T.

Parameters:

protocol - protocol

clientVersion - client's version

addr - server address

ticket - security ticket

conf - configuration

factory - socket factory

rpcTimeout - max time for each rpc; 0 means no timeout

connectionRetryPolicy - retry policy

Returns:

the proxy

Throws:

java.io.IOException - if any error occurs

getProtocolProxy

public static <T> ProtocolProxy<T> getProtocolProxy(java.lang.Class<T> protocol,
                                                    long clientVersion,
                                                    java.net.InetSocketAddress addr,
                                                    UserGroupInformation ticket,
                                                    Configuration conf,
                                                    javax.net.SocketFactory factory,
                                                    int rpcTimeout,
                                                    RetryPolicy connectionRetryPolicy,
                                                    java.util.concurrent.atomic.AtomicBoolean fallbackToSimpleAuth)
                                             throws java.io.IOException

Get a protocol proxy that contains a proxy connection to a remote server and a set of methods that are supported by the server.

Type Parameters:

T - Generics Type T.

Parameters:

protocol - protocol

clientVersion - client's version

addr - server address

ticket - security ticket

conf - configuration

factory - socket factory

rpcTimeout - max time for each rpc; 0 means no timeout

connectionRetryPolicy - retry policy

fallbackToSimpleAuth - set to true or false during calls to indicate if a secure client falls back to simple auth

Returns:

the proxy

Throws:

java.io.IOException - if any error occurs

getProtocolProxy

public static <T> ProtocolProxy<T> getProtocolProxy(java.lang.Class<T> protocol,
                                                    long clientVersion,
                                                    java.net.InetSocketAddress addr,
                                                    UserGroupInformation ticket,
                                                    Configuration conf,
                                                    javax.net.SocketFactory factory,
                                                    int rpcTimeout,
                                                    RetryPolicy connectionRetryPolicy,
                                                    java.util.concurrent.atomic.AtomicBoolean fallbackToSimpleAuth,
                                                    AlignmentContext alignmentContext)
                                             throws java.io.IOException

Get a protocol proxy that contains a proxy connection to a remote server and a set of methods that are supported by the server.

Type Parameters:

T - Generics Type T.

Parameters:

protocol - protocol

clientVersion - client's version

addr - server address

ticket - security ticket

conf - configuration

factory - socket factory

rpcTimeout - max time for each rpc; 0 means no timeout

connectionRetryPolicy - retry policy

fallbackToSimpleAuth - set to true or false during calls to indicate if a secure client falls back to simple auth

alignmentContext - state alignment context

Returns:

the proxy

Throws:

java.io.IOException - if any error occurs

getProxy

public static <T> T getProxy(java.lang.Class<T> protocol,
                             long clientVersion,
                             java.net.InetSocketAddress addr,
                             Configuration conf)
                      throws java.io.IOException

Construct a client-side proxy object with the default SocketFactory.

Type Parameters:

T - Generics Type T.

Parameters:

protocol - input protocol.

clientVersion - input clientVersion.

addr - input addr.

conf - input Configuration.

Returns:

a proxy instance

Throws:

java.io.IOException - if the thread is interrupted.

getServerAddress

public static java.net.InetSocketAddress getServerAddress(java.lang.Object proxy)

Parameters:

proxy - input proxy.

Returns:

Returns the server address for a given proxy.

getConnectionIdForProxy

public static Client.ConnectionId getConnectionIdForProxy(java.lang.Object proxy)

Return the connection ID of the given object. If the provided object is in fact a protocol translator, we'll get the connection ID of the underlying proxy object.

Parameters:

proxy - the proxy object to get the connection ID of.

Returns:

the connection ID for the provided proxy object.

getProtocolProxy

public static <T> ProtocolProxy<T> getProtocolProxy(java.lang.Class<T> protocol,
                                                    long clientVersion,
                                                    java.net.InetSocketAddress addr,
                                                    Configuration conf)
                                             throws java.io.IOException

Get a protocol proxy that contains a proxy connection to a remote server and a set of methods that are supported by the server

Type Parameters:

T - Generics Type T.

Parameters:

protocol - input protocol.

clientVersion - input clientVersion.

addr - input addr.

conf - input configuration.

Returns:

a protocol proxy

Throws:

java.io.IOException - if the thread is interrupted.

stopProxy

public static void stopProxy(java.lang.Object proxy)

Stop the proxy. Proxy must either implement Closeable or must have associated RpcInvocationHandler.

Parameters:

proxy - the RPC proxy object to be stopped

Throws:

HadoopIllegalArgumentException - if the proxy does not implement Closeable interface or does not have closeable InvocationHandler

getRpcTimeout

public static int getRpcTimeout(Configuration conf)

Get the RPC time from configuration; If not set in the configuration, return the default value.

Parameters:

conf - Configuration

Returns:

the RPC timeout (ms)