uws
Class UWSToolBox

java.lang.Object
  uws.UWSToolBox

public class UWSToolBox
extends java.lang.Object

Some useful functions for the managing of a UWS service.

Version:

02/2011

Author:

Grégory Mantelet (CDS)

Method Summary

static void	clearDirectory(java.io.File directory) Empties the specified directory.
static void	clearDirectory(java.lang.String directoryPath) Empties the specified directory.
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.util.Map<java.lang.String,java.lang.String>	getParamsMap(javax.servlet.http.HttpServletRequest req, java.lang.String userId) Builds a map of strings with all parameters of the given HTTP request and adds the given owner ID if not already in the request parameters.
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 java.lang.String	getUWSNamespace() Deprecated. Replaced by a non-static function in XMLSerializer: XMLSerializer.getUWSNamespace(). It is totally discouraged to use this function.
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 boolean	publishErrorSummary(AbstractJob j, java.lang.Exception ex, ErrorType type, java.lang.String errorFileUri, java.lang.String errorsDirectory, java.lang.String errorFileName) Sets an error summary corresponding to the given Exception with the given error type.
static boolean	publishErrorSummary(AbstractJob j, java.lang.Exception ex, ErrorType type, java.net.URL errorFileUrl, java.lang.String errorsDirectory, java.lang.String errorFileName) Deprecated. Replaced by publishErrorSummary(AbstractJob, Exception, ErrorType, String, String, String)
static boolean	publishErrorSummary(AbstractJob j, java.lang.String msg, ErrorType type) Sets an error summary to the given job with the given message and the given error type and sets the phase member to ERROR.
static AbstractUWS	restoreUWS(java.io.File restoreFile, boolean debug) De-serializes (Java Object de-Serialization) a UWS from the specified file.
static boolean	saveUWS(AbstractUWS uws, java.io.File restoreFile, boolean debug) Serializes (Java Object Serialization) the given UWS in the specified file.
static boolean	writeErrorFile(java.lang.Exception ex, java.lang.String errorsDirectory, java.lang.String errorFileName) Writes the stack trace of the given exception in the file whose the name and the parent directory are given in parameters.
static boolean	writeErrorFile(java.lang.Exception ex, java.lang.String errorsDirectory, java.lang.String errorFileName, boolean overwrite) 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

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)

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: Actually it converts the Map<String, String[]> returned by ServletRequest.getParameterMap() into a Map<String, String> (the key is put in lower case).

Parameters:

req - The HTTP request which contains the parameters to extract.

Returns:

The corresponding map of string.

getParamsMap

public static final java.util.Map<java.lang.String,java.lang.String> getParamsMap(javax.servlet.http.HttpServletRequest req,
                                                                                  java.lang.String userId)

Builds a map of strings with all parameters of the given HTTP request and adds the given owner ID if not already in the request parameters.

Note: Actually it converts the Map<String, String[]> returned by ServletRequest.getParameterMap() into a Map<String, String>.

Parameters:

req - The HTTP request which contains the parameters to extract.

userId - The ID of the current user/owner.

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).

saveUWS

public static final boolean saveUWS(AbstractUWS uws,
                                    java.io.File restoreFile,
                                    boolean debug)

Serializes (Java Object Serialization) the given UWS in the specified file.

Parameters:

uws - The UWS to serialize.

restoreFile - The file in which the given UWS will be serialized.

debug - true to print a debugging message before and after the serialization, false otherwise.

Returns:

true if the UWS has been successfully serialized in the specified file, false otherwise.

restoreUWS

public static final AbstractUWS restoreUWS(java.io.File restoreFile,
                                           boolean debug)
                                    throws javax.servlet.ServletException

De-serializes (Java Object de-Serialization) a UWS from the specified file.

Parameters:

restoreFile - The file which has contains the serialization of a UWS.

debug - true to print a debugging message before and after the de-serialization, false otherwise.

Returns:

The de-serialized UWS or null if there is no corresponding file.

Throws:

javax.servlet.ServletException - If it is impossible to restore a UWS from the specified file.

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.

publishErrorSummary

public static final boolean publishErrorSummary(AbstractJob j,
                                                java.lang.String msg,
                                                ErrorType type)
                                         throws UWSException

Sets an error summary to the given job with the given message and the given error type and sets the phase member to ERROR.

Parameters:

j - The job to update.

msg - The message of the error summary.

type - The type of the error.

Returns:

true if the job has been successfully updated, false otherwise.

Throws:

UWSException - If there is an error when changing the phase or setting the error summary.

See Also:

AbstractJob.error(ErrorSummary)

publishErrorSummary

public static final boolean publishErrorSummary(AbstractJob j,
                                                java.lang.Exception ex,
                                                ErrorType type,
                                                java.lang.String errorFileUri,
                                                java.lang.String errorsDirectory,
                                                java.lang.String errorFileName)
                                         throws java.io.IOException,
                                                UWSException

Sets an error summary corresponding to the given Exception with the given error type.

1. The message of the generated error summary is set to the message of the given exception.
2. The phase is set to ERROR.
3. The stack trace of the given exception is written in the file whose the name and the parent directory are given in parameters.

Note: Even if the error file can not be written, the error summary is set to job... but it would have no URI/URL for the details message !

Parameters:

j - The job to update.

ex - The exception which must be used to generate the error summary.

type - The type of the error.

errorFileUri - The URI/URL at which the content of the error file can be displayed.

errorsDirectory - The parent directory of the generated error file.

errorFileName - The name of the file which must contains the stack trace of the given exception.

Returns:

true if the job has been successfully updated, false otherwise.

Throws:

java.io.IOException - If there is an error during the error file writing.

UWSException - If there is an error when changing the phase or setting the error summary.

See Also:

AbstractJob.error(ErrorSummary), writeErrorFile(Exception, String, String)

writeErrorFile

public static final boolean writeErrorFile(java.lang.Exception ex,
                                           java.lang.String errorsDirectory,
                                           java.lang.String errorFileName)
                                    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, nothing will be done. To overwrite the file use the writeErrorFile(Exception, String, String, boolean) function.

Parameters:

ex - The exception which has to be used to generate the error file.

errorsDirectory - The directory in which the error file must be created.

errorFileName - The name of the file to create.

Returns:

true if the file has been successfully created, false otherwise.

Throws:

java.io.IOException - If there is an error during the file creation.

See Also:

writeErrorFile(Exception, String, String, boolean)

writeErrorFile

public static final boolean writeErrorFile(java.lang.Exception ex,
                                           java.lang.String errorsDirectory,
                                           java.lang.String errorFileName,
                                           boolean overwrite)
                                    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, String, String)).

Parameters:

ex - The exception which has to be used to generate the error file.

errorsDirectory - The directory in which the error file must be created.

errorFileName - The name of the file to create.

overwrite - true to overwrite the file if it already exists, false otherwise.

Returns:

true if the file has been successfully created, false otherwise.

Throws:

java.io.IOException - If there is an error during the file creation.

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.

getUWSNamespace

@Deprecated
public static final java.lang.String getUWSNamespace()

Deprecated. Replaced by a non-static function in XMLSerializer: XMLSerializer.getUWSNamespace(). It is totally discouraged to use this function.

Gets all UWS namespaces declarations needed for an XML representation of a UWS object.

Returns:

The UWS namespaces:
(i.e. = "xmlns:uws=[...] xmlns:xlink=[...] xmlns:xs=[...] xmlns:xsi=[...]").

See Also:

XMLSerializer.getUWSNamespace()

publishErrorSummary

@Deprecated
public static final boolean publishErrorSummary(AbstractJob j,
                                                           java.lang.Exception ex,
                                                           ErrorType type,
                                                           java.net.URL errorFileUrl,
                                                           java.lang.String errorsDirectory,
                                                           java.lang.String errorFileName)
                                         throws java.io.IOException,
                                                UWSException

Deprecated. Replaced by publishErrorSummary(AbstractJob, Exception, ErrorType, String, String, String)

Sets an error summary corresponding to the given Exception with the given error type.

1. The message of the generated error summary is set to the message of the given exception.
2. The phase is set to ERROR.
3. The stack trace of the given exception is written in the file whose the name and the parent directory are given in parameters.

Note: Even if the error file can not be written, the error summary is set to job... but it would have no URL for the details message !

Parameters:

j - The job to update.

ex - The exception which must be used to generate the error summary.

type - The type of the error.

errorFileUrl - The URL at which the content of the error file can be displayed.

errorsDirectory - The parent directory of the generated error file.

errorFileName - The name of the file which must contains the stack trace of the given exception.

Returns:

true if the job has been successfully updated, false otherwise.

Throws:

java.io.IOException - If there is an error during the error file writing.

UWSException - If there is an error when changing the phase or setting the error summary.

See Also:

AbstractJob.error(ErrorSummary), writeErrorFile(Exception, String, String)