uws.job.parameters

Class UWSParameters

java.lang.Object

uws.job.parameters.UWSParameters

All Implemented Interfaces:

java.lang.Iterable<java.util.Map.Entry<java.lang.String,java.lang.Object>>

Direct Known Subclasses:

TAPParameters

public class UWSParameters
extends java.lang.Object
implements java.lang.Iterable<java.util.Map.Entry<java.lang.String,java.lang.Object>>

Let extracting all UWS standard and non-standard parameters from a map.

Input parameter check

It is possible to check the value of some or all parameters by calling the function InputParamController.check(Object) of an InputParamController associated with the name of the parameter. Input parameter controllers can be provided at the creation of a UWSParameters. If none are given, default ones are used (see getDefaultControllers()) for the standard UWS parameters (e.g. destruction time, duration, etc...).

Default value

By calling the function init(), you set a default value to any parameter which has an InputParamController and which has not yet a value.

The function InputParamController.getDefault() returns a default value for its associated parameter. This value must be obviously different from NULL.

Updating a UWSParameters

It is possible to update a UWSParameters with another UWSParameters thanks to the function update(UWSParameters). In this case, no check is done since the values given by a UWSParameters should be theoretically already correct.

In order to forbid the modification of some parameters after their initialization, you must associate an InputParamController with them and override the function InputParamController.allowModification() so that it returns false.

Case sensitivity

All UWS STANDARD parameters can be provided in any case: they will always be identified and updated. However any other parameter will be stored as it is provided: so with the same case. Thus, you must respect the case for all UWS additional parameters in your other operations on the parameters.

If you want to identify your own parameters without case sensitivity, you must provides a list of all the additional parameters you are expected at the creation: see UWSParameters(HttpServletRequest, Collection, Map) and UWSParameters(Map, Collection, Map).

Additional parameters case normalization

Indeed, the second parameter of these constructors (if != NULL) is used to normalize the name of the additional parameters so that they have exactly the given case.

For instance, suppose that the request had a parameter named "foo" and you expect a parameter named "FOO" (only the case changes). By providing a second parameter which contains the entry "FOO", all parameters having the same name - even if the case is different - will be named "FOO".

In brief:

• With "FOO" in the second parameter of the constructor: get("FOO") will return something if in the request there was a parameter named: "foo", "FOO", "Foo", ...
• If the second parameter is empty, NULL or does not contain "FOO": get("FOO") will return something if in the request there was a parameter named exactly "FOO".

UWS standard parameters

All UWS standard parameters are identified in this class. However, only READ/WRITE parameters are kept. All the others are ignored. The read/write UWS standard parameters are:

• runId (UWSJob.PARAM_RUN_ID)
• executionDuration (UWSJob.PARAM_EXECUTION_DURATION)
• destruction (UWSJob.PARAM_DESTRUCTION_TIME)

note 1: All parameters stored under the parameter UWSJob.PARAM_PARAMETERS (that's to say, additional parameters) are also considered as READ/WRITE parameters !

note 2: If several values have been submitted for the same UWS standard parameter, just the last occurrence is taken into account.

Version:

4.4 (07/2018)

Author:

Grégory Mantelet (CDS;ARI)

Field Summary

Fields

Modifier and Type	Field and Description
protected java.util.Collection<java.lang.String>	expectedAdditionalParams List of the expected additional parameters.
protected java.util.List<UploadFile>	files List of all uploaded files among the whole set of parameters.
protected java.util.Map<java.lang.String,InputParamController>	mapParamControllers List of the controllers of all the input parameters.
protected java.util.Map<java.lang.String,java.lang.Object>	params List of all extracted parameters.
protected static java.lang.String[]	UWS_RO_PARAMETERS Read-Only parameters.
protected static java.lang.String[]	UWS_RW_PARAMETERS Read-Write parameters.
static java.lang.String	UWS_RW_PARAMETERS_REGEXP Regular expression allowing to test which UWS parameters can be set.

Constructor Summary

Constructors

Constructor and Description
UWSParameters() Builds an empty list of UWS parameters.
UWSParameters(java.util.Collection<java.lang.String> expectedAdditionalParams, java.util.Map<java.lang.String,InputParamController> inputParamControllers) Builds an empty list of UWS parameters.
UWSParameters(javax.servlet.http.HttpServletRequest request) Extracts and identifies all UWS standard and non-standard parameters from the given HttpServletRequest.
UWSParameters(javax.servlet.http.HttpServletRequest request, java.util.Collection<java.lang.String> expectedAdditionalParams, java.util.Map<java.lang.String,InputParamController> inputParamControllers) Extracts and identifies all UWS standard and non-standard parameters from the given HttpServletRequest.
UWSParameters(java.util.Map<java.lang.String,java.lang.Object> params) Extracts and identifies all UWS standard and non-standard parameters from the map.
UWSParameters(java.util.Map<java.lang.String,java.lang.Object> params, java.util.Collection<java.lang.String> expectedAdditionalParams, java.util.Map<java.lang.String,InputParamController> inputParamControllers) Extracts and identifies all UWS standard and non-standard parameters from the map.

Method Summary

Modifier and Type	Method and Description
java.lang.Object	get(java.lang.String name) Gets the value of the specified parameter.
java.util.Map<java.lang.String,java.lang.Object>	getAdditionalParameters() Gets the list of all UWS additional parameters (all these parameters are associated with the parameter name UWSJob.PARAM_PARAMETERS).
protected InputParamController	getController(java.lang.String inputParamName) Must return the input parameter controller of the specified parameter.
protected java.util.Iterator<java.util.Map.Entry<java.lang.String,InputParamController>>	getControllers() Must return the list of all available input parameter controllers.
protected java.util.Map<java.lang.String,InputParamController>	getDefaultControllers() Builds a default list of controllers for the standard UWS input parameters.
java.util.Date	getDestructionTime() Gets the value of the parameter destruction.
long	getExecutionDuration() Gets the value of the parameter executionDuration.
java.util.Iterator<UploadFile>	getFiles() Get the list of all uploaded files.
java.lang.String	getInputPhase() Gets the value of the parameter phase.
java.util.Set<java.lang.String>	getNames() Gets the name of all parameters.
protected static java.util.Map<java.lang.String,java.lang.Object>	getParameters(javax.servlet.http.HttpServletRequest request) Get the parameters stored in the given HTTP request.
java.lang.String	getRunId() Gets the value of the parameter runId.
boolean	hasInputPhase() Tells whether there is a value for the PHASE parameter.
void	init() Set the default value to all missing parameters (ONLY for those who have a controller -> see InputParamController).
boolean	isEmpty() Tells whether there is no parameter or not.
java.util.Iterator<java.util.Map.Entry<java.lang.String,java.lang.Object>>	iterator()
protected java.lang.String	normalizeParamName(java.lang.String name) Normalizes the given name.
java.lang.Object	remove(java.lang.String inputParamName) Removes the value of the given input parameter name.
java.lang.Object	set(java.lang.String name, java.lang.Object value) Sets the given value to the specified parameter.
int	size() Gets the number of all stored parameters.
java.lang.String[]	update(UWSParameters newParams) Updates this list of UWS parameters with the given ones.

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Field Detail

UWS_RW_PARAMETERS

protected static final java.lang.String[] UWS_RW_PARAMETERS

Read-Write parameters.

Names of the UWS parameters whose the value can be modified by the user.

UWS_RW_PARAMETERS_REGEXP

public static final java.lang.String UWS_RW_PARAMETERS_REGEXP

Regular expression allowing to test which UWS parameters can be set. Actually, only: phase, runID, executionduration and destruction.

UWS_RO_PARAMETERS

protected static final java.lang.String[] UWS_RO_PARAMETERS

Read-Only parameters.

Names of the UWS parameters whose the value can NOT be modified by the user. These value are not kept. They are only ignored.

params

protected final java.util.Map<java.lang.String,java.lang.Object> params

List of all extracted parameters.

files

protected java.util.List<UploadFile> files

List of all uploaded files among the whole set of parameters.

Since:

4.1

expectedAdditionalParams

protected final java.util.Collection<java.lang.String> expectedAdditionalParams

List of the expected additional parameters.

mapParamControllers

protected final java.util.Map<java.lang.String,InputParamController> mapParamControllers

List of the controllers of all the input parameters.

Constructor Detail

UWSParameters

public UWSParameters()

Builds an empty list of UWS parameters.

See Also:

UWSParameters(Collection, Map)

UWSParameters

public UWSParameters(java.util.Collection<java.lang.String> expectedAdditionalParams,
                     java.util.Map<java.lang.String,InputParamController> inputParamControllers)

Builds an empty list of UWS parameters.

note: Even if no controllers is provided, this constructor sets the default input parameter controllers (see getDefaultControllers()).

Parameters:

expectedAdditionalParams - The names of all expected additional parameters (MAY BE NULL). note: they will be identified with no case sensitivity and stored with the same case as in this collection.

inputParamControllers - Controllers of the input parameters (MAY BE NULL).

See Also:

getDefaultControllers()

UWSParameters

public UWSParameters(javax.servlet.http.HttpServletRequest request)
              throws UWSException

Extracts and identifies all UWS standard and non-standard parameters from the given HttpServletRequest.

note: The default input parameter controllers are set by default (see getDefaultControllers()).

Parameters:

request - The request to parse to extract the parameters.

Throws:

UWSException - If one of the given parameter is incorrect or badly formatted.

See Also:

UWSParameters(HttpServletRequest, Collection, Map)

UWSParameters

public UWSParameters(javax.servlet.http.HttpServletRequest request,
                     java.util.Collection<java.lang.String> expectedAdditionalParams,
                     java.util.Map<java.lang.String,InputParamController> inputParamControllers)
              throws UWSException

Extracts and identifies all UWS standard and non-standard parameters from the given HttpServletRequest.

note: Even if no controllers is provided, this constructor sets the default input parameter controllers (see getDefaultControllers()).

Parameters:

request - The request to parse to extract the parameters.

expectedAdditionalParams - The names of all expected additional parameters. note: they will be identified with no case sensitivity and stored with the same case as in this collection.

inputParamControllers - Controllers of the input parameters.

Throws:

UWSException - If one of the given parameter is incorrect or badly formatted.

See Also:

UWSParameters(Map, Collection, Map)

UWSParameters

public UWSParameters(java.util.Map<java.lang.String,java.lang.Object> params)
              throws UWSException

Extracts and identifies all UWS standard and non-standard parameters from the map.

note: The default input parameter controllers are set by default (see getDefaultControllers()).

Parameters:

params - A map of parameters.

Throws:

UWSException - If one of the given parameter is incorrect or badly formatted.

See Also:

UWSParameters(Map, Collection, Map)

UWSParameters

public UWSParameters(java.util.Map<java.lang.String,java.lang.Object> params,
                     java.util.Collection<java.lang.String> expectedAdditionalParams,
                     java.util.Map<java.lang.String,InputParamController> inputParamControllers)
              throws UWSException

Extracts and identifies all UWS standard and non-standard parameters from the map.

note: Even if no controllers is provided, this constructor sets the default input parameter controllers (see getDefaultControllers()).

Parameters:

params - A map of parameters.

expectedAdditionalParams - The names of all expected additional parameters. note: they will be identified with no case sensitivity and stored with the same case as in this collection.

inputParamControllers - Controllers of the input parameters.

Throws:

UWSException - If one of the given parameter is incorrect or badly formatted.

See Also:

UWSParameters(Collection, Map)

Method Detail

getParameters

protected static java.util.Map<java.lang.String,java.lang.Object> getParameters(javax.servlet.http.HttpServletRequest request)

Get the parameters stored in the given HTTP request.

Since the version 4.1, parameters are extracted immediately when the request is received. They are then stored in an attribute under the name of UWS.REQ_ATTRIBUTE_PARAMETERS. Thus, the map of parameters can be got in that way. However, if this attribute does not exist, this function will ask for the parameters extracted by HttpServletRequest (ServletRequest.getParameterNames() and ServletRequest.getParameter(String)). In this last case only the last non-null occurrence of any parameter will be kept.

Parameters:

request - HTTP request from which the parameters must be got.

Returns:

The extracted parameters.

Since:

4.1

getDefaultControllers

protected java.util.Map<java.lang.String,InputParamController> getDefaultControllers()

Builds a default list of controllers for the standard UWS input parameters.

Returns:

Default list of controllers. note: This map can be modified !

getController

protected InputParamController getController(java.lang.String inputParamName)

Must return the input parameter controller of the specified parameter.

note: This function is supposed to be case sensitive !

Parameters:

inputParamName - The name of the parameter whose the controller is asked.

Returns:

The corresponding controller or null if there is no controller for the specified parameter.

getControllers

protected java.util.Iterator<java.util.Map.Entry<java.lang.String,InputParamController>> getControllers()

Must return the list of all available input parameter controllers.

Returns:

An iterator over all available controllers.

iterator

public final java.util.Iterator<java.util.Map.Entry<java.lang.String,java.lang.Object>> iterator()

Specified by:

iterator in interface java.lang.Iterable<java.util.Map.Entry<java.lang.String,java.lang.Object>>

getNames

public final java.util.Set<java.lang.String> getNames()

Gets the name of all parameters.

Returns:

List of all parameter names.

isEmpty

public final boolean isEmpty()

Tells whether there is no parameter or not.

Returns:

true if there is no parameter, false otherwise.

size

public final int size()

Gets the number of all stored parameters.

Returns:

Number of all parameters.

init

public final void init()

Set the default value to all missing parameters (ONLY for those who have a controller -> see InputParamController).

note: This method is thread safe!

update

public java.lang.String[] update(UWSParameters newParams)
                          throws UWSException

Updates this list of UWS parameters with the given ones. No check is done on the given parameters (since they come from an instance of UWSParameters, they are supposed to be correct)

note: This method is thread safe!

Parameters:

newParams - The parameters to update.

Returns:

An array listing the name of the updated parameters.

Throws:

UWSException - If one of the given parameters is not allowed to be modified.

get

public final java.lang.Object get(java.lang.String name)

Gets the value of the specified parameter.

note 1: The case of the parameter name MUST BE correct EXCEPT FOR the standard UWS parameters (i.e. runId, executionDuration, destructionTime).

note 2: If the name of the parameter is PARAMETERS, this function will return exactly what getAdditionalParameters() returns.

note 3: Depending of the way the parameters are fetched from an HTTP request, the returned object may be an array. Each item of this array would then be an occurrence of the parameter in the request (MAYBE in the same order as submitted).

Parameters:

name - Name of the parameter to get.

Returns:

Value of the specified parameter, or null if the given name is null, or an array or Objects if several values have been submitted for the same parameter, empty or has no value.

See Also:

normalizeParamName(String), getAdditionalParameters()

getFiles

public final java.util.Iterator<UploadFile> getFiles()

Get the list of all uploaded files.

Returns:

An iterator over the list of uploaded files.

Since:

4.1

set

public final java.lang.Object set(java.lang.String name,
                                  java.lang.Object value)
                           throws UWSException

Sets the given value to the specified parameter. But if the given value is null, the specified parameter is merely removed.

note 1: This method is thread safe!

note 2: The case of the parameter name MUST BE correct EXCEPT FOR the standard UWS parameters (i.e. runId, executionDuration, destructionTime).

note 3: If the specified parameter is a read-only UWS parameter (i.e. jobId, startTime, endTime, results, errorSummary, quote), this function does nothing and merely returns NULL.

note 4: A value equals to NULL, means that the specified parameter must be removed.

note 5: If the parameter PARAMETERS is given, it must be a Map. In this case, the map is read and all its entries are added individually.

Parameters:

name - Name of the parameter to set (add, update or remove). note: not case sensitive ONLY FOR the standard UWS parameters !

value - The value to set. note: NULL means that the specified parameter must be removed ; several values may have been provided using an array of Objects.

Returns:

The old value of the specified parameter. null may mean that the parameter has just been added, but it may also mean that nothing has been done (because, the given name is null, empty or corresponds to a read-only parameter).

Throws:

UWSException - If the given value is incorrect or badly formatted.

See Also:

normalizeParamName(String)

remove

public java.lang.Object remove(java.lang.String inputParamName)

Removes the value of the given input parameter name.

Parameters:

inputParamName - Name of the parameter to remove. note: not case sensitive ONLY FOR the standard UWS parameters !

Returns:

The removed value.

See Also:

normalizeParamName(String)

normalizeParamName

protected java.lang.String normalizeParamName(java.lang.String name)

Normalizes the given name.

Parameters:

name - Name of the parameter to identify/normalize.

Returns:

Normalized name or null if the parameters should be ignored (i.e. empty name and UWS read-only parameters).

hasInputPhase

public final boolean hasInputPhase()

Tells whether there is a value for the PHASE parameter.

Returns:

true if the PHASE has a value, false otherwise.

getInputPhase

public final java.lang.String getInputPhase()

Gets the value of the parameter phase.

note: This parameter is removed from the parameters list after the call of this function !

Returns:

The given phase.

getRunId

public final java.lang.String getRunId()

Gets the value of the parameter runId.

Returns:

The given runId or null if this parameter has no value.

getExecutionDuration

public final long getExecutionDuration()

Gets the value of the parameter executionDuration.

Returns:

The given executionDuration or UWSJob.UNLIMITED_DURATION if this parameter has no value.

getDestructionTime

public final java.util.Date getDestructionTime()

Gets the value of the parameter destruction.

Returns:

The given destruction or null if this parameter has no value.

getAdditionalParameters

public final java.util.Map<java.lang.String,java.lang.Object> getAdditionalParameters()

Gets the list of all UWS additional parameters (all these parameters are associated with the parameter name UWSJob.PARAM_PARAMETERS).

WARNING: The result of this function MUST BE used ONLY in READ-ONLY. Any modification applied to the returned map will NEVER be propagated to this instance of UWSParameters ! You should rather use set(String, Object) to add/update/remove an additional parameters !

Returns:

All the UWS additional parameters.