com.perforce.p4java.impl.mapbased.rpc.connection
Class RpcConnection

java.lang.Object
  com.perforce.p4java.impl.mapbased.rpc.connection.RpcConnection

Direct Known Subclasses:

RpcStreamConnection

public abstract class RpcConnection
extends Object

Main abstract class for sending and receiving packets (etc.) to and from the Perforce server. There is currently only one known subclass, RpcStreamConnection, which implements the connection using java.io streams on top of sockets.

Note that charset conversion should never be necessary on connections to non-Unicode servers, as any bytes in the incoming stream that are marked as "text" should be interpreted as ASCII (seven or eight bits). Unfortunately, in Java land, there's no such thing as non-interpreted bytes -- bytes are converted to strings according to *some* charset or other (and Java uses UTF-16 as the native encoding for strings under the covers). This explains why we always do a conversion below -- if we didn't use an explicit "from" charset, the current JVM's charset would be used, which would quite probably be wrong. Similar observations apply for conversions in the other direction -- all conversions must be with an explicit charset in case the JVM's charset isn't the one we actually need.

Note that, in general, we "know" that the Perforce server on the other end of this connection is -- or should be -- a Unicode server by the fact that the incoming clientCharset is not null. This probably isn't infallible, but it's supposed to be true, so we use it as a proxy for IServer.supportsUnicode().

See http://computer.perforce.com/newwiki/index.php?title=P4Java_and_Charset_Support for a detailed discussion of P4Java and server charset issues...

Field Summary

protected Charset	clientCharset
protected RpcConnectionFlowControl	flowController
protected String	hostName
protected int	hostPort
protected boolean	isUnicodeServer
static Charset	NON_UNICODE_SERVER_CHARSET Charset assumed when the server is non in Unicode mode.
static String	NON_UNICODE_SERVER_CHARSET_NAME The name of the assumed non-Unicode server charset.
protected Properties	props
protected ServerStats	stats
static String	TRACE_PREFIX
static Charset	UNICODE_SERVER_CHARSET The charset used internally by a Perforce Unicode-enabled server.
static String	UNICODE_SERVER_CHARSET_NAME The name of the assumed Unicode server internal charset.
protected boolean	usingCompression

Constructor Summary

RpcConnection(String serverHost, int serverPort, Properties props, ServerStats stats, Charset clientCharset)
Create a Perforce RPC connection to a given host and port number pair.

Method Summary

abstract void	disconnect(RpcPacketDispatcher dispatcher) Disconnect this server.
Charset	getClientCharset()
RpcConnectionFlowControl	getFlowController()
String	getHostName()
int	getHostPort()
protected byte[]	getNormalizedBytes(String str) Encode the passed-in string properly for the server.
protected String	getNormalizedString(byte[] bytes) Decode the passed-in bytes from the server into a suitable string.
Properties	getProps()
abstract RpcPacket	getRpcPacket() Get the next RPC packet from the receive queue.
ServerStats	getStats()
abstract int	getSystemRecvBufferSize() Return the system (i.e.
abstract int	getSystemSendBufferSize() Return the system (i.e.
boolean	isUnicodeServer()
boolean	isUsingCompression()
byte[]	marshalPacketField(String key, Object value) Marshal a packet field into a key value byte array pair.
protected byte[]	marshalPacketValue(Object value) Marshal a packet field value onto a byte array and return that array.
abstract long	putRpcPacket(RpcPacket rpcPacket) Put a Perforce RPC packet onto the output stream.
abstract long	putRpcPackets(RpcPacket[] rpcPackets) Put an array of RPC packets.
void	setClientCharset(Charset charset)
void	setFlowController(RpcConnectionFlowControl flowController)
void	setHostName(String hostName)
void	setHostPort(int hostPort)
void	setProps(Properties props)
void	setStats(ServerStats stats)
void	setUnicodeServer(boolean isUnicodeServer)
void	setUsingCompression(boolean usingCompression)
void	useConnectionCompression() If called, will set this connection to use (GZIP) compression for all traffic on this connection from this point on.

Methods inherited from class java.lang.Object

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

Field Detail

TRACE_PREFIX

public static final String TRACE_PREFIX

See Also:

Constant Field Values

UNICODE_SERVER_CHARSET

public static final Charset UNICODE_SERVER_CHARSET

The charset used internally by a Perforce Unicode-enabled server. If a server is Unicode-enabled, then every non-binary RPC packet field is sent to and received from the Perforce server in this charset.

Do not change this unless you want all hell to break loose.

UNICODE_SERVER_CHARSET_NAME

public static final String UNICODE_SERVER_CHARSET_NAME

The name of the assumed Unicode server internal charset. Do not change this either.

NON_UNICODE_SERVER_CHARSET

public static final Charset NON_UNICODE_SERVER_CHARSET

Charset assumed when the server is non in Unicode mode. Do not change this field, either, unless you want problems...

NON_UNICODE_SERVER_CHARSET_NAME

public static final String NON_UNICODE_SERVER_CHARSET_NAME

The name of the assumed non-Unicode server charset. Do not change this either.

props

protected Properties props

flowController

protected RpcConnectionFlowControl flowController

stats

protected ServerStats stats

clientCharset

protected Charset clientCharset

hostName

protected String hostName

hostPort

protected int hostPort

usingCompression

protected boolean usingCompression

isUnicodeServer

protected boolean isUnicodeServer

Constructor Detail

RpcConnection

public RpcConnection(String serverHost,
                     int serverPort,
                     Properties props,
                     ServerStats stats,
                     Charset clientCharset)
              throws ConnectionException

Create a Perforce RPC connection to a given host and port number pair.

This method will also implicitly connect to the server. Note that new connections are never using connection compression -- this has to come as an explicit command from the server after the connection has been established.

Parameters:

serverHost - non-null Perforce server host name or IP address.

serverPort - Perforce server host port number.

props - if not null, use the Properties for any connection- or implementation-specific values (such as buffer sizes, etc.).

stats - if not null, attempt to fill in these connection stats appropriately.

clientCharset - if non-null, sets the connection's idea of what the current client charset is. If null, CharsetDefs.DEFAULT is used.

Throws:

ConnectionException - if any user-reportable error occurred under the covers.

Method Detail

disconnect

public abstract void disconnect(RpcPacketDispatcher dispatcher)
                         throws ConnectionException

Disconnect this server. Assumes the connection is quiescent -- no further sends or receives will be possible after this call, and only the output stream is flushed (no attempt is made to look at anything still on the wire coming in to the socket).

Throws:

ConnectionException

putRpcPacket

public abstract long putRpcPacket(RpcPacket rpcPacket)
                           throws ConnectionException

Put a Perforce RPC packet onto the output stream. The implementing method must make the appropriate charset translations and any other client- or server- (or whatever-) specific processing on the passed-in packet.

Returns the number of bytes actually sent to the Perforce server, which may not bear any relationship at all to the size of the passed-in packet.

Throws:

ConnectionException

putRpcPackets

public abstract long putRpcPackets(RpcPacket[] rpcPackets)
                            throws ConnectionException

Put an array of RPC packets. A convenience method wrapping putRpcPacket(packet) in the obvious way.

Throws:

ConnectionException

getRpcPacket

public abstract RpcPacket getRpcPacket()
                                throws ConnectionException

Get the next RPC packet from the receive queue. The implementing method must make the appropriate charset translations and any other client- or server- (or whatever-) specific processing on the packet returned from this method by the time it's returned.

Will wait until either a timeout occurs (if the stream's been set up appropriately), the underlying stream returns EOF or error, or we get a complete packet.

Throws:

ConnectionException

getSystemSendBufferSize

public abstract int getSystemSendBufferSize()

Return the system (i.e. underlying implementation) send buffer size.

getSystemRecvBufferSize

public abstract int getSystemRecvBufferSize()

Return the system (i.e. underlying implementation) receive buffer size.

marshalPacketField

public byte[] marshalPacketField(String key,
                                 Object value)

Marshal a packet field into a key value byte array pair. This must respect the relevant charset settings, which can be a little counter-intuitive or confusing.

marshalPacketValue

protected byte[] marshalPacketValue(Object value)

Marshal a packet field value onto a byte array and return that array.

For strings and similar types (e.g. StringBuilder, StringBuffer), we may need to do a translation to the server charset (normally UTF-8) before enbyteifying the underlying value. Other field types are sent as-is, and are assumed to have been encoded properly upstream (and are almost always just file contents).

Note: if the value object passed in is a ByteBuffer, it must have been flipped ready for use; this method will (of course) have predictable side effects on that ByteBuffer.

useConnectionCompression

public void useConnectionCompression()
                              throws ConnectionException

If called, will set this connection to use (GZIP) compression for all traffic on this connection from this point on. Can not be turned back off again. See the main P4 help documentation (and C++ API code) for "client compression" (etc.) for details.

Throws:

ConnectionException

getNormalizedBytes

protected byte[] getNormalizedBytes(String str)

Encode the passed-in string properly for the server. If the server is Unicode-enabled, this usually means converting to UTF-8 encoding for the stream. This can be a very CPU-intensive process...

FIXME: use proper encoding / decoding with error handling -- HR.

Parameters:

str -

Returns:

- normalized string

getNormalizedString

protected String getNormalizedString(byte[] bytes)

Decode the passed-in bytes from the server into a suitable string. In general, bytes from the server will be in ASCII (non-Unicode servers) or UTF-8 (Unicode servers), but there are exceptions.

FIXME: use proper encoding / decoding with error handling -- HR.

Parameters:

bytes -

Returns:

- normalized string

isUsingCompression

public boolean isUsingCompression()

getFlowController

public RpcConnectionFlowControl getFlowController()

setFlowController

public void setFlowController(RpcConnectionFlowControl flowController)

getProps

public Properties getProps()

setProps

public void setProps(Properties props)

getClientCharset

public Charset getClientCharset()

setClientCharset

public void setClientCharset(Charset charset)

getStats

public ServerStats getStats()

setStats

public void setStats(ServerStats stats)

getHostName

public String getHostName()

setHostName

public void setHostName(String hostName)

getHostPort

public int getHostPort()

setHostPort

public void setHostPort(int hostPort)

setUsingCompression

public void setUsingCompression(boolean usingCompression)

isUnicodeServer

public boolean isUnicodeServer()

setUnicodeServer

public void setUnicodeServer(boolean isUnicodeServer)