Package 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.

  • Field Details

    • 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:

    • 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

  • Constructor Details

    • UsageOptions

      public UsageOptions(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(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.
      Parameters:
      props - properties
      programName - program name
      programVersion - program version
      workingDirectory - working directory
      hostName - host name
      textLanguage - language
      unsetUserName - user name
      noClientName - client name

  • Method Details

    • 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.

      Parameters:
      props - properties

    • 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.
      Parameters:
      props - properties
      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.
      Parameters:
      props - properties
      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).
      Parameters:
      props - properties
      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.
      Parameters:
      props - properties
      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.
      Parameters:
      props - properties
      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.
      Returns:
      program name

    • 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.
      Returns:
      program version

    • setProgramVersion

      public UsageOptions setProgramVersion(String programVersion)
      Parameters:
      programVersion - program version
      Returns:
      usage options

    • 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.
      Returns:
      working directory

    • setWorkingDirectory

      public UsageOptions setWorkingDirectory(String workingDirectory)
      Parameters:
      workingDirectory - working directory
      Returns:
      usage options

    • getHostName

      public String getHostName()
      Returns:
      host name

    • 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.
      Parameters:
      hostName - host name
      Returns:
      usage options

    • getTextLanguage

      public String getTextLanguage()
      Returns:
      language

    • setTextLanguage

      public UsageOptions setTextLanguage(String textLanguage)
      Parameters:
      textLanguage - language
      Returns:
      usage options

    • getProps

      public Properties getProps()
      Returns:
      properties

    • setProps

      public UsageOptions setProps(Properties props)
      Parameters:
      props - properties
      Returns:
      usage options

    • 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.
      Returns:
      client name

    • setUnsetClientName

      public UsageOptions setUnsetClientName(String unsetClientName)
      Parameters:
      unsetClientName - client name
      Returns:
      usage options

    • 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.
      Returns:
      user name

    • setUnsetUserName

      public UsageOptions setUnsetUserName(String unsetUserName)
      Parameters:
      unsetUserName - user name
      Returns:
      usage options