com.perforce.p4java.server
Class ServerFactory

java.lang.Object
  com.perforce.p4java.server.ServerFactory

public class ServerFactory
extends java.lang.Object

The main P4Java server factory class. This class is used to obtain an IServer interface onto a particular Perforce server using a specific (or default) protocol. Usage is described below with the getServer method.

Field Summary

static java.lang.String	DEFAULT_PROTOCOL_NAME Default protocol name, i.e.
static java.lang.String	DEFAULT_PROTOCOL_SPEC The pseudo-protocol used in URIs to signal that the factory should make its own decision about what protocol and server to use.
static java.lang.String	TRACE_PREFIX

Constructor Summary

ServerFactory()

Method Summary

static java.util.List<IServerImplMetadata>	getAvailableImplementationMetadata() Return a non-null list of implementation metadata about available IServer implementations.
static ISystemFileCommandsHelper	getRpcFileSystemHelper() Return the current SystemFileCommands helper, if any.
static IServer	getServer(java.lang.String serverUriString, java.util.Properties props) Return an IServer interface onto an underlying Perforce server at the host address specified by serverUriString using the protocol implementation and passed-in properties.
static IServer	getServer(java.net.URI serverUrl, java.util.Properties props) Deprecated. as of the 2009.2 release, use the getServer(String, Properties) method due to that Java's URI class does not accept hostnames with anything other than alphanumeric characters: even common hostnames like "perforce_p" will fail, often silently.
static void	setRpcFileSystemHelper(ISystemFileCommandsHelper fsCmdHelper) Register an ISystemFileCommandsHelper for the RPC implementations.

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 java.lang.String TRACE_PREFIX

See Also:

Constant Field Values

DEFAULT_PROTOCOL_SPEC

public static final java.lang.String DEFAULT_PROTOCOL_SPEC

The pseudo-protocol used in URIs to signal that the factory should make its own decision about what protocol and server to use.

See Also:

Constant Field Values

DEFAULT_PROTOCOL_NAME

public static final java.lang.String DEFAULT_PROTOCOL_NAME

Default protocol name, i.e. the name used when the protocol name is specified as "p4java" in a suitable URL. Currently it always maps to the native RPC implementation, but this is not guaranteed.

See Also:

Constant Field Values

Constructor Detail

ServerFactory

public ServerFactory()

Method Detail

getAvailableImplementationMetadata

public static java.util.List<IServerImplMetadata> getAvailableImplementationMetadata()

Return a non-null list of implementation metadata about available IServer implementations. This can be useful for presenting implementation choices to end users, or for debugging, etc.

getServer

public static IServer getServer(java.lang.String serverUriString,
                                java.util.Properties props)
                         throws java.net.URISyntaxException,
                                ConnectionException,
                                NoSuchObjectException,
                                ConfigException,
                                ResourceException

Return an IServer interface onto an underlying Perforce server at the host address specified by serverUriString using the protocol implementation and passed-in properties. Note that we use the term "URL" here a lot when we typically mean "URI"; this is mostly done to pre-empt confusion, but we may tighten usage up a lot over time.

The format of the server URI string is protocol + "://" + hostaddr [+ ":" + port] [+ queryString], e.g. "p4java://server.perforce.com:1666" or "p4java://192.168.1.12:999" or "p4jrpc://play.perforce.com:1199?progName=p4javaTest21&progVersion=Alpha203B". The protocol, port, and hostaddr fields can't be missing, but the port and hostaddr fields can be anything acceptable to the protocol, e.g. typically something like an IP address or hostname coupled with a port number.

The protocol part specifies which network implementation to use; the value "p4java" (DEFAULT_PROTOCOL_NAME) will tell the factory to use the default protocol, the details of which are not spelled out here, and which should always be used unless you have good reason to use an alternative (other protocol part values are possible, but should not generally be used unless suggested by Perforce support staff).

For advanced users, the optional queryString part can be used to set P4Java properties from the URI; these override any correspondingly-named properties sent programmatically through the props parameter (see next paragraph). These URI query strings are not interpreted, but are simply put as-is into the properties passed to the individual server implementation class. Note: this method does not do any query string replacement of things like %20 to spaces, etc. (this really isn't needed here as the query parts are passed as-is to the underlying implementation(s)).

The props argument can be used to pass in any protocol-specific properties; these are typically described in usage or implementation notes supplied elsewhere, and are not typically used by end-users.

IServer objects returned by this method may have been retrieved from a cache of previously-used objects, but they are guaranteed to be ready for use by the consumer, and to be for that consumer's exclusive use only.

Parameters:

serverUriString - non-null server address in URI form.

props - protocol-specific properties; may be null

Returns:

a non-null IServer object ready for use by the consumer.

Throws:

java.net.URISyntaxException - if the passed-in URI string does not conform to the Perforce URI specs detailed above.

ConnectionException - if the factory is unable to connect to the server named by serverUrl

NoSuchObjectException - if no implementation class can be found for the protocol specified in the passed-in URI protocol (scheme part);

ConfigException - if the underlying protocol supplier detects a misconfiguration

ResourceException - if the factory does not have the resources available to service the request

getServer

@Deprecated
public static IServer getServer(java.net.URI serverUrl,
                                           java.util.Properties props)
                         throws ConnectionException,
                                NoSuchObjectException,
                                ConfigException,
                                ResourceException,
                                java.net.URISyntaxException

Deprecated. as of the 2009.2 release, use the getServer(String, Properties) method due to that Java's URI class does not accept hostnames with anything other than alphanumeric characters: even common hostnames like "perforce_p" will fail, often silently.

Deprecated way to get an IServer object -- see getServer(String, Properties) for the correct way to get a server.

Parameters:

serverUrl - non-null server URI in the format described above

props - protocol-specific properties; may be null

Returns:

a non-null IServer object ready for use by the consumer.

Throws:

ConnectionException - if the factory is unable to connect to the server named by serverUrl

NoSuchObjectException - if no implementation class can be found for the protocol specified in the passed-in URI protocol (scheme part);

ConfigException - if the underlying protocol supplier detects a misconfiguration

ResourceException - if the factory does not have the resources available to service the request

java.net.URISyntaxException - if the passed-in URI is malformed.

setRpcFileSystemHelper

public static void setRpcFileSystemHelper(ISystemFileCommandsHelper fsCmdHelper)

Register an ISystemFileCommandsHelper for the RPC implementations. See the documentation for the ISystemFileCommandsHelper interface for more semantic and usage details.

Helper classes are needed for certain hosted implementations and for some JDK 5 installations, and are shared across an entire instance of P4Java. Please do not register a helper class unless you know what you're doing and you're OK with the dire consequences of getting a helper class implementation wrong.

Note that if the fsCmdHelper parameter is null, the default internal implementation will be used, which is usually fine for JDK 6 systems.

Parameters:

fsCmdHelper - file helper interface implementation; if null, use the JVM default implementation(s).

See Also:

ISystemFileCommandsHelper

getRpcFileSystemHelper

public static ISystemFileCommandsHelper getRpcFileSystemHelper()

Return the current SystemFileCommands helper, if any.