UWSToolBox

java.lang.Object
- uws.UWSToolBox

```
public class UWSToolBox
extends java.lang.Object
```
Some useful functions for the managing of a UWS service.

Version:

4.4 (03/2019)

Author:

Grégory Mantelet (CDS;ARI)

Field Summary

Fields
Modifier and Type	Field and Description
`static java.lang.String`	`DEFAULT_CHAR_ENCODING` Default character encoding for all HTTP response sent by this library.
`protected static java.lang.String[]`	`fileExts` List of file extensions whose the MIME type is known (see `mimeTypes`).
`protected static java.lang.String[]`	`mimeTypes` List of known MIME types (see `fileExts`).

Method Summary

All Methods Static Methods Concrete Methods
Modifier and Type	Method and Description
`static java.util.Map<java.lang.String,java.lang.Object>`	`addGETParameters(javax.servlet.http.HttpServletRequest req, java.util.Map<java.lang.String,java.lang.Object> parameters)` Extract only the GET parameters from the given HTTP request and add them inside the given map.
`static void`	`clearDirectory(java.io.File directory)` Empties the specified directory.
`static void`	`clearDirectory(java.lang.String directoryPath)` Empties the specified directory.
`static int`	`deleteUploads(javax.servlet.http.HttpServletRequest req)` Delete all unused uploaded files of the given request.
`static void`	`flush(java.io.PrintWriter writer)` Flush the buffer of the given `PrintWriter`.
`static UWSLog`	`getDefaultLogger()` Gets the default `UWSLog` instance.
`static java.lang.String`	`getFileExtension(java.lang.String mimeType)` Gets the file extension corresponding to the given MIME type.
`static java.lang.String`	`getMimeType(java.lang.String fileExtension)` Gets the MIME type corresponding to the given file extension.
`static int`	`getNbParameters(javax.servlet.http.HttpServletRequest request)` Get the number of parameters submitted in the given HTTP request.
`static java.lang.Object`	`getParameter(java.lang.String name, javax.servlet.http.HttpServletRequest request, boolean caseSensitive)` Get the parameter specified by the given name from the given HTTP request.
`static java.util.Map<java.lang.String,java.lang.String>`	`getParameters(java.lang.String queryPart)` Converts the given query part of a HTTP-GET URL to a map of parameters.
`static java.util.Map<java.lang.String,java.lang.String>`	`getParamsMap(javax.servlet.http.HttpServletRequest req)` Builds a map of strings with all parameters of the given HTTP request.
`static java.lang.String`	`getQueryPart(java.util.Map<java.lang.String,java.lang.String> parameters)` Converts map of UWS parameters into a string corresponding to the query part of a HTTP-GET URL (i.e.
`static java.net.URL`	`getServerResource(java.lang.String serverPath, javax.servlet.http.HttpServletRequest req)` Lets building the absolute URL of any resource available in the root server, from a relative URL.
`static JobOwner`	`getUser(javax.servlet.http.HttpServletRequest request, UserIdentifier userIdentifier)` Extract the user/job owner from the given HTTP request.
`static boolean`	`hasParameter(java.lang.String name, javax.servlet.http.HttpServletRequest request, boolean caseSensitive)` Check whether a parameter has been submitted with the given name.
`static boolean`	`hasParameter(java.lang.String name, java.lang.String value, javax.servlet.http.HttpServletRequest request, boolean caseSensitive)` Check whether the parameter specified with the given pair (name,value) exists in the given HTTP request.
`static void`	`printStackTrace(java.lang.Throwable ex, java.io.PrintWriter pw)` Prints the full stack trace of the given exception in the given writer.
`static void`	`printURL(UWSUrl url)` Displays all the fields of the given UWSUrl.
`static void`	`printURL(UWSUrl url, java.io.OutputStream output)` Displays all the fields of the given UWSUrl in the given output stream.
`static void`	`setContentLength(javax.servlet.http.HttpServletResponse response, long contentSize)` Set the content length in the given `HttpServletResponse`.
`static void`	`write(java.io.InputStream input, java.lang.String mimeType, long contentSize, javax.servlet.http.HttpServletResponse response)` Copies the content of the given input stream in the given HTTP response.
`static boolean`	`writeErrorFile(java.lang.Exception ex, ErrorSummary error, UWSJob job, java.io.OutputStream output)` Writes the stack trace of the given exception in the file whose the name and the parent directory are given in parameters.

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

- Field Detail
  - DEFAULT_CHAR_ENCODING
```
public static final java.lang.String DEFAULT_CHAR_ENCODING
```
    Default character encoding for all HTTP response sent by this library.
    
    Since:
    
    4.1
    
    See Also:
    
    Constant Field Values
  - fileExts
```
protected static final java.lang.String[] fileExts
```
    List of file extensions whose the MIME type is known (see mimeTypes).
  - mimeTypes
```
protected static final java.lang.String[] mimeTypes
```
    List of known MIME types (see fileExts).
- Method Detail
  - getServerResource
```
public static final java.net.URL getServerResource(java.lang.String serverPath,
                                                   javax.servlet.http.HttpServletRequest req)
```
    Lets building the absolute URL of any resource available in the root server, from a relative URL.
    
    For instance, if the server URL is http://foo.org/uwstuto (and whatever is the current URL):
    - if you want the URL of the html page "basic.html" of the root directory: servletPath="/basic.html" => returned URL=http://foo.org/uwstuto/basic.html
    - if you want the URL of the image "ivoa.png" contained into the directory "images": servletPath="/images/ivoa.png" => returned URL="http://foo.org/uwstuto/images/ivoa.png"
    Parameters:
    
    serverPath - The relative path to access a server resource.
    
    req - A request of the servlet.
    
    Returns:
    
    The absolute URL to access the desired server resource or null if one of the parameter is null or if a well-formed URL can not be built.
    
    See Also:
    
    HttpServletRequest.getRequestURL(), HttpServletRequest.getContextPath(), URL.URL(String)
  - getDefaultLogger
```
public static final UWSLog getDefaultLogger()
```
    Gets the default UWSLog instance. Any log message will be print on the standard error output (System.err).
    
    Returns:
    
    The default UWSLog instance.
  - getParamsMap
```
public static final java.util.Map<java.lang.String,java.lang.String> getParamsMap(javax.servlet.http.HttpServletRequest req)
```
    Builds a map of strings with all parameters of the given HTTP request.
    
    Note: If the request attribute UWS.REQ_ATTRIBUTE_PARAMETERS has been already set by the UWS library, this map (after conversion into a Map) is returned. Otherwise, the parameters identified automatically by the Servlet are returned (just the last occurrence of each parameter is kept).
    
    WARNING: This function does not extract directly the parameters from the request content. It is just returning those already extracted either by the Servlet or by a RequestParser.
    
    Parameters:
    
    req - The HTTP request which contains the parameters to extract.
    
    Returns:
    
    The corresponding map of string.
  - getQueryPart
```
public static final java.lang.String getQueryPart(java.util.Map<java.lang.String,java.lang.String> parameters)
```
    Converts map of UWS parameters into a string corresponding to the query part of a HTTP-GET URL (i.e. ?EXECUTIONDURATION=60&DESTRUCTION=2010-09-01T13:58:00:000-0200).
    
    Parameters:
    
    parameters - A Map of parameters.
    
    Returns:
    
    The corresponding query part of an HTTP-GET URL (all keys have been set in upper case).
  - getParameters
```
public static final java.util.Map<java.lang.String,java.lang.String> getParameters(java.lang.String queryPart)
```
    Converts the given query part of a HTTP-GET URL to a map of parameters.
    
    Parameters:
    
    queryPart - A query part of a HTTP-GET URL.
    
    Returns:
    
    The corresponding map of parameters (all keys have been set in lower case).
  - addGETParameters
```
public static final java.util.Map<java.lang.String,java.lang.Object> addGETParameters(javax.servlet.http.HttpServletRequest req,
                                                                                      java.util.Map<java.lang.String,java.lang.Object> parameters)
```
    Extract only the GET parameters from the given HTTP request and add them inside the given map.
    
    Warning: If entries with the same key already exist in the map, they will overwritten.
    
    Parameters:
    
    req - The HTTP request whose the GET parameters must be extracted.
    
    parameters - List of parameters to update.
    
    Returns:
    
    The same given parameters map (but updated with all found GET parameters).
    
    Since:
    
    4.1
  - getNbParameters
```
public static final int getNbParameters(javax.servlet.http.HttpServletRequest request)
```
    Get the number of parameters submitted in the given HTTP request.
    
    Parameters:
    
    request - An HTTP request;
    
    Returns:
    
    The number of submitted parameters.
    
    Since:
    
    4.1
  - hasParameter
```
public static final boolean hasParameter(java.lang.String name,
                                         javax.servlet.http.HttpServletRequest request,
                                         boolean caseSensitive)
```
    Check whether a parameter has been submitted with the given name.
    
    Parameters:
    
    name - Name of the parameter to search. The case is important!
    
    request - HTTP request in which the specified parameter must be searched.
    
    caseSensitive - true to perform the research case-sensitively, false for a case INsensitive research.
    
    Returns:
    
    true if the specified parameter has been found, false otherwise.
    
    Since:
    
    4.1
  - hasParameter
```
public static final boolean hasParameter(java.lang.String name,
                                         java.lang.String value,
                                         javax.servlet.http.HttpServletRequest request,
                                         boolean caseSensitive)
```
    Check whether the parameter specified with the given pair (name,value) exists in the given HTTP request.
    
    Parameters:
    
    name - Name of the parameter to search.
    
    value - Expected value of the parameter.
    
    request - HTTP request in which the given pair must be searched.
    
    caseSensitive - true to perform the research (on name AND value) case-sensitively, false for a case INsensitive research.
    
    Returns:
    
    true if the specified parameter has been found with the given value in the given HTTP request, false otherwise.
    
    Since:
    
    4.1
  - getParameter
```
public static final java.lang.Object getParameter(java.lang.String name,
                                                  javax.servlet.http.HttpServletRequest request,
                                                  boolean caseSensitive)
```
    Get the parameter specified by the given name from the given HTTP request.
    
    Parameters:
    
    name - Name of the parameter to search.
    
    request - HTTP request in which the given pair must be searched.
    
    caseSensitive - true to perform the research case-sensitively, false for a case INsensitive research.
    
    Returns:
    
    Value of the parameter.
    
    Since:
    
    4.1
  - deleteUploads
```
public static final int deleteUploads(javax.servlet.http.HttpServletRequest req)
```
    Delete all unused uploaded files of the given request.
    
    These files have been stored on the file system if there is a request attribute named UWS.REQ_ATTRIBUTE_PARAMETERS.
    
    Parameters:
    
    req - Request in which files have been uploaded.
    
    Returns:
    
    The number of deleted files.
    
    Since:
    
    4.1
    
    See Also:
    
    UploadFile.isUsed()
  - getUser
```
public static final JobOwner getUser(javax.servlet.http.HttpServletRequest request,
                                     UserIdentifier userIdentifier)
                              throws java.lang.NullPointerException,
                                     UWSException
```
    Extract the user/job owner from the given HTTP request.
    Two cases are supported:
    1. The user has already been identified and is stored in the HTTP attribute UWS.REQ_ATTRIBUTE_USER => the stored value is returned.
    2. No HTTP attribute and a UserIdentifier is provided => the user is identified with the given UserIdentifier and stored in the HTTP attribute UWS.REQ_ATTRIBUTE_USER before being returned.
    In any other case, NULL is returned.
    Parameters:
    
    request - The HTTP request from which the user must be extracted. note: if NULL, NULL will be returned.
    
    userIdentifier - The method to use in order to extract a user from the given request. note: if NULL, NULL is returned IF no HTTP attribute UWS.REQ_ATTRIBUTE_USER can be found.
    
    Returns:
    
    The identified user. MAY be NULL
    
    Throws:
    
    java.lang.NullPointerException - If an error occurs while extracting a UWSUrl from the given HttpServletRequest.
    
    UWSException - If any error occurs while extracting a user from the given HttpServletRequest.
    
    Since:
    
    4.1
  - clearDirectory
```
public static final void clearDirectory(java.lang.String directoryPath)
```
    Empties the specified directory.
    
    Parameters:
    
    directoryPath - The path of the directory to empty.
  - clearDirectory
```
public static final void clearDirectory(java.io.File directory)
```
    Empties the specified directory.
    
    Note: The directory is NOT deleted. Just its content is destroyed.
    
    Parameters:
    
    directory - The directory which has to be emptied.
  - flush
```
public static final void flush(java.io.PrintWriter writer)
                        throws ClientAbortException
```
    Flush the buffer of the given PrintWriter.
    
    This function aims to be used if the given PrintWriter has been provided by an HttpServletResponse. In such case, a call to its flush() function may generate a silent error which could only mean that the connection with the HTTP client has been closed.
    
    Parameters:
    
    writer - The writer to flush.
    
    Throws:
    
    ClientAbortException - If the connection with the HTTP client is closed.
    
    Since:
    
    4.1
    
    See Also:
    
    PrintWriter.flush()
  - write
```
public static final void write(java.io.InputStream input,
                               java.lang.String mimeType,
                               long contentSize,
                               javax.servlet.http.HttpServletResponse response)
                        throws java.io.IOException
```
    Copies the content of the given input stream in the given HTTP response.
    
    Parameters:
    
    input - Data to copy.
    
    mimeType - Type of data to copy (may be null).
    
    contentSize - Size of the file to write.
    
    response - Response in which the data must be copied.
    
    Throws:
    
    java.io.IOException - If there is an error while opening the output stream or while copying.
  - writeErrorFile
```
public static final boolean writeErrorFile(java.lang.Exception ex,
                                           ErrorSummary error,
                                           UWSJob job,
                                           java.io.OutputStream output)
                                    throws java.io.IOException
```
    Writes the stack trace of the given exception in the file whose the name and the parent directory are given in parameters. If the specified file already exists, it will be overwritten if the parameter overwrite is equal to true, otherwise no file will not be changed (default behavior of writeErrorFile(Exception, ErrorSummary, UWSJob, OutputStream)).
    
    Parameters:
    
    ex - The exception which has to be used to generate the error file.
    
    error - The error description.
    
    job - The job which ended with the given error.
    
    output - The stream in which the error description and trace must be written.
    
    Returns:
    
    true if the file has been successfully created, false otherwise.
    
    Throws:
    
    java.io.IOException - If there is an error while writing the description and the stack trace of the given error.
  - printStackTrace
```
public static final void printStackTrace(java.lang.Throwable ex,
                                         java.io.PrintWriter pw)
                                  throws java.io.IOException
```
    Prints the full stack trace of the given exception in the given writer.
    
    Parameters:
    
    ex - The exception whose the stack trace must be printed.
    
    pw - The stream in which the stack trace must be written.
    
    Throws:
    
    java.io.IOException - If there is an error while printing the stack trace.
  - printURL
```
public static final void printURL(UWSUrl url)
```
    Displays all the fields of the given UWSUrl.
    
    Parameters:
    
    url - The UWSUrl which has to be displayed.
    
    See Also:
    
    printURL(UWSUrl, java.io.OutputStream)
  - printURL
```
public static final void printURL(UWSUrl url,
                                  java.io.OutputStream output)
                           throws java.io.IOException
```
    Displays all the fields of the given UWSUrl in the given output stream.
    
    Parameters:
    
    url - The UWSUrl which has to be displayed.
    
    output - The stream in which the fields of the given UWSUrl has to be displayed.
    
    Throws:
    
    java.io.IOException - If there is an error while writing in the given stream.
  - getMimeType
```
public static final java.lang.String getMimeType(java.lang.String fileExtension)
```
    Gets the MIME type corresponding to the given file extension.
    
    Parameters:
    
    fileExtension - File extension (i.e. .txt, json, .xml, xml, ....)
    
    Returns:
    
    The corresponding MIME type or null if not known.
  - getFileExtension
```
public static final java.lang.String getFileExtension(java.lang.String mimeType)
```
    Gets the file extension corresponding to the given MIME type.
    
    Parameters:
    
    mimeType - A MIME type (i.e. text/plain, application/json, application/xml, text/xml, application/x-votable+xml, ....)
    
    Returns:
    
    The corresponding file extension or null if not known.
  - setContentLength
```
public static final void setContentLength(javax.servlet.http.HttpServletResponse response,
                                          long contentSize)
```
    Set the content length in the given HttpServletResponse.
    Implementation note: This could perfectly be done using ServletResponse.setContentLength(int), but only if the content size is encoded or fit in an integer value. Otherwise, that function will set no content length. On the contrary, this current function takes a long value and set manually the content type header.
    
    Note: This function has no effect if the given HttpServletResponse is NULL or if the given content size is ≤ 0.
    
    Parameters:
    
    response - HTTP response.
    
    contentSize - The content size to set.
    
    Since:
    
    4.4

Class UWSToolBox

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

DEFAULT_CHAR_ENCODING

fileExts

mimeTypes

Method Detail

getServerResource

getDefaultLogger

getParamsMap

getQueryPart

getParameters

addGETParameters

getNbParameters

hasParameter

hasParameter

getParameter

deleteUploads

getUser

clearDirectory

clearDirectory

flush

write

writeErrorFile

printStackTrace

printURL

printURL

getMimeType

getFileExtension

setContentLength