Package com.perforce.p4java.option

Class Options

    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected boolean immutable
      If true, this Options object is (theoretically) immutable.
      protected java.util.List<java.lang.String> optionList
      The list of options strings associated with this Option.

    • Constructor Summary

      Constructors 
      Constructor Description
      Options()
      Default constructor.
      Options​(java.lang.String... options)
      Construct a new immutable Options object using the passed-in strings as the options.

    • Method Summary

      All Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      java.util.List<java.lang.String> getOptions()
      Return the options string list associated with this object, if any.
      boolean isImmutable()  
      java.util.List<java.lang.String> processFields​(java.lang.String optionSpecsString, java.lang.Object... opts)
      Process command method options according to a simple getopts-like options specifier string.
      abstract java.util.List<java.lang.String> processOptions​(IServer server)
      Turn this (specific) options object into a list of strings to be sent to the Perforce server as options for a specific command.
      void setImmutable​(boolean immutable)  
      void setOptions​(java.lang.String... options)
      Set the options string list associated with this options object.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Field Detail

      • optionList

        protected java.util.List<java.lang.String> optionList
        The list of options strings associated with this Option. Note that if this is non-null, the processOptions options processing method may optionally bypass options construction and simply return this value; this allows for options reuse, etc.

      • immutable

        protected boolean immutable
        If true, this Options object is (theoretically) immutable. What this means in practice is that its processOptions method is only evaluated once, i.e. the Server implementation class and associated Parameters (etc.) classes only call the processOptions methods the first time the object is passed to the Server as an argument (rather than each time the object is passed to the Server). More precisely, if the object is immutable and has already been evaluated (i.e. the optionList field is not null), the optionList is used as-is; otherwise the optionList is set to the (non-null) value returned by processOptions.

        This can be useful for Options objects intended for shared and constant use, and can bypass quite a lot of options evaluation; but note that in general it should only be used when you're certain that options don't change or are not reliant on dynamic circumstances.

        Note that immutable is always set when the string constructor is used, which can have surprising implications if this fact is forgotten down the line. Note that subclass implementations are not bound to observe immutability, in which case the class should ensure (by overriding, etc.) that isImmutable() always returns false.

    • Constructor Detail

      • Options

        public Options()
        Default constructor. Currently does nothing except set this.optionList to null.

      • Options

        public Options​(java.lang.String... options)
        Construct a new immutable Options object using the passed-in strings as the options.

        WARNING: you should not pass more than one option or argument in each string parameter. Each option or argument should be passed-in as its own separate string parameter, without any spaces between the option and the option value (if any).

        The intention here is to provide a way to bypass the various method-specific options setters with a simple mechanism to allow for constructs like this: 

         new Options("-m10", "-uhreid");
        where the individual options strings correspond exactly to the Perforce server arguments and are passed to the server as is (unless a callback intervenes). Options passed in like this will normally take precedence over any options set using other mechanisms.

        NOTE: setting options this way always bypasses the internal options values, and getter methods against the individual values corresponding to the strings passed in to this constructor will not normally reflect the string's setting. Do not use this constructor unless you know what you're doing and / or you do not also use the field getters and setters.

        Parameters:
        options - possibly-null option strings.

    • Method Detail

      • setOptions

        public void setOptions​(java.lang.String... options)
        Set the options string list associated with this options object.

        WARNING: you should not pass more than one option or argument in each string parameter. Each option or argument should be passed-in as its own separate string parameter, without any spaces between the option and the option value (if any).

        The intention here is to provide a way to bypass the various method-specific options setters with a simple mechanism to allow for constructs like this: 

         opts = new Options();
 opts.setOptions("-m10", "-uhreid");
        where the individual options strings correspond exactly to the Perforce server arguments and are passed to the server as is (unless a callback intervenes). Options passed in like this may take precedence over any options set using other mechanisms.

        Parameters:
        options - possibly-null option strings list

      • setImmutable

        public void setImmutable​(boolean immutable)

      • isImmutable

        public boolean isImmutable()

      • getOptions

        public java.util.List<java.lang.String> getOptions()
        Return the options string list associated with this object, if any. This is a simple getter method for the options field, and is not the same as the processOptions() method (which does processing).
        Returns:
        possibly null list of options strings.

      • processFields

        public java.util.List<java.lang.String> processFields​(@Nonnull
                                                      java.lang.String optionSpecsString,
                                                      @Nullable
                                                      java.lang.Object... opts)
                                               throws OptionsException
        Process command method options according to a simple getopts-like options specifier string. The intention here is to provide a very simple way for methods with common options to turn those options values into a list of strings suitable for sending to the perforce server. Usage is typically something like this: 
         optsList = processFields("i:c:cl s:j b:i i:m:gtz", opts.getChangelistId(), opts.getJobId(),
                opts.isIncludeIntegrations(), opts.getMaxFixes())
        The format of the optionSpecsString string parameter is: 
         typespec:server-flag[:rulename]
        where typespec is currently one of: 
         i -- integer; assumes the corresponding argument is an int; will generally
 just concatenate the flag and the value.
 b -- boolean; assumes the corresponding argument is a boolean; will normally
 only return the corresponding flag if true.
 s -- string; assumes the corresponding argument is a string; will normally
 just concatenate the flag and the value if the value is non-null.
        and server-flag is the flag string associated with this option when sent to the Perforce server, and where the optional rulename is passed to the relevant applyRule method. See the individual applyRule documentation below for rule processing details. Note that use of this method is entirely voluntary, and that it does not always work for non-simple cases. Note also that both the general implementation and the rules section will probably expand a bit over time.
        Parameters:
        optionSpecsString - non-null options specifier string as specified above
        opts - non-null options to be processed
        Returns:
        a non-null but possibly-empty list of options strings
        Throws:
        OptionsException - if any errors occurred during options processing.

      • processOptions

        public abstract java.util.List<java.lang.String> processOptions​(IServer server)
                                                         throws OptionsException
        Turn this (specific) options object into a list of strings to be sent to the Perforce server as options for a specific command. As a side effect, set the option list associated with this Option to the result.

        The method is used by the server object to generate the string-based arguments expected by the Perforce server corresponding to the state of this method-specific options object. Will return an empty list if there are no "interesting" options set or available. May simply return the superclass options string list if is non-null, but that behaviour is neither guaranteed nor required.

        Note that this method is not intended to be called directly by users but by the underlying P4Java plumbing; odd results may occur if this method is called in other contexts.

        Parameters:
        server - possibly-null IServer representing the Perforce server the options are to be used against. If this parameter is null, it is acceptable to throw an OptionsException, but it is also possible to ignore it and do the best you can with what you've got...
        Returns:
        non-null (but possibly empty) string list representing the normalized Perforce server arguments corresponding to the state of this specific options object.
        Throws:
        OptionsException - if an error occurs in options processing that is not some species of ConnectionException, RequestException, AccessException, etc.