UsageOptions (p4java 2023.2.2581742 API)

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

```
public class UsageOptions
extends java.lang.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.

Field Summary

Fields
Modifier and Type	Field and Description
`protected java.lang.String`	`defaultWorkingDirectory` Default working directory from the JVM to fall back to if not working directory is set on the usage options
`protected java.lang.String`	`hostName` If not null, specifies the host name used by the server's commands.
`protected java.lang.String`	`programName` If not null, will be used to identify the P4Java application's program name to the Perforce server.
`protected java.lang.String`	`programVersion` If not null, will be used to identify the P4Java application's program version to the Perforce server.
`protected java.util.Properties`	`props` Properties object used to get default field values from.
`protected java.lang.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.
`protected java.lang.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).
`protected java.lang.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.
`static java.lang.String`	`WORKING_DIRECTORY_PROPNAME` The name of the system property used to determine the JVM's current working directory.
`protected java.lang.String`	`workingDirectory` If not null, this specifies the Perforce server's idea of each command's working directory for the associated server object.

Constructor Summary

Constructors
Constructor and Description
`UsageOptions(java.util.Properties props)` Default constructor.
`UsageOptions(java.util.Properties props, java.lang.String programName, java.lang.String programVersion, java.lang.String workingDirectory, java.lang.String hostName, java.lang.String textLanguage, java.lang.String unsetUserName, java.lang.String noClientName)` Explicit value constructor.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`java.lang.String`	`getHostName()`
`java.lang.String`	`getProgramName()` Return the program name.
`protected java.lang.String`	`getProgramNameDefault(java.util.Properties props)` Get a suitable default value for the programName field.
`java.lang.String`	`getProgramVersion()` Return the program version.
`protected java.lang.String`	`getProgramVersionDefault(java.util.Properties props)` Get a suitable default value for the programVersion field.
`java.util.Properties`	`getProps()`
`java.lang.String`	`getTextLanguage()`
`java.lang.String`	`getUnsetClientName()` Return the unset client name.
`protected java.lang.String`	`getUnsetClientNameDefault(java.util.Properties props)` Get a suitable default value for the unsetClientName field.
`java.lang.String`	`getUnsetUserName()` Return the unset user name.
`protected java.lang.String`	`getUnsetUserNameDefault(java.util.Properties props)` Get a suitable default value for the unsetUserName field.
`java.lang.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.
`protected java.lang.String`	`getWorkingDirectoryDefault(java.util.Properties props)` Get a suitable default value for the workingDirectory field.
`protected void`	`setFieldDefaults(java.util.Properties props)` Set any non-null default values when the object is constructed.
`UsageOptions`	`setHostName(java.lang.String hostName)` Set the host name.
`UsageOptions`	`setProgramName(java.lang.String programName)`
`UsageOptions`	`setProgramVersion(java.lang.String programVersion)`
`UsageOptions`	`setProps(java.util.Properties props)`
`UsageOptions`	`setTextLanguage(java.lang.String textLanguage)`
`UsageOptions`	`setUnsetClientName(java.lang.String unsetClientName)`
`UsageOptions`	`setUnsetUserName(java.lang.String unsetUserName)`
`UsageOptions`	`setWorkingDirectory(java.lang.String workingDirectory)`

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - WORKING_DIRECTORY_PROPNAME
```
public static final java.lang.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 java.util.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 java.lang.String programName
```
    If not null, will be used to identify the P4Java application's program name to the Perforce server.
  - programVersion
```
protected java.lang.String programVersion
```
    If not null, will be used to identify the P4Java application's program version to the Perforce server.
  - workingDirectory
```
protected java.lang.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 java.lang.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 java.lang.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 java.lang.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 java.lang.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 java.lang.String defaultWorkingDirectory
```
    Default working directory from the JVM to fall back to if not working directory is set on the usage options
- Constructor Detail
  - UsageOptions
```
public UsageOptions(java.util.Properties props)
```
    Default constructor. Sets props field then calls setFieldDefaults to set appropriate field default values; otherwise does nothing.
    
    Parameters:
    
    props - properties
  - UsageOptions
```
public UsageOptions(java.util.Properties props,
                    java.lang.String programName,
                    java.lang.String programVersion,
                    java.lang.String workingDirectory,
                    java.lang.String hostName,
                    java.lang.String textLanguage,
                    java.lang.String unsetUserName,
                    java.lang.String noClientName)
```
    Explicit value constructor. After setting any values explicitly, calls setFieldDefaults() to tidy up any still-null fields that shouldn't be null.
    
    Parameters:
    
    props - properties
    
    programName - program name
    
    programVersion - program version
    
    workingDirectory - working directory
    
    hostName - host name
    
    textLanguage - language
    
    unsetUserName - user name
    
    noClientName - client name
- Method Detail
  - setFieldDefaults
```
protected void setFieldDefaults(java.util.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.
    
    Parameters:
    
    props - properties
  - getProgramNameDefault
```
protected java.lang.String getProgramNameDefault(java.util.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.
    
    Parameters:
    
    props - properties
    
    Returns:
    
    non-null default programName value.
  - getProgramVersionDefault
```
protected java.lang.String getProgramVersionDefault(java.util.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.
    
    Parameters:
    
    props - properties
    
    Returns:
    
    non-null default programVersion value.
  - getWorkingDirectoryDefault
```
protected java.lang.String getWorkingDirectoryDefault(java.util.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).
    
    Parameters:
    
    props - properties
    
    Returns:
    
    non-null working directory.
  - getUnsetUserNameDefault
```
protected java.lang.String getUnsetUserNameDefault(java.util.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.
    
    Parameters:
    
    props - properties
    
    Returns:
    
    non-null default unsetUserName value.
  - getUnsetClientNameDefault
```
protected java.lang.String getUnsetClientNameDefault(java.util.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.
    
    Parameters:
    
    props - properties
    
    Returns:
    
    non-null default unsetClientName value.
  - getProgramName
```
public java.lang.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.
    
    Returns:
    
    program name
  - setProgramName
```
public UsageOptions setProgramName(java.lang.String programName)
```
  - getProgramVersion
```
public java.lang.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.
    
    Returns:
    
    program version
  - setProgramVersion
```
public UsageOptions setProgramVersion(java.lang.String programVersion)
```
    Parameters:
    
    programVersion - program version
    
    Returns:
    
    usage options
  - getWorkingDirectory
```
public java.lang.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.
    
    Returns:
    
    working directory
  - setWorkingDirectory
```
public UsageOptions setWorkingDirectory(java.lang.String workingDirectory)
```
    Parameters:
    
    workingDirectory - working directory
    
    Returns:
    
    usage options
  - getHostName
```
public java.lang.String getHostName()
```
    Returns:
    
    host name
  - setHostName
```
public UsageOptions setHostName(java.lang.String hostName)
```
    Set the host name. Calling this method has no effect at all after any associated server object is created.
    
    Parameters:
    
    hostName - host name
    
    Returns:
    
    usage options
  - getTextLanguage
```
public java.lang.String getTextLanguage()
```
    Returns:
    
    language
  - setTextLanguage
```
public UsageOptions setTextLanguage(java.lang.String textLanguage)
```
    Parameters:
    
    textLanguage - language
    
    Returns:
    
    usage options
  - getProps
```
public java.util.Properties getProps()
```
    Returns:
    
    properties
  - setProps
```
public UsageOptions setProps(java.util.Properties props)
```
    Parameters:
    
    props - properties
    
    Returns:
    
    usage options
  - getUnsetClientName
```
public java.lang.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.
    
    Returns:
    
    client name
  - setUnsetClientName
```
public UsageOptions setUnsetClientName(java.lang.String unsetClientName)
```
    Parameters:
    
    unsetClientName - client name
    
    Returns:
    
    usage options
  - getUnsetUserName
```
public java.lang.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.
    
    Returns:
    
    user name
  - setUnsetUserName
```
public UsageOptions setUnsetUserName(java.lang.String unsetUserName)
```
    Parameters:
    
    unsetUserName - user name
    
    Returns:
    
    usage options

Class UsageOptions

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

WORKING_DIRECTORY_PROPNAME

props

programName

programVersion

workingDirectory

hostName

textLanguage

unsetUserName

unsetClientName

defaultWorkingDirectory

Constructor Detail

UsageOptions

UsageOptions

Method Detail

setFieldDefaults

getProgramNameDefault

getProgramVersionDefault

getWorkingDirectoryDefault

getUnsetUserNameDefault

getUnsetClientNameDefault

getProgramName

setProgramName

getProgramVersion

setProgramVersion

getWorkingDirectory

setWorkingDirectory

getHostName

setHostName

getTextLanguage

setTextLanguage

getProps

setProps

getUnsetClientName

setUnsetClientName

getUnsetUserName

setUnsetUserName