Package com.perforce.p4java.option

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

    • 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