uws.service.file

Interface UWSFileManager

All Known Implementing Classes:

LocalUWSFileManager

public interface UWSFileManager

Lets accessing any file managed by a UWS service.

It is particularly useful if you want to organize yourself the results, log or backup file generated and read by a UWS.

Version:

4.4 (08/2018)

Author:

Grégory Mantelet (CDS;ARI)

See Also:

LocalUWSFileManager

Field Summary

Fields

Modifier and Type	Field and Description
static java.io.File	TMP_UPLOAD_DIR Deprecated. Since 4.4, use getTmpDirectory() and setTmpDirectory(File) instead.

Method Summary

Modifier and Type	Method and Description
boolean	deleteError(ErrorSummary error, UWSJob job) Deletes the error file corresponding to the given job error summary.
boolean	deleteResult(Result result, UWSJob job) Deletes the result file corresponding to the given job result's description.
void	deleteUpload(UploadFile upload) Delete definitely the specified file, submitted inline in an HTTP request.
java.util.Iterator<java.io.InputStream>	getAllUserBackupInputs() Gets an input stream on the backup file of ALL the job owners (~ UWS user).
java.io.InputStream	getBackupInput() Gets an input stream on the backup file of the whole UWS.
java.io.InputStream	getBackupInput(JobOwner owner) Gets an input stream on the backup file of ONLY the given job owner (~ UWS user).
java.io.OutputStream	getBackupOutput() Gets an output stream on the backup file of the whole UWS.
java.io.OutputStream	getBackupOutput(JobOwner owner) Gets an output stream on the backup file of ONLY the given job owner (~ UWS user).
java.io.InputStream	getErrorInput(ErrorSummary error, UWSJob job) Gets an input stream on the error file corresponding to the given error and job.
java.io.OutputStream	getErrorOutput(ErrorSummary error, UWSJob job) Gets an output stream on the error file corresponding to the given error and job.
long	getErrorSize(ErrorSummary error, UWSJob job) Gets the size of the specified error summary file.
java.io.InputStream	getLogInput(UWSLog.LogLevel level, java.lang.String context) Gets an input stream on the log file of this UWS.
java.io.PrintWriter	getLogOutput(UWSLog.LogLevel level, java.lang.String context) Gets an output stream on the log file of this UWS.
java.io.InputStream	getResultInput(Result result, UWSJob job) Gets an input stream on the result file corresponding to the given job result.
java.io.OutputStream	getResultOutput(Result result, UWSJob job) Gets an output stream on the result file corresponding to the given job result.
long	getResultSize(Result result, UWSJob job) Gets the size of the specified result file.
java.io.File	getTmpDirectory() Get the temporary directory to use in this service.
java.io.InputStream	getUploadInput(UploadFile upload) Open a stream toward the specified file, submitted inline in an HTTP request.
java.lang.String	moveUpload(UploadFile upload, UWSJob destination) Move the specified file from its current location to a location related to the given job.
java.io.InputStream	openURI(java.net.URI uri) Open a stream toward the given URI.
boolean	setTmpDirectory(java.io.File newTmpDir) Set the temporary directory to use in this service.

Field Detail

TMP_UPLOAD_DIR

@Deprecated
static final java.io.File TMP_UPLOAD_DIR

Deprecated. Since 4.4, use getTmpDirectory() and setTmpDirectory(File) instead.

Temporary directory in which uploaded files will be stored when parsing the HTTP request.

Important 1: Uploaded files should be then moved using UploadFile.move(UWSJob) when the job creation or update is validated.

Important 2: As qualified above, this directory is temporary. It means that it should be emptied sometimes. It is particularly important because when a delete or move operation fails on uploaded files, no log or error might be published.

Note: The default value is the temporary directory of the system (e.g. \tmp or \var\tmp on Unix/Linux/MacOS, c:\temp on Windows).

Since:

4.1

Method Detail

getLogInput

java.io.InputStream getLogInput(UWSLog.LogLevel level,
                                java.lang.String context)
                         throws java.io.IOException

Gets an input stream on the log file of this UWS.

Parameters:

level - Level of the message to log (DEBUG, INFO, WARNING, ERROR or FATAL).

context - Context of the message to log (UWS, HTTP, JOB, THREAD, ...).

Returns:

An input on the log file or null if there is no log file.

Throws:

java.io.IOException - If there is an error while opening an input stream on the log file.

getLogOutput

java.io.PrintWriter getLogOutput(UWSLog.LogLevel level,
                                 java.lang.String context)
                          throws java.io.IOException

Gets an output stream on the log file of this UWS.

Note: The log file must be automatically created if needed.

Parameters:

level - Level of the message to log (DEBUG, INFO, WARNING, ERROR or FATAL).

context - Context of the message to log (UWS, HTTP, JOB, THREAD, ...).

Returns:

An output on the log file.

Throws:

java.io.IOException - If there is an error while creating the log file or while opening an output stream on it.

getTmpDirectory

java.io.File getTmpDirectory()

Get the temporary directory to use in this service.

Note: This directory is generally used when files are uploaded in a received HTTP request.

Important: As qualified above, this directory is temporary. It means that it should be sometimes emptied. It is particularly important because when a delete or move operation fails on a files, no log or error might be published and the files would take some space for no more reason.

Returns:

The temporary directory to use. Never null.

Since:

4.4

setTmpDirectory

boolean setTmpDirectory(java.io.File newTmpDir)

Set the temporary directory to use in this service.

Note: This directory is generally used when files are uploaded in a received HTTP request.

Important: As qualified above, this directory is temporary. It means that it should be sometimes emptied. It is particularly important because when a delete or move operation fails on a files, no log or error might be published and the files would take some space for no more reason.

Parameters:

newTmpDir - The new temporary directory to use.

Returns:

true if the path of the temporary directory has been successfully updated, false otherwise (e.g. null, not a directory, not writable, not readable).

Since:

4.4

getUploadInput

java.io.InputStream getUploadInput(UploadFile upload)
                            throws java.io.IOException

Open a stream toward the specified file, submitted inline in an HTTP request.

Parameters:

upload - Description of the uploaded file.

Returns:

Input to the specified uploaded file.

Throws:

java.io.IOException - If any error occurs while opening the stream.

Since:

4.1

openURI

java.io.InputStream openURI(java.net.URI uri)
                     throws UnsupportedURIProtocolException,
                            java.io.IOException

Open a stream toward the given URI.

Most of the time, the given URI uses the protocol http, https or ftp, which makes the URI perfectly understandable by URL which is then able to open easily a stream (cf URL.openStream()). However, a different scheme/protocol could be used ; particularly VO ones like "ivo" and "vos". It is for these particular cases that this function has been designed: in order to provide an implementation supporting additional protocols.

Parameters:

uri - URI of any resource to read.

Returns:

Input to the specified resource.

Throws:

UnsupporteURIProtocol - If the protocol is not supported by this implementation.

java.io.IOException - If another error occurs while opening the stream.

UnsupportedURIProtocolException

Since:

4.1

deleteUpload

void deleteUpload(UploadFile upload)
           throws java.io.IOException

Delete definitely the specified file, submitted inline in an HTTP request.

Parameters:

upload - Description of the uploaded file.

Throws:

java.io.IOException - If any error occurs while deleting the file.

Since:

4.1

moveUpload

java.lang.String moveUpload(UploadFile upload,
                            UWSJob destination)
                     throws java.io.IOException

Move the specified file from its current location to a location related to the given job.

Note: This function is generally used only once: after the HTTP request parsing, when creating or updating a job and only if the action has been accepted.

Important: This function might not be able to update the location inside the given UploadFile. For this reason, it is strongly recommended to not call directly this function, but to use UploadFile.move(UWSJob).

Parameters:

upload - Description of the uploaded file to move.

destination - Job in which the uploaded file will be used.

Returns:

The new location of the uploaded file.

Throws:

java.io.IOException - If any error occurs while moving the file.

Since:

4.1

getResultInput

java.io.InputStream getResultInput(Result result,
                                   UWSJob job)
                            throws java.io.IOException

Gets an input stream on the result file corresponding to the given job result.

Parameters:

result - The description of the result file to read.

job - The job of the given result.

Returns:

An input of the corresponding result file or null if there is no result file.

Throws:

java.io.IOException - If there is an error while opening an input stream on the result file.

getResultOutput

java.io.OutputStream getResultOutput(Result result,
                                     UWSJob job)
                              throws java.io.IOException

Gets an output stream on the result file corresponding to the given job result.

Note: The result file must be automatically created if needed.

Parameters:

result - The description of the result file to write.

job - The job of the given result.

Returns:

An output of the corresponding result file.

Throws:

java.io.IOException - If there is an error while creating the result file or while opening an output stream on it.

getResultSize

long getResultSize(Result result,
                   UWSJob job)
            throws java.io.IOException

Gets the size of the specified result file.

Parameters:

result - Description of the result file whose the size is wanted.

job - The job of the given result.

Returns:

The size (in bytes) of the specified result file or -1 if unknown or the file does not exist.

Throws:

java.io.IOException - If there is an error while getting the result file size.

deleteResult

boolean deleteResult(Result result,
                     UWSJob job)
              throws java.io.IOException

Deletes the result file corresponding to the given job result's description.

Parameters:

result - The description of the result file to delete.

job - The job of the given result.

Returns:

true if the result file has been deleted or if the result file does not exists, false otherwise.

Throws:

java.io.IOException - If there is a grave and unexpected error while deleting the result file.

getErrorInput

java.io.InputStream getErrorInput(ErrorSummary error,
                                  UWSJob job)
                           throws java.io.IOException

Gets an input stream on the error file corresponding to the given error and job.

Parameters:

error - The description of the error file to read.

job - The job of the given error.

Returns:

An input of the corresponding error file or null if there is no error file.

Throws:

java.io.IOException - If there is an error while opening an input stream on the error file.

getErrorOutput

java.io.OutputStream getErrorOutput(ErrorSummary error,
                                    UWSJob job)
                             throws java.io.IOException

Gets an output stream on the error file corresponding to the given error and job.

Note: The error file must be automatically created if needed.

Parameters:

error - The description of the error file to write.

job - The job of the given error.

Returns:

An output of the corresponding error file.

Throws:

java.io.IOException - If there is an error while creating the error file or while opening an output stream on it.

getErrorSize

long getErrorSize(ErrorSummary error,
                  UWSJob job)
           throws java.io.IOException

Gets the size of the specified error summary file.

Parameters:

error - Description of the error file whose the size is wanted.

job - The job of the given error.

Returns:

The size (in bytes) of the specified error file or -1 if unknown or the file does not exist.

Throws:

java.io.IOException - If there is an error while getting the error file size.

deleteError

boolean deleteError(ErrorSummary error,
                    UWSJob job)
             throws java.io.IOException

Deletes the error file corresponding to the given job error summary.

Parameters:

error - The description of the error file to delete.

job - The job of the given error.

Returns:

true if the error file has been deleted or if the error file does not exists, false otherwise.

Throws:

java.io.IOException - If there is a grave and unexpected error while deleting the error file.

getBackupInput

java.io.InputStream getBackupInput(JobOwner owner)
                            throws java.lang.IllegalArgumentException,
                                   java.io.IOException

Gets an input stream on the backup file of ONLY the given job owner (~ UWS user).

Parameters:

owner - Owner whose the jobs must be fetched from the file on which the input stream is asked.

Returns:

An input on the backup file of the given owner or null if there is no backup file.

Throws:

java.lang.IllegalArgumentException - If the given owner is null.

java.io.IOException - If there is an error while opening an input stream on the backup file.

getAllUserBackupInputs

java.util.Iterator<java.io.InputStream> getAllUserBackupInputs()

Gets an input stream on the backup file of ALL the job owners (~ UWS user).

Returns:

An iterator on all job owner's backup file.

getBackupOutput

java.io.OutputStream getBackupOutput(JobOwner owner)
                              throws java.lang.IllegalArgumentException,
                                     java.io.IOException

Gets an output stream on the backup file of ONLY the given job owner (~ UWS user).

Note: The backup file must be automatically created if needed.

Parameters:

owner - Owner whose the jobs must be saved in the file on which the output stream is asked.

Returns:

An output on the backup file of the given owner.

Throws:

java.lang.IllegalArgumentException - If the given owner is null.

java.io.IOException - If there is an error while creating the backup file or while opening an output stream on it.

getBackupInput

java.io.InputStream getBackupInput()
                            throws java.io.IOException

Gets an input stream on the backup file of the whole UWS.

Returns:

An input on the backup file of the whole UWS or null if there is no backup file.

Throws:

java.io.IOException - If there is an error while opening an input stream of the backup file.

getBackupOutput

java.io.OutputStream getBackupOutput()
                              throws java.io.IOException

Gets an output stream on the backup file of the whole UWS.

Note: The backup file must be automatically created if needed.

Returns:

An output on the backup file of the whole UWS.

Throws:

java.io.IOException - If there is an error while creating the backup file or while opening an output stream on it.