Package com.perforce.p4java.option

Class Options

java.lang.Object
com.perforce.p4java.option.Options
Direct Known Subclasses:
AddFilesOptions, ChangelistOptions, ConvertSparseOptions, CopyFilesOptions, CounterOptions, DeleteBranchSpecOptions, DeleteClientOptions, DeleteFilesOptions, DeleteLabelOptions, DescribeOptions, DuplicateRevisionsOptions, EditFilesOptions, ExportRecordsOptions, FixJobsOptions, GetBranchSpecOptions, GetBranchSpecsOptions, GetChangelistDiffsOptions, GetChangelistsOptions, GetClientsOptions, GetClientTemplateOptions, GetCountersOptions, GetDepotFilesOptions, GetDepotsOptions, GetDiffFilesOptions, GetDirectoriesOptions, GetExtendedFilesOptions, GetFileAnnotationsOptions, GetFileContentsOptions, GetFileDiffsOptions, GetFileSizesOptions, GetFixesOptions, GetInterchangesOptions, GetJobsOptions, GetKeysOptions, GetLabelsOptions, GetPropertyOptions, GetProtectionEntriesOptions, GetReviewChangelistsOptions, GetReviewsOptions, GetRevisionHistoryOptions, GetServerProcessesOptions, GetStreamOptions, GetStreamsOptions, GetSubmittedIntegrationsOptions, GetUserGroupsOptions, GetUsersOptions, GraphCommitLogOptions, GraphReceivePackOptions, GraphRevListOptions, GraphShowRefOptions, IntegrateFilesOptions, JournalWaitOptions, KeyOptions, LabelSyncOptions, ListOptions, LockFilesOptions, Login2Options, LoginOptions, LogTailOptions, MatchingLinesOptions, MergeFilesOptions, MoveFileOptions, ObliterateFilesOptions, OpenedFilesOptions, PopulateFilesOptions, PropertyOptions, ReconcileFilesOptions, ReloadOptions, ReopenFilesOptions, ReposOptions, ResolvedFilesOptions, ResolveFilesAutoOptions, RevertFilesOptions, SearchJobsOptions, SetFileAttributesOptions, ShelveFilesOptions, StreamIntegrationStatusOptions, StreamlogOptions, StreamOptions, SubmitOptions, SwitchClientViewOptions, SyncOptions, TagFilesOptions, TrustOptions, UndoFilesOptions, UnloadOptions, UnlockFilesOptions, UnshelveFilesOptions, UpdateClientOptions, UpdateUserGroupOptions, UpdateUserOptions, VerifyFilesOptions
public abstract class Options extends Object
Abstract P4Java method options superclass. Supplies the very basic plumbing for the method-specific options classes, including the associated generic options processing gubbins.

  • Field Summary

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

  • Constructor Summary

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

  • Method Summary

    Modifier and Type
    Method
    Description
    List<String>
    getOptions()
    Return the options string list associated with this object, if any.
    boolean
    isImmutable()
     
    List<String>
    processFields(String optionSpecsString, Object... opts)
    Process command method options according to a simple getopts-like options specifier string.
    abstract List<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(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 Details

    • optionList

      protected List<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 Details

    • Options

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

    • Options

      public Options(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 Details

    • setOptions

      public void setOptions(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 List<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 List<String> processFields(@Nonnull String optionSpecsString, @Nullable 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 List<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.