Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.perforce.p4java.option
Class Options

java.lang.Object
  extended by com.perforce.p4java.option.Options
Direct Known Subclasses:
AddFilesOptions, ChangelistOptions, CopyFilesOptions, CounterOptions, DeleteBranchSpecOptions, DeleteClientOptions, DeleteFilesOptions, DeleteLabelOptions, DescribeOptions, DuplicateRevisionsOptions, EditFilesOptions, ExportRecordsOptions, FixJobsOptions, GetBranchSpecOptions, GetBranchSpecsOptions, GetChangelistDiffsOptions, GetChangelistsOptions, GetClientsOptions, GetClientTemplateOptions, GetCountersOptions, GetDepotFilesOptions, GetDiffFilesOptions, GetDirectoriesOptions, GetExtendedFilesOptions, GetFileAnnotationsOptions, GetFileContentsOptions, GetFileDiffsOptions, GetFileSizesOptions, GetFixesOptions, GetInterchangesOptions, GetJobsOptions, GetKeysOptions, GetLabelsOptions, GetPropertyOptions, GetProtectionEntriesOptions, GetReviewChangelistsOptions, GetReviewsOptions, GetRevisionHistoryOptions, GetServerProcessesOptions, GetStreamOptions, GetStreamsOptions, GetSubmittedIntegrationsOptions, GetUserGroupsOptions, GetUsersOptions, IntegrateFilesOptions, JournalWaitOptions, KeyOptions, LabelSyncOptions, LockFilesOptions, LoginOptions, LogTailOptions, MatchingLinesOptions, MergeFilesOptions, MoveFileOptions, ObliterateFilesOptions, OpenedFilesOptions, PopulateFilesOptions, PropertyOptions, ReconcileFilesOptions, ReloadOptions, ReopenFilesOptions, ResolvedFilesOptions, ResolveFilesAutoOptions, RevertFilesOptions, SearchJobsOptions, SetFileAttributesOptions, ShelveFilesOptions, StreamIntegrationStatusOptions, StreamOptions, SubmitOptions, SwitchClientViewOptions, SyncOptions, TagFilesOptions, TrustOptions, 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
protected  boolean immutable
          If true, this Options object is (theoretically) immutable.
protected  List<String> optionList
          The list of options strings associated with this Option.
protected static String OPTPFX
          String used to prefix options for the server.
 
Constructor Summary
Options()
          Default constructor.
Options(String... options)
          Construct a new immutable Options object using the passed-in strings as the options.
 
Method Summary
protected  String applyRule(String ruleName, String serverOptStr, boolean value)
          Apply an optional rule to a boolean option value.
protected  String applyRule(String ruleName, String serverOptStr, int value)
          Apply an optional rule to an integer option value.
protected  String applyRule(String ruleName, String serverOptStr, long value)
          Apply an optional rule to a long option value.
protected  String applyRule(String ruleName, String serverOptStr, String value)
          Apply an optional rule to a string option value.
 List<String> getOptions()
          Return the options string list associated with this object, if any.
 boolean isImmutable()
           
 List<String> processFields(String optsSpecs, 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.
 Options setImmutable(boolean immutable)
           
 Options 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 Detail

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.

OPTPFX

protected static final String OPTPFX
String used to prefix options for the server. This is pretty fundamental; don't change this unless you really know what you're doing....

See Also:
Constant Field Values
Constructor Detail

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 Detail

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.

setOptions

public Options 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
Returns:
this object

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.

processFields

public List<String> processFields(String optsSpecs,
                                  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 optsSpecs 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:
optsSpecs - 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.

applyRule

protected String applyRule(String ruleName,
                           String serverOptStr,
                           int value)
                    throws OptionsException
Apply an optional rule to an integer option value. This method is always called by the default implementation of Options.processOptions to process integer values; you should override this if you need your own rules processing.

This version of applyRules implements the rules specified below: 

 "gtz": don't return anything unless the value is > 0; typically used for
                things like maxUsers or maxRows.
 "cl": ignore negative values; convert 0 to the string "default". Typically
                used for changelists.
 "clz": ignore non-positive values; typically used for changelists where we
                let the server infer "default" for IChangelist.DEFAULT rather than
                spelling it out.
 "dcn": implements the -dc[n] rule for diff contexts, i.e. if the int value is
                zero, emit the flag alone; if it's positive, emit the flag with the int
                value attached; if it's negative, don't emit anything.
If the passed-in ruleName is non-null and not recognized, the behaviour is the same as if a null rule name was passed in.

Parameters:
ruleName - rule name string from the options spec string. If null, no rule was specified.
serverOptStr - the flag string to be sent to the Perforce server prefixing this value
value - the integer value itself.
Returns:
processed value or null if the rules resulted in nothing to be sent to the Perforce server.
Throws:
OptionsException - if any errors occurred during options processing.

applyRule

protected String applyRule(String ruleName,
                           String serverOptStr,
                           long value)
                    throws OptionsException
Apply an optional rule to a long option value. This method is always called by the default implementation of Options.processOptions to process long values; you should override this if you need your own rules processing.

This version of applyRules implements the rules specified below: 

 "gtz": don't return anything unless the value is > 0.
 "gez": don't return anything unless the value is >= 0.
If the passed-in ruleName is non-null and not recognized, the behaviour is the same as if a null rule name was passed in.

Parameters:
ruleName - rule name string from the options spec string. If null, no rule was specified.
serverOptStr - the flag string to be sent to the Perforce server prefixing this value
value - the long value itself.
Returns:
processed value or null if the rules resulted in nothing to be sent to the Perforce server.
Throws:
OptionsException - if any errors occurred during options processing.

applyRule

protected String applyRule(String ruleName,
                           String serverOptStr,
                           String value)
                    throws OptionsException
Apply an optional rule to a string option value. This method is always called by the default implementation of Options.processOptions to process string values; you should override this if you need your own rules processing.

There are currently no rules recognised or implemented in this method.

Parameters:
ruleName - rule name string from the options spec string. If null, no rule was specified.
serverOptStr - the flag string to be sent to the Perforce server prefixing this value
value - the string value itself; may be null.
Returns:
processed value or null if the rules resulted in nothing to be sent to the Perforce server.
Throws:
OptionsException - if any errors occurred during options processing.

applyRule

protected String applyRule(String ruleName,
                           String serverOptStr,
                           boolean value)
                    throws OptionsException
Apply an optional rule to a boolean option value. This method is always called by the default implementation of Options.processOptions to process boolean values; you should override this if you need your own rules processing.

There are currently no rules recognised or implemented in this method.

Parameters:
ruleName - rule name string from the options spec string. If null, no rule was specified.
serverOptStr - the flag string to be sent to the Perforce server prefixing this value
value - the boolean value itself.
Returns:
processed value or null if the rules resulted in nothing to be sent to the Perforce server.
Throws:
OptionsException - if any errors occurred during options processing.

isImmutable

public boolean isImmutable()

setImmutable

public Options setImmutable(boolean immutable)
Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Copyright © 2015 Perforce Software. All Rights Reserved.