XMLRequestParser

java.lang.Object
- uws.service.request.XMLRequestParser

All Implemented Interfaces:

RequestParser
```
public class XMLRequestParser
extends java.lang.Object
implements RequestParser
```
This parser aims to copy the full content of an HTTP request if it is identified as an XML document.
UWS's Job Description

Actually, this parser implements the possibility defined in the UWS 1.0 standard to provide an XML document describing the parameters of a UWS job. This XML document is then called "Job Description".

Validation

In the UWS 1.0 standard, it is said that this Job Description has to follow a Job Description Language (JDL ; that's to say a known pattern describing the expected job parameters) dependent of the UWS service implementation.

By default, this parser copies the request content and checks it is an XML document. Nothing else is done, and particularly not the validation of its content. To do so, a particular service implementation can extend this class and overwrite its function validate(InputStream). By default this function just ensures the request content is a valid XML document.

Document access

Once parsed, the request content will be made accessible through an HttpServletRequest attribute under the name "UWS_JOB_DESCRIPTION". The associated object is typed as an XMLJobInfo.

Note: Afterwards, it is intended to be attached to a UWSJob and then made accessible through its function UWSJob.getJobInfo().

Document storage

XMLJobInfo gives two storage possibility:
1. in memory with the constructor XMLJobInfo(String)
2. in a file with the constructor XMLJobInfo(UploadFile)
The storage chosen by this parser depends on the size of the input document. If it exceeds SMALL_XML_THRESHOLD (expressed in bytes), then the document will be stored inside a file. Otherwise it will be kept in memory. To change this threshold, it is just needed to set the static field SMALL_XML_THRESHOLD to the desired value (in bytes). By default, it is set to 2048 bytes.

Important: It is possible to prevent the unwanted storage of a very large document by setting the limit SIZE_LIMIT to a different value (in bytes). If the input document exceeds this size, the request will be rejected with an 413 (REQUEST ENTITY TOO LARGE) error. By default this limit is set to 204800 bytes.
Since:

4.2

Version:

4.2 (06/2017)

Author:

Grégory Mantelet (ARI)

Field Summary

Fields
Modifier and Type	Field and Description
`static int`	`DEFAULT_SIZE_LIMIT` Default maximum allowed size for an HTTP request content: 200 kiB.
`static int`	`DEFAULT_SMALL_XML_THRESHOLD` Default threshold for XML document that can be kept entirely in memory: 2 kiB.
`protected UWSFileManager`	`fileManager` File manager to use to create `UploadFile` instances.
`static int`	`SIZE_LIMIT` Maximum allowed size for an HTTP request content.
`static int`	`SMALL_XML_THRESHOLD` This threshold determines whether an XML request content should be stored in memory or inside a file.

Constructor Summary

Constructors
Constructor and Description

XMLRequestParser(UWSFileManager fileManager)
Build the request parser.

Constructors
Constructor and Description
`XMLRequestParser(UWSFileManager fileManager)` Build the request parser.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`static boolean`	`isXMLRequest(javax.servlet.http.HttpServletRequest request)` Utility method that determines whether the content of the given request is an XML (or XML-derived) document.
`java.util.Map<java.lang.String,java.lang.Object>`	`parse(javax.servlet.http.HttpServletRequest request)` Extract parameters from the given HTTP request.
`protected void`	`validate(java.io.File xmlFile)` Validate the specified XML document.
`protected void`	`validate(java.io.InputStream input)` Validate the given XML document.
`protected void`	`validate(java.lang.String smallXML)` Validate the given XML document.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - DEFAULT_SIZE_LIMIT
```
public static final int DEFAULT_SIZE_LIMIT
```
    Default maximum allowed size for an HTTP request content: 200 kiB.
    
    See Also:
    
    Constant Field Values
  - SIZE_LIMIT
```
public static int SIZE_LIMIT
```
    Maximum allowed size for an HTTP request content. Over this limit, an exception is thrown and the request is aborted.
    
    Note: The default value is DEFAULT_SIZE_LIMIT (= 204800 Bytes).
    
    Note: This limit is expressed in bytes and can not be negative. Its smallest possible value is 0. If the set value is though negative, it will be ignored and DEFAULT_SIZE_LIMIT will be used instead.
  - DEFAULT_SMALL_XML_THRESHOLD
```
public static final int DEFAULT_SMALL_XML_THRESHOLD
```
    Default threshold for XML document that can be kept entirely in memory: 2 kiB.
    
    See Also:
    
    Constant Field Values
  - SMALL_XML_THRESHOLD
```
public static int SMALL_XML_THRESHOLD
```
    This threshold determines whether an XML request content should be stored in memory or inside a file.
    In short: between 0 and this value, the XML document will be stored in memory ; above this value, it will be stored in a file.
  - fileManager
```
protected final UWSFileManager fileManager
```
    File manager to use to create UploadFile instances. It is required by this new object to execute open, move and delete operations whenever it could be asked.
- Constructor Detail
  - XMLRequestParser
```
public XMLRequestParser(UWSFileManager fileManager)
```
    Build the request parser.
    
    Parameters:
    
    fileManager - A file manager. Must NOT be NULL.
- Method Detail
  - parse
```
public java.util.Map<java.lang.String,java.lang.Object> parse(javax.servlet.http.HttpServletRequest request)
                                                       throws UWSException
```
    Description copied from interface: RequestParser
    
    Extract parameters from the given HTTP request.
    
    These parameters can be fetched from ServletRequest.getParameterMap() or directly from the full request content. In this last case, a parsing is necessary ; hence this function.
    
    In case a parameter is provided several times with the same time and the same case, the request parser can choose to keep only the last occurrence or all occurrences. If all occurrences are kept, this function MUST return an array of Objects (in which types may be mixed), otherwise a map value MUST be an elementary object.
    
    Note: A parameter item can be a simple value (e.g. String, integer, ...) or a more complex object (e.g. File, InputStream, ...).
    
    IMPORTANT: This function MUST NOT be used to check the parameters' value. It only aims to parse the given request in order to extract its embedded parameters.
    Consequently, if this function throws an exception, it could be only because the request can not be read, and not because a parameter format or value is incorrect.
    Parameter checks should be done in UWSParameters and more particularly by an InputParamController.
    
    Specified by:
    
    parse in interface RequestParser
    
    Parameters:
    
    request - An HTTP request.
    
    Returns:
    
    A map listing all extracted parameters. Values are either an elementary object (whatever is the type), or an array of Objects (in which types can be mixed).
    
    Throws:
    
    UWSException - If any error provides this function to read the parameters.
  - validate
```
protected void validate(java.lang.String smallXML)
                 throws UWSException
```
    Validate the given XML document.
    By default, it is only ensured this document is an XML one.
    
    Parameters:
    
    smallXML - The document to check.
    
    Throws:
    
    UWSException - If the given document is not valid.
    
    See Also:
    
    validate(InputStream)
  - validate
```
protected void validate(java.io.File xmlFile)
                 throws UWSException
```
    Validate the specified XML document.
    By default, it is only ensured this document is an XML one.
    
    Parameters:
    
    xmlFile - The file containing the document to check.
    
    Throws:
    
    UWSException - If the specified document is not valid.
    
    See Also:
    
    validate(InputStream)
  - validate
```
protected void validate(java.io.InputStream input)
                 throws UWSException
```
    Validate the given XML document.
    By default, it is only ensured this document is an XML one.
    
    Parameters:
    
    input - Stream toward the document to check.
    
    Throws:
    
    UWSException - If the given document is not valid.
  - isXMLRequest
```
public static final boolean isXMLRequest(javax.servlet.http.HttpServletRequest request)
```
    Utility method that determines whether the content of the given request is an XML (or XML-derived) document.
    Important: This function just tests the content-type of the request. Neither the HTTP method (e.g. GET, POST, ...) nor the content is tested.
    
    Parameters:
    
    request - The servlet request to be evaluated. Must NOT be NULL.
    
    Returns:
    
    true if the request is an XML document, false otherwise.

Class XMLRequestParser

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

DEFAULT_SIZE_LIMIT

SIZE_LIMIT

DEFAULT_SMALL_XML_THRESHOLD

SMALL_XML_THRESHOLD

fileManager

Constructor Detail

XMLRequestParser

Method Detail

parse

validate

validate

validate

isXMLRequest