water.api
Class RequestArguments.Argument<T>

java.lang.Object
  water.Iced
      water.api.RequestArguments.Argument<T>

All Implemented Interfaces:

java.lang.Cloneable, Request.Filter, Freezable

Direct Known Subclasses:

Parse.Preview, RequestArguments.InputCheckBox, RequestArguments.InputSelect, RequestArguments.InputText, RequestArguments.MultipleSelect, RequestArguments.MultipleText

Enclosing class:

RequestArguments

public abstract class RequestArguments.Argument<T>
extends Iced
implements Request.Filter

Field Summary

java.lang.String	_displayName Name of the argument.
java.lang.reflect.Field	_field If argument has been created reflectively from a request field.
boolean	_hideInQuery True if the argument should not appear in the automatically generated query.
java.lang.String	_name Name of the argument.
java.util.ArrayList<RequestArguments.Argument<T>>	_prerequisites List of all prerequisite arguments for the current argument.
boolean	_readOnly True if the argument should be only read-only.
java.lang.String	_requestHelp As with request's _requestHelp, this provides the extended help that will be displayed on the help and wiki pages.
boolean	_required True if the argument is required, false if it may be skipped.

Constructor Summary

protected

RequestArguments.Argument(java.lang.String name, boolean required) Creates the argument of given name.

Method Summary

protected void	addPrerequisite(RequestArguments.Argument arg) Adds the given argument as a prerequisite.
void	check(RequestQueries callInstance, java.lang.String input) Checks that the argument supplied is correct.
protected abstract T	defaultValue() Returns the default value of the argument.
void	disable(java.lang.String reason) Disables the argument with given reason.
void	disable(java.lang.String reason, java.util.Properties args) Disables the argument and makes its input value empty.
boolean	disabled() Returns whether the argument is disabled or not.
protected java.lang.String[]	errors() Returns a list of possible error strings, that could be thrown in an IllegalArgumentException.
protected java.lang.String	jsAddons() If there is any additional javascript that should be dumped to the query page, it should be defined here.
protected abstract java.lang.String	jsRefresh(java.lang.String callbackName) Returns the javascript code that will be executed when the query is loaded that associates the given callback JS function with the on change event of the input.
protected abstract java.lang.String	jsValue() Returns the javascript code that will be executed when the value of the argument is to be determined.
java.lang.String	originalValue() Returns the input value submitted by the user, if specified.
protected abstract T	parse(java.lang.String input) Override this method to provide parsing of the input string to the Java expected value.
protected java.lang.String	query() Returns the html query for the given argument, including the full formatting.
protected java.lang.String	queryAddons() Any query addons can be specified here.
protected java.lang.String	queryComment()
protected abstract java.lang.String	queryDescription() Returns the query description.
protected abstract java.lang.String	queryElement() Returns the HTML elements of the argument query only.
protected RequestArguments.Record<T>	record() Returns the thread local argument state record.
boolean	refreshOnChange() Returns true if the argument refreshes the query automatically on its change.
com.google.gson.JsonObject	requestHelp() Creates the request help page part for the given argument.
void	reset() Resets the argument by creating it a new thread local state.
boolean	run(java.lang.Object value)
protected void	setRefreshOnChange() Makes the argument refresh the query page on its change automatically.
boolean	specified() Returns true if the argument is specified by the user.
boolean	valid() Returns true if the argument is valid.
T	value() Returns the value of the argument.

Methods inherited from class water.Iced

clone, frozenType, init, newInstance, read, toDocField, write, writeJSON, writeJSONFields

Methods inherited from class java.lang.Object

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

Field Detail

_requestHelp

public java.lang.String _requestHelp

As with request's _requestHelp, this provides the extended help that will be displayed on the help and wiki pages. Specify this in the particular request constructor.

_hideInQuery

public boolean _hideInQuery

True if the argument should not appear in the automatically generated query.

_readOnly

public boolean _readOnly

True if the argument should be only read-only.

_name

public java.lang.String _name

Name of the argument. This must correspond to the name of the JSON request argument.

_displayName

public java.lang.String _displayName

Name of the argument. This must correspond to the name of the JSON request argument.

_required

public boolean _required

True if the argument is required, false if it may be skipped.

_prerequisites

public transient java.util.ArrayList<RequestArguments.Argument<T>> _prerequisites

List of all prerequisite arguments for the current argument. All the prerequisite arguments must be created before the current argument.

_field

public transient java.lang.reflect.Field _field

If argument has been created reflectively from a request field.

Constructor Detail

RequestArguments.Argument

protected RequestArguments.Argument(java.lang.String name,
                                    boolean required)

Creates the argument of given name. Also specifies whether the argument is required or not. This cannot be changed later.

Method Detail

run

public boolean run(java.lang.Object value)

Specified by:

run in interface Request.Filter

parse

protected abstract T parse(java.lang.String input)
                    throws java.lang.IllegalArgumentException

Override this method to provide parsing of the input string to the Java expected value. The input is guaranteed to be non-empty when this method is called and all prerequisities are guaranteed to be valid before this method is called.

Throws:

java.lang.IllegalArgumentException

defaultValue

protected abstract T defaultValue()

Returns the default value of the argument. Note that the method will be called also on required arguments, in which case it is ok return null. It is kept abstract because defining a proper default value might be tricky and in many case you do not want it to be null. Overriding it always makes you think:)

jsRefresh

protected abstract java.lang.String jsRefresh(java.lang.String callbackName)

Returns the javascript code that will be executed when the query is loaded that associates the given callback JS function with the on change event of the input. This method is only called if the element should refresh the webpage upon its change.

jsValue

protected abstract java.lang.String jsValue()

Returns the javascript code that will be executed when the value of the argument is to be determined. It must contain a return statement, that returns the string that should be sent back to the request for the given arhument.

jsAddons

protected java.lang.String jsAddons()

If there is any additional javascript that should be dumped to the query page, it should be defined here. Please follow chaining rules.

queryElement

protected abstract java.lang.String queryElement()

Returns the HTML elements of the argument query only. This should return the elements in HTML that will be used to enter the value. For instance the input text, selection, etc.

queryComment

protected java.lang.String queryComment()

queryDescription

protected abstract java.lang.String queryDescription()

Returns the query description. This is a concise description of a correct value for the argument. generally used as a placeholder in the html query elements.

errors

protected java.lang.String[] errors()

Returns a list of possible error strings, that could be thrown in an IllegalArgumentException.

queryAddons

protected java.lang.String queryAddons()

Any query addons can be specified here. These will be displayed with the query html code and should be used for instance for default value calculators, etc.

query

protected java.lang.String query()

Returns the html query for the given argument, including the full formatting. That means not only the queryElement, but also the argument name in front of it, etc. You may want to override this if you want different form layouts to be present.

requestHelp

public final com.google.gson.JsonObject requestHelp()

Creates the request help page part for the given argument. Displays its JSON name, query name (the one in HTML), value type and the request help provided by the argument.

addPrerequisite

protected final void addPrerequisite(RequestArguments.Argument arg)

Adds the given argument as a prerequisite. This means that current argument will not be checked and/or reported in queries as a control form unless all its prerequisite arguments are in a valid state. (the argument will be disabled if not all its prerequisites are satisfied).

record

protected final RequestArguments.Record<T> record()

Returns the thread local argument state record.

disable

public final void disable(java.lang.String reason)

Disables the argument with given reason. If the argument is already disabled, its reason is overwritten by the new one. NOTE disable(null) effectively enables the argument, that is why the assert!

disable

public final void disable(java.lang.String reason,
                          java.util.Properties args)

Disables the argument and makes its input value empty. This is the preferred way of disabling arguments.

disabled

public final boolean disabled()

Returns whether the argument is disabled or not.

setRefreshOnChange

protected void setRefreshOnChange()

Makes the argument refresh the query page on its change automatically. If you want this behavior to be disabled for the argument, overwrite this method to error.

refreshOnChange

public boolean refreshOnChange()

Returns true if the argument refreshes the query automatically on its change.

valid

public final boolean valid()

Returns true if the argument is valid. Valid means specified by user and parsed properly, or not required and not specified.

specified

public final boolean specified()

Returns true if the argument is specified by the user. That is if the argument value was submitted by the user and parsed correctly.

value

public final T value()

Returns the value of the argument. This is either the value parsed, if specified, or defaultValue. Note that default value is returned also for invalid arguments.

originalValue

public final java.lang.String originalValue()

Returns the input value submitted by the user, if specified.

reset

public final void reset()

Resets the argument by creating it a new thread local state. Everything is null and the argument is not valid.

check

public void check(RequestQueries callInstance,
                  java.lang.String input)
           throws java.lang.IllegalArgumentException

Checks that the argument supplied is correct. This method is called for each argument and is given the HTTP supplied argument value. If the value was not supplied, input contains an empty string. The argument must already be reseted before calling this method. If the argument is disabled, the function does not do anything except setting the original value in the record. If the prerequisites of the argument are not all valid, then the argument is disabled and function returns. Then the argument is parsed if provided, or an error thrown if the input is empty and the argument is required. At the end of the function the value is either the result of a successful parse() call or a defaultValue or null if the argument is disabled. However if the argument is disabled a defaultValue should not be called.

Throws:

java.lang.IllegalArgumentException