com.perforce.p4java.option
Class UsageOptions

java.lang.Object
  com.perforce.p4java.option.UsageOptions

public class UsageOptions
extends Object

Global server usage options class.

Intended to implement some of the options described in the main Perforce p4 usage and p4 undoc documentation on a per-IOptionsServer object basis, and also implements some of the broader environment settings (such as the client name used by the P4Java server implementation when no client has been associated with the server).

The UsageOptions object associated with a server is read and used for a small number of usage values (currently programName, programVersion, unsetUserName, and unsetClientName) each time a command is issued to the corresponding Perforce server, so updates to the UsageOptions object and / or any associated Properties object will be reflected at the next command execution except where noted. Note that this means that UsageOption objects shared between multiple servers are sensitive to such changes, and that changes that occur when a server is processing command requests may cause unexpected results.

A UsageOption object is associated with a server instance when the server is issued by the server factory; this can be the default object or one passed-in to the server factory specifically for that server.

Note that the UsageOptions class should be used with some care as the possible side effects of setting some of the usage parameters to the wrong value can lead to unexpected or odd behaviour.

WORKING_DIRECTORY_PROPNAME

public static final String WORKING_DIRECTORY_PROPNAME

The name of the system property used to determine the JVM's current working directory.

See Also:

Constant Field Values

props

protected Properties props

Properties object used to get default field values from. Note that these properties are potentially accessed for each command, so any changes in the properties will be reflected the next time the options object is used.

programName

protected String programName

If not null, will be used to identify the P4Java application's program name to the Perforce server.

programVersion

protected String programVersion

If not null, will be used to identify the P4Java application's program version to the Perforce server.

workingDirectory

protected String workingDirectory

If not null, this specifies the Perforce server's idea of each command's working directory for the associated server object. Corresponds to the p4 -d usage option.

This affects all commands on the associated server from this point on, and the passed-in path should be both absolute and valid, otherwise strange errors may appear from the server. If workingDirectory is null, the Java VM's actual current working directory at the time this object is constructed is used instead (which is almost always a safe option unless you're using Perforce alt roots).

Note: no checking is done at any time for correctness (or otherwise) of the workingDirectory option.

hostName

protected String hostName

If not null, specifies the host name used by the server's commands. Set to null by the default constructor. Corresponds to the p4 -H usage option. HostName is not live -- that is, unlike many other UsageOption fields, its value is only read once when the associated server is created; subsequent changes will not be reflected in the associated server.

textLanguage

protected String textLanguage

If not null, use this field to tell the server which language to use in text messages it sends back to the client. Corresponds to the p4 -L option, with the same limitations. Set to null by the default constructor.

unsetUserName

protected String unsetUserName

What will be sent to the Perforce server with each command as the user name if no user name has been explicitly set for servers associated with this UsageOption.

unsetClientName

protected String unsetClientName

If set, this will be used as the name of the client when no client has actually been explicitly set for the associated server(s).

defaultWorkingDirectory

protected String defaultWorkingDirectory

Default working directory from the JVM to fall back to if not working directory is set on the usage options

UsageOptions

public UsageOptions(Properties props)

Default constructor. Sets props field then calls setFieldDefaults to set appropriate field default values; otherwise does nothing.

UsageOptions

public UsageOptions(Properties props,
                    String programName,
                    String programVersion,
                    String workingDirectory,
                    String hostName,
                    String textLanguage,
                    String unsetUserName,
                    String noClientName)

Explicit value constructor. After setting any values explicitly, calls setFieldDefaults() to tidy up any still-null fields that shouldn't be null.

setFieldDefaults

protected void setFieldDefaults(Properties props)

Set any non-null default values when the object is constructed. Basically, this means running down the fields and if a field is null and it's not a field that should have a null default value, calling the corresponding getXXXXDefault method.

Fields set here: workingDirectory.

getProgramNameDefault

protected String getProgramNameDefault(Properties props)

Get a suitable default value for the programName field. This version tries to find a suitable value in the passed-in properties with the key PropertyDefs.PROG_NAME_KEY_SHORTFORM, then with the key PropertyDefs.PROG_NAME_KEY; if that comes up null, it uses the value of PropertyDefs.PROG_NAME_DEFAULT.

Returns:

non-null default programName value.

getProgramVersionDefault

protected String getProgramVersionDefault(Properties props)

Get a suitable default value for the programVersion field. This version tries to find a suitable value in the passed-in properties with the key PropertyDefs.PROG_VERSION_KEY_SHORTFORM, then with the key PropertyDefs.PROG_VERSION_KEY; if that comes up null, it uses the value of PropertyDefs.PROG_VERSION_DEFAULT.

Returns:

non-null default programVersion value.

getWorkingDirectoryDefault

protected String getWorkingDirectoryDefault(Properties props)

Get a suitable default value for the workingDirectory field. This is taken from the JVM's system properties using the WORKING_DIRECTORY_PROPNAME system properties key (which is normally user.dir).

Returns:

non-null working directory.

getUnsetUserNameDefault

protected String getUnsetUserNameDefault(Properties props)

Get a suitable default value for the unsetUserName field. This version returns the value of the property associated with the PropertyDefs.USER_UNSET_NAME_KEY if it exists, or PropertyDefs.USER_UNSET_NAME_DEFAULT if not.

Returns:

non-null default unsetUserName value.

getUnsetClientNameDefault

protected String getUnsetClientNameDefault(Properties props)

Get a suitable default value for the unsetClientName field. This version returns the value of the property associated with the PropertyDefs.CLIENT_UNSET_NAME_KEY if it exists, or PropertyDefs.CLIENT_UNSET_NAME_DEFAULT if not.

Returns:

non-null default unsetClientName value.

getProgramName

public String getProgramName()

Return the program name. The current program name is determined by first seeing if there's been one explicitly set in this options object; if so, it's returned, otherwise the associated properties are searched for a value with the key PropertyDefs.PROG_NAME_KEY_SHORTFORM, then with the key PropertyDefs.PROG_NAME_KEY; if that comes up null, it returns the value of PropertyDefs.PROG_NAME_DEFAULT.

setProgramName

public UsageOptions setProgramName(String programName)

getProgramVersion

public String getProgramVersion()

Return the program version. The current program version is determined by first seeing if there's been one explicitly set in this options object; if so, it's returned, otherwise the associated properties are searched for a value with the key PropertyDefs.PROG_VERSION_KEY_SHORTFORM, then with the key PropertyDefs.PROG_VERSION_KEY; if that comes up null, it returns the value of PropertyDefs.PROG_VERSION_DEFAULT.

setProgramVersion

public UsageOptions setProgramVersion(String programVersion)

getWorkingDirectory

public String getWorkingDirectory()

Return the current value of the working directory; this can be dynamically set explicitly using the setter method or implicitly when the object is constructed using the JVM's working directory as reflected in the System properties.

setWorkingDirectory

public UsageOptions setWorkingDirectory(String workingDirectory)

getHostName

public String getHostName()

setHostName

public UsageOptions setHostName(String hostName)

Set the host name. Calling this method has no effect at all after any associated server object is created.

getTextLanguage

public String getTextLanguage()

setTextLanguage

public UsageOptions setTextLanguage(String textLanguage)

getProps

public Properties getProps()

setProps

public UsageOptions setProps(Properties props)

getUnsetClientName

public String getUnsetClientName()

Return the unset client name. The current value is determined by first seeing if there's been one explicitly set in this options object; if so, it's returned; otherwise the associated properties are searched for a value with the key PropertyDefs.CLIENT_UNSET_NAME_KEY; if that comes up null, it returns the value of PropertyDefs.CLIENT_UNSET_NAME_DEFAULT.

setUnsetClientName

public UsageOptions setUnsetClientName(String unsetClientName)

getUnsetUserName

public String getUnsetUserName()

Return the unset user name. The current value is determined by first seeing if there's been one explicitly set in this options object; if so, it's returned; otherwise the associated properties are searched for a value with the key PropertyDefs.USER_UNSET_NAME_KEY; if that comes up null, it returns the value of PropertyDefs.USER_UNSET_NAME_DEFAULT.

setUnsetUserName

public UsageOptions setUnsetUserName(String unsetUserName)