tap.parameters

Class DALIUpload

java.lang.Object

tap.parameters.DALIUpload

public class DALIUpload
extends java.lang.Object

Description of an uploaded content specified using the DALI/TAP syntax.

How to access the upload content?

This parameter is either a reference to a distant content and is then specified by a URI, or a pointer to the stored version of a file submitted inline in a HTTP request. In both cases, this class lets access the upload content with the function open().

How to get DALIUpload objects from HTTP request parameters?

The static function getDALIUploads(Map, boolean, UWSFileManager) should be used in order to extract the DALIUpload items specified in a list of request parameters.

Note: It is recommended to provide these parameters as a map generated by a RequestParser. If not, you should ensure that values of the map associated to the "UPLOAD" parameter(s) are Strings, String[]s, DALIUploads, DALIUpload[]s or Object[] containing Strings and/or DALIUploads. Besides, the request parameters referenced using the syntax "param:{param-name}" must be instances of only UploadFile or an array of Objects containing at least one UploadFile instance (if several are found, just the last one will be used).

Calling this function will also modify a little the given list of parameters by rewriting the "UPLOAD" parameter and removing unreferenced uploaded files (from the list and from the file-system).

Reminder about the "UPLOAD" parameter

The IVOA standards DAL and TAP define both the same special parameter: "UPLOAD" (not case-sensitive).

This parameter lists all upload items. A such item can be either an inline file or a reference to a distant file. In both cases, it is specified as a URI. The parameter "UPLOAD" sets also a label/name to this item. The syntax to use for a single item is the following: "{label},{URI}". Several items can be provided, but there is a slight difference between DALI and TAP in the way to do it. DALI says that multiple uploads MUST be done by several submit of a single "UPLOAD" parameter with the syntax described above. TAP says that multiple uploads CAN be done in one "UPLOAD" parameter by separating each item with a semicolon (;). For instance:

• In TAP: "UPLOAD=tableA,param:foo;tableB,http://..." => only 1 parameter for 2 uploads
• In DALI: "UPLOAD=tableA,param:foo" and "UPLOAD=tableB,http://..." => 2 parameters, one for each upload

Note: The drawback of the TAP method is: what happens when a URI contains a semicolon? URI can indeed contain a such character and in this case the parsing becomes more tricky, or even impossible in some cases. In such cases, it is strongly recommended to either encode the URI (so the ";" becomes "%3B") or to forbid the TAP syntax. This latter can be done by setting the second parameter of getDALIUploads(Map, boolean, UWSFileManager) to false.

Since:

2.0

Version:

2.0 (12/2014)

Author:

Grégory Mantelet (ARI)

See Also:

RequestParser

Field Summary

Fields

Modifier and Type	Field and Description
protected static java.lang.String	DALI_UPLOAD_REGEXP Regular expression of an UPLOAD parameter as defined by DALI (REC-DALI-1.0-20131129).
UploadFile	file Pointer to the stored version of the file submitted inline in a HTTP request.
protected UWSFileManager	fileManager The file manager to use when a stream will be opened toward the given URI.
java.lang.String	label Name to use in the service to label this upload.
protected static java.lang.String	TAP_UPLOAD_REGEXP Regular expression of an UPLOAD parameter as defined by TAP (REC-TAP-1.0).
java.net.URI	uri URI toward a distant resource.

Constructor Summary

Constructors

Constructor and Description
DALIUpload(java.lang.String label, UploadFile file) Build a DALIUpload whose the content has been submitted inline in an HTTP request.
DALIUpload(java.lang.String label, java.net.URI uri, UWSFileManager fileManager) Build a DALIUpload whose the content is distant and specified by a URI.

Method Summary

Modifier and Type	Method and Description
protected static DALIUpload	buildDALIUpload(java.lang.String label, java.lang.String uri, java.util.Map<java.lang.String,java.lang.Object> parameters, UWSFileManager fileManager) Build a DALIUpload corresponding to the specified URI.
protected static DALIUpload	fetchDALIUpload(java.lang.String uploadParam, java.util.Map<java.lang.String,java.lang.Object> parameters, UWSFileManager fileManager) Fetch the single upload item (a pair with the syntax: "{label},{URI}".
protected static void	fetchDALIUploads(java.util.ArrayList<DALIUpload> uploads, java.util.ArrayList<java.lang.String> usedFiles, java.lang.String uploadParam, java.util.Map<java.lang.String,java.lang.Object> parameters, boolean allowTAPSyntax, UWSFileManager fileManager) Fetch all uploads specified in the DALI/TAP "UPLOAD" parameter.
static java.util.List<DALIUpload>	getDALIUploads(java.util.Map<java.lang.String,java.lang.Object> requestParams, boolean allowTAPSyntax, UWSFileManager fileManager) Get all uploads specified in the DALI parameter "UPLOAD" from the given request parameters.
boolean	isByReference() Tell whether this upload is actually a reference toward a distant resource.
java.io.InputStream	open() Open a stream to the content of this upload.
protected static java.lang.String[]	parseDALIParam(java.lang.String definition) Extract the two parts (label and URI) of the given DALI parameter, and then, check their syntax.
java.lang.String	toString()

Methods inherited from class java.lang.Object

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

Field Detail

file

public final UploadFile file

Pointer to the stored version of the file submitted inline in a HTTP request.

Note: If NULL, this DALIUpload is then a "byReference" upload, meaning that its content is distant and can be accessed only with the URI uri.

uri

public final java.net.URI uri

URI toward a distant resource.

Note: If NULL, this DALIUpload corresponds to a file submitted inline in a HTTP request. Its content has then been stored by this service and can be accessed using the pointer file.

label

public final java.lang.String label

Name to use in the service to label this upload.

Note: In a TAP service, this label is the name of the table to create in the database when creating the corresponding table inside it.

fileManager

protected final UWSFileManager fileManager

The file manager to use when a stream will be opened toward the given URI. It should know how to access it, because the URI can use a URL scheme (http, https, ftp) but also another scheme unknown by the library (e.g. ivo, vos).

DALI_UPLOAD_REGEXP

protected static final java.lang.String DALI_UPLOAD_REGEXP

Regular expression of an UPLOAD parameter as defined by DALI (REC-DALI-1.0-20131129).

Note: In DALI, multiple uploads must be done by posting several UPLOAD parameters. It is not possible to provide directly a list of parameters as in TAP. However, the advantage of the DALI method is to allow ; in URI (while ; is the parameter separator in TAP).

See Also:

Constant Field Values

TAP_UPLOAD_REGEXP

protected static final java.lang.String TAP_UPLOAD_REGEXP

Regular expression of an UPLOAD parameter as defined by TAP (REC-TAP-1.0).

Note: In TAP, multiple uploads may be done by POSTing only one UPLOAD parameter whose the value is a list of DALI UPLOAD parameters, separated by a ;

See Also:

Constant Field Values

Constructor Detail

DALIUpload

public DALIUpload(java.lang.String label,
                  UploadFile file)

Build a DALIUpload whose the content has been submitted inline in an HTTP request.

A such upload has been specified by referencing another HTTP request parameter containing an inline file. The used syntax was then: "{label},param:{param-name}".

Parameters:

label - Label of the DALIUpload (i.e. {label} inside an "UPLOAD" parameter value "{label},{URI}"). Note: If NULL, the file name will be used as label.

file - Pointer to the uploaded file.

DALIUpload

public DALIUpload(java.lang.String label,
                  java.net.URI uri,
                  UWSFileManager fileManager)

Build a DALIUpload whose the content is distant and specified by a URI.

A such upload has been specified by referencing a URI (whose the scheme is different from "param"). The used syntax was then: "{label},{URI}".

Parameters:

label - Label of the DALIUpload (i.e. {label} inside an "UPLOAD" parameter value "{label},{URI}"). Note: If NULL, the URI will be used as label.

uri - URI toward a distant file. The scheme of this URI must be different from "param". This scheme is indeed reserved by the DALI syntax to reference a HTTP request parameter containing an inline file.

fileManager - The file manager to use when a stream will be opened toward the given URI. This file manager should know how to access it, because the URI can use a URL scheme (http, https, ftp) but also another scheme unknown by the library (e.g. ivo, vos).

Method Detail

isByReference

public boolean isByReference()

Tell whether this upload is actually a reference toward a distant resource.

Returns:

true if this upload is referenced by a URI, false if the upload has been submitted inline in the HTTP request.

open

public java.io.InputStream open()
                         throws UnsupportedURIProtocolException,
                                java.io.IOException

Open a stream to the content of this upload.

Returns:

An InputStream.

Throws:

UnsupportedURIProtocolException - If the URI of this upload item is using a protocol not supported by this service implementation.

java.io.IOException - If the stream can not be opened.

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

getDALIUploads

public static final java.util.List<DALIUpload> getDALIUploads(java.util.Map<java.lang.String,java.lang.Object> requestParams,
                                                              boolean allowTAPSyntax,
                                                              UWSFileManager fileManager)
                                                       throws TAPException

Get all uploads specified in the DALI parameter "UPLOAD" from the given request parameters.

Note: This function is case INsensitive for the "UPLOAD" parameter.

WARNING: Calling this function modifies the given map ONLY IF the "UPLOAD" parameter (whatever is its case) is found. In such case, the following modifications are applied:

• All "UPLOAD" parameters will be removed and then added again in the map with their corresponding DALIUpload item (not any more a String).
• If allowTAPSyntax is true, several uploads may be specified in the same "UPLOAD" parameter value. For more clarity for the user (once the parameters listed), this list of uploads will be split in the same number of "UPLOAD" parameters. That's to say, there will be only one "UPLOAD" item in the Map, but its value will be an array containing every specified uploads: an array of DALIUpload objects.
• If there is at least one "UPLOAD" parameter, all uploaded files (parameters associated with instances of UploadFile) will be removed from the map (and also from the file system). They are indeed not useful for a DALI service since all interesting uploads have already been listed.

Note: This function can be called several times on the same map. After a first call, this function will just gathers into a List all found DALIUpload objects. Of course, only uploads specified in the "UPLOAD" parameter(s) will be returned and others will be removed as explained above.

DALI and TAP syntax

The "UPLOAD" parameter lists all files to consider as uploaded. The syntax for one item is the following: "{name},{uri}", where {uri} is "param:{param-ref}" when the file is provided inline in the parameter named {param-ref}, otherwise, it can be any valid URI (http:..., ftp:..., vos:..., ivo:..., etc...).

The parameter allowTAPSyntax lets switch between the DALI and TAP syntax. The only difference between them, is in the way to list multiple uploads. In TAP, they can be given as a semicolon separated list in a single parameter, whereas in DALI, there must be submitted as several individual parameters. For instance:

• In TAP: "UPLOAD=tableA,param:foo;tableB,http://..." => only 1 parameter
• In DALI: "UPLOAD=tableA,param:foo" and "UPLOAD=tableB,http://..." => 2 parameters

Note: Because of the possible presence of a semicolon in a URI (which is also used as separator of uploads in the TAP syntax), there could be a problem while splitting the uploads specified in "UPLOAD". In that case, it is strongly recommended to either encode the URI (in UTF-8) (i.e. ";" becomes "%3B") or to merely restrict the syntax to the DALI one. In this last case, the parameter "allowTAPSyntax" should be set to false and then all parameters should be submitted individually.

Parameters:

requestParams - All parameters extracted from an HTTP request by a RequestParser.

allowTAPSyntax - true to allow a list of several upload items in one "UPLOAD" parameter value (each item separated by a semicolon), false to forbid it (and so, multiple upload items shall be submitted individually).

fileManager - The file manager to use in order to build a DALIUpload objects from a URI. (a link to the file manager will be set in the DALIUpload object in order to open it whenever it will asked after its creation)

Returns:

List of all uploads specified with the DALI or TAP syntax.

Throws:

TAPException - If the syntax of an "UPLOAD" parameter is wrong.

See Also:

RequestParser.parse(javax.servlet.http.HttpServletRequest)

fetchDALIUploads

protected static void fetchDALIUploads(java.util.ArrayList<DALIUpload> uploads,
                                       java.util.ArrayList<java.lang.String> usedFiles,
                                       java.lang.String uploadParam,
                                       java.util.Map<java.lang.String,java.lang.Object> parameters,
                                       boolean allowTAPSyntax,
                                       UWSFileManager fileManager)
                                throws TAPException

Fetch all uploads specified in the DALI/TAP "UPLOAD" parameter. The fetched DALIUploads are added in the given ArrayList.

Note: A DALI upload can be either a URI or an inline file (specified as "param:{param-ref}").

Parameters:

uploads - List of DALIUploads. to update.

usedFiles - List of the the names of the referenced file parameters. to update.

uploadParam - Value of the "UPLOAD" parameter.

parameters - List of all extracted parameters (including UploadFile(s)).

allowTAPSyntax - true to allow a list of several upload items in one "UPLOAD" parameter value (each item separated by a semicolon), false to forbid it (and so, multiple upload items shall be submitted individually).

fileManager - The file manager to use in order to build a DALIUpload objects from a URI. (a link to the file manager will be set in the DALIUpload object in order to open it whenever it will asked after its creation)

Throws:

TAPException - If the syntax of the given "UPLOAD" parameter is incorrect.

fetchDALIUpload

protected static DALIUpload fetchDALIUpload(java.lang.String uploadParam,
                                            java.util.Map<java.lang.String,java.lang.Object> parameters,
                                            UWSFileManager fileManager)
                                     throws TAPException

Fetch the single upload item (a pair with the syntax: "{label},{URI}".

Parameters:

uploadParam - Value of the "UPLOAD" parameter. A single upload item is expected ; that's to say something like "{label},{URI}".

parameters - List of extracted parameters. The fetched LOB must be added as a new parameter in this map. MUST not be NULL

fileManager - The file manager to use in order to build a DALIUpload objects from a URI. (a link to the file manager will be set in the DALIUpload object in order to open it whenever it will asked after its creation)

Returns:

The corresponding DALIUpload object.

Throws:

TAPException - If the syntax of the given "UPLOAD" parameter is incorrect.

See Also:

parseDALIParam(String), buildDALIUpload(String, String, Map, UWSFileManager)

parseDALIParam

protected static java.lang.String[] parseDALIParam(java.lang.String definition)
                                            throws TAPException

Extract the two parts (label and URI) of the given DALI parameter, and then, check their syntax.

Important note: It MUST be ensured before calling this function that the given DALI parameter is not NULL and contains at least one comma (,).

The first comma found in the given string will be the separator of the two parts of the given DALI parameter: {label},{URI}

The label part - {label} - must start with one letter and may be followed by a letter, a digit or an underscore. The corresponding regular expression is: [a-zA-Z][a-zA-Z0-9_]*

The URI part - {URI} - must start with a scheme, followed by a colon (:) and then by several characters (no restriction). A scheme must start with one letter and may be followed by a letter, a digit, a plus (+), a dot (.) or an hyphen/minus (-). The corresponding regular expression is: [a-zA-Z][a-zA-Z0-9\+\.-]*

Parameters:

definition - MUST BE A PAIR label,value

Returns:

An array of exactly 2 items: [0]=upload label/name, [1]=an URI. (note: the special DALI syntax "param:..." is also a valid URI)

Throws:

TAPException - If the given upload definition is not following the valid DALI syntax.

buildDALIUpload

protected static final DALIUpload buildDALIUpload(java.lang.String label,
                                                  java.lang.String uri,
                                                  java.util.Map<java.lang.String,java.lang.Object> parameters,
                                                  UWSFileManager fileManager)
                                           throws TAPException

Build a DALIUpload corresponding to the specified URI.

If the URI starts, case-insensitively, with "param:", it is then a reference to another request parameter containing a file content. In this case, the file content has been already stored inside a local file and represented by an UploadFile instance in the map.

If the URI does not start with "param:", the DALI upload is considered as a reference to a distant file which can be accessed using this URI. Any URI scheme is allowed here, but the given file manager should be able to interpret it and open a stream toward the referenced resource whenever it will be asked.

Note: If the URI is not a parameter reference (i.e. started by "param:"), it will be decoded using URLDecoder.decode(String, String) (character encoding: UTF-8).

Parameters:

label - Label of the DALIUpload to build.

uri - URI of the LOB. MUST be NOT-NULL

parameters - All parameters extracted from an HTTP request by a RequestParser.

fileManager - The file manager to use in order to build a DALIUpload objects from a URI. (a link to the file manager will be set in the DALIUpload object in order to open it whenever it will asked after its creation)

Returns:

The corresponding DALIUpload object.

Throws:

TAPException - If the parameter reference is broken or if the given URI has a wrong syntax.