com.perforce.p4java.server
Class ServerFactory

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

public class ServerFactory
extends 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.

TRACE_PREFIX

public static final String TRACE_PREFIX

See Also:

Constant Field Values

DEFAULT_PROTOCOL_SPEC

public static final 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.

DEFAULT_PROTOCOL_NAME

public static final 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.

DEFAULT_SSL_PROTOCOL_NAME

public static final String DEFAULT_SSL_PROTOCOL_NAME

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

ZEROCONF_CLASS_NAME

public static final String ZEROCONF_CLASS_NAME

See Also:

Constant Field Values

ServerFactory

public ServerFactory()

getAvailableImplementationMetadata

public static 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(String serverUriString,
                                Properties props)
                         throws 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).

To connect to an SSL-enabled Perforce server, use one of the SSL protocols defined in the IServerAddress.Protocol enum (i.e. "p4javassl", "p4rpcssl" or "p4jrpcntsssl").

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:

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

getOptionsServer

public static IOptionsServer getOptionsServer(String serverUriString,
                                              Properties props)
                                       throws URISyntaxException,
                                              ConnectionException,
                                              NoSuchObjectException,
                                              ConfigException,
                                              ResourceException

Return an IOptionsServer onto an underlying Perforce server at the host address specified by serverUriString using the protocol implementation and passed-in properties and a default UsageOptions object.

Basically a convenience wrapper for calling the main getOptionsServer method with a null UsageOptions argument -- see that method's Javadoc for full documentation.

Parameters:

serverUriString - non-null server address in URI form.

props - protocol-specific properties; may be null

Returns:

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

Throws:

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

getOptionsServer

public static IOptionsServer getOptionsServer(String serverUriString,
                                              Properties props,
                                              UsageOptions opts)
                                       throws URISyntaxException,
                                              ConnectionException,
                                              NoSuchObjectException,
                                              ConfigException,
                                              ResourceException

Return an IOptionsServer interface onto an underlying Perforce server at the host address specified by serverUriString using the protocol implementation and passed-in properties and usage options. 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 "p4java://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).

To connect to an SSL-enabled Perforce server, use one of the SSL protocols defined in the IServerAddress.Protocol enum (i.e. "p4javassl", "p4rpcssl" or "p4jrpcntsssl").

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.

opts - UsageOptions object to be associated with the new server object specifying the server's usage options; if null, a new usage options object is constructed using the default UsageOptions constructor and associated default values using the passed-in properties object (if not null); this is then associated with the new server object.

Returns:

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

Throws:

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(URI serverUrl,
                                           Properties props)
                         throws ConnectionException,
                                NoSuchObjectException,
                                ConfigException,
                                ResourceException,
                                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

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.

getZeroconfServers

@Deprecated
public static List<ZeroconfServerInfo> getZeroconfServers()
                                                   throws ConfigException

Deprecated. As of release 2013.1, ZeroConf is no longer supported by the Perforce server 2013.1.

Return a list of Perforce servers registered locally with zeroconf at the time the method was called. See the Perforce knowledge base articles at http://kb.perforce.com/AdminTasks/Zeroconf for an introduction to Perforce zeroconf usage, and zeroconf.org for zeroconf in general.

This method uses the javax.jmdns JmDNS package (available through Sourceforge, etc.), and that package must be visible to the current class loader for this method to work. If the server factory is unable to find a suitable JmDNS package using the current class loader, this method will throw a ConfigException. The JmDNS package is not supplied with P4Java and must be downloaded and installed separately.

Note that zeroconf discovery can take some time (in the order of tens of seconds in some cases), and only works for local subnets, so the first call to this method may return nothing even though there's a suitable server out there on the same subnet. Subsequent calls are usually more successful.

Note also that we recommend you call the associated isZeroconfAvailable method first to check whether zeroconf is even available for this P4Java instance -- this can save a lot of overhead and / or annoying log messages.

Returns:

non-null (but possibly-empty) list of ZeroconfServerInfo objects for Perforce servers registered when this method is called.

Throws:

ConfigException - if the server factory can't load and use a suitable JmDNS zeroconf package using the current class loader.

isZeroConfAvailable

@Deprecated
public static boolean isZeroConfAvailable()

Deprecated. As of release 2013.1, ZeroConf is no longer supported by the Perforce server 2013.1.

Returns true if the server factory has a suitable zeroconf service browsing implementation available to it. Should probably be used at least once before calling the getZeroConfServers method to avoid unnecessary overhead.

Returns:

true iff zeroconf browsing services are available to the server factory.