UWS

All Superinterfaces:

java.lang.Iterable<JobList>

All Known Implementing Classes:

UWSService, UWSServlet
```
public interface UWS
extends java.lang.Iterable<JobList>
```
Minimal API of a UWS service. Basically, an instance of this interface is supposed to manage one or several jobs lists.

note: All the functions of this interface are required by JobList, UWSJob and all the other classes available in this library.

Two default implementations of this interface are provided in this library:
- UWSService: this class represents an object which is able to receive, to interpret and to answer to any HTTP request as a UWS service must do (see UWSService.executeRequest(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse). Thus, an instance of this class must be used inside a servlet: all HTTP requests dedicated to UWS will be then forwarded to it.
- UWSServlet: this class represents directly a servlet. All standard UWS actions are managed as new HTTP methods. Indeed, for each HTTP method, a servlet has one function (i.e. doGet(...), doPost(...)). So, for each UWS action, a UWSServlet has one function: doAddJob(...), doDestroyJob(...), doGetJob(...), ...
These two classes already implement all standard actions and behaviors of UWS 1.0. Nothing really change between them except the way they lets creating and managing a UWS. The second implementation is the most simple to use because it gathers the UWS and the servlet.

IMPORTANT: All implementations of this interface should implement properly the function destroy() and should call it when the JVM or the HTTP server application is closing.
Version:

4.3 (09/2017)

Author:

Grégory Mantelet (CDS;ARI)

Field Summary

Fields
Modifier and Type	Field and Description
`static java.lang.String`	`REQ_ATTRIBUTE_ID` Attribute of the HttpServletRequest to set and to get in order to access the request ID set by the UWS library.
`static java.lang.String`	`REQ_ATTRIBUTE_JOB_DESCRIPTION` Attribute of the HttpServletRequest to set and to get in order to access the Job-Description (generally in XML) sent instead of the "normal" HTTP-POST/-PUT parameters in the HTTP request body.
`static java.lang.String`	`REQ_ATTRIBUTE_PARAMETERS` Attribute of the HttpServletRequest to set and to get in order to access the parameters extracted by the UWS library (using a RequestParser).
`static java.lang.String`	`REQ_ATTRIBUTE_USER` Attribute of the HttpServletRequest to set and to get in order to access the user at the origin of the HTTP request.
`static java.lang.String`	`STANDARD_ID` IVOA standardID of a UWS service currently generated by this library.
`static java.lang.String`	`VERSION` Version of the UWS protocol used in this library.

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`boolean`	`addJobList(JobList newJL)` Adds a jobs list to this UWS.
`void`	`destroy()` End properly this UWS: jobs should be backuped (if this feature is enable), timers and threads should be stopped, open files and database connections should be closed, etc...
`boolean`	`destroyJobList(java.lang.String name)` Destroys the specified jobs list.
`UWSBackupManager`	`getBackupManager()` Gets its backup manager.
`java.lang.String`	`getDescription()` Gets the description of this UWS.
`UWSFactory`	`getFactory()` Gets its job factory.
`UWSFileManager`	`getFileManager()` Gets its file manager.
`JobList`	`getJobList(java.lang.String name)` Gets the jobs list whose the name matches exactly the given one.
`UWSLog`	`getLogger()` Gets the logger of this UWS.
`java.lang.String`	`getName()` Gets the name of this UWS.
`int`	`getNbJobList()` Gets the number of managed jobs lists.
`RequestParser`	`getRequestParser()` Get its HTTP request parser.
`UWSSerializer`	`getSerializer(java.lang.String mimeTypes)` Gets the serializer whose the MIME type is the same as the given one.
`UWSUrl`	`getUrlInterpreter()` Gets the object which is able to interpret and to build any UWS URL.
`UserIdentifier`	`getUserIdentifier()` Gets the object which is able to identify a user from an HTTP request.

Methods inherited from interface java.lang.Iterable
forEach, iterator, spliterator

- Field Detail
  - VERSION
```
static final java.lang.String VERSION
```
    Version of the UWS protocol used in this library.
    
    Since:
    
    4.2
    
    See Also:
    
    Constant Field Values
  - STANDARD_ID
```
static final java.lang.String STANDARD_ID
```
    IVOA standardID of a UWS service currently generated by this library.
    
    Since:
    
    4.2
    
    See Also:
    
    Constant Field Values
  - REQ_ATTRIBUTE_ID
```
static final java.lang.String REQ_ATTRIBUTE_ID
```
    Attribute of the HttpServletRequest to set and to get in order to access the request ID set by the UWS library.
    
    Since:
    
    4.1
    
    See Also:
    
    Constant Field Values
  - REQ_ATTRIBUTE_PARAMETERS
```
static final java.lang.String REQ_ATTRIBUTE_PARAMETERS
```
    Attribute of the HttpServletRequest to set and to get in order to access the parameters extracted by the UWS library (using a RequestParser).
    
    Since:
    
    4.1
    
    See Also:
    
    Constant Field Values
  - REQ_ATTRIBUTE_USER
```
static final java.lang.String REQ_ATTRIBUTE_USER
```
    Attribute of the HttpServletRequest to set and to get in order to access the user at the origin of the HTTP request.
    
    Since:
    
    4.1
    
    See Also:
    
    Constant Field Values
  - REQ_ATTRIBUTE_JOB_DESCRIPTION
```
static final java.lang.String REQ_ATTRIBUTE_JOB_DESCRIPTION
```
    Attribute of the HttpServletRequest to set and to get in order to access the Job-Description (generally in XML) sent instead of the "normal" HTTP-POST/-PUT parameters in the HTTP request body.
    
    Since:
    
    4.2
    
    See Also:
    
    Constant Field Values
- Method Detail
  - getName
```
java.lang.String getName()
```
    Gets the name of this UWS.
    
    Returns:
    
    Its name (MAY BE NULL).
  - getDescription
```
java.lang.String getDescription()
```
    Gets the description of this UWS.
    
    Returns:
    
    Its description (MAY BE NULL).
  - destroy
```
void destroy()
```
    End properly this UWS: jobs should be backuped (if this feature is enable), timers and threads should be stopped, open files and database connections should be closed, etc... In brief, this function should release all used resources.
    
    IMPORTANT: This function should be called only when the JVM or the Web Application Server is stopping.
    
    Note: A call to this function may prevent this instance of UWS to execute any subsequent HTTP request, or the behavior would be unpredictable.
    
    Since:
    
    4.1
  - addJobList
```
boolean addJobList(JobList newJL)
```
    Adds a jobs list to this UWS.
    
    Parameters:
    
    newJL - The jobs list to add.
    
    Returns:
    
    true if the jobs list has been successfully added, false if the given jobs list is null or if a jobs list with this name already exists or if a UWS is already associated with another UWS.
  - getJobList
```
JobList getJobList(java.lang.String name)
            throws UWSException
```
    Gets the jobs list whose the name matches exactly the given one.
    
    Parameters:
    
    name - Name of the jobs list to get.
    
    Returns:
    
    The corresponding jobs list.
    
    Throws:
    
    UWSException - If the given name is null or empty, or if no jobs list matches.
  - getNbJobList
```
int getNbJobList()
```
    Gets the number of managed jobs lists.
    
    Returns:
    
    The number of jobs lists.
  - destroyJobList
```
boolean destroyJobList(java.lang.String name)
                throws UWSException
```
    Destroys the specified jobs list.
    
    note: After the call of this function, the UWS reference of the given jobs list should be removed (see JobList.setUWS(UWS)).
    
    Parameters:
    
    name - Name of the jobs list to destroy.
    
    Returns:
    
    true if the given jobs list has been destroyed, false otherwise.
    
    Throws:
    
    UWSException
  - getSerializer
```
UWSSerializer getSerializer(java.lang.String mimeTypes)
                     throws UWSException
```
    Gets the serializer whose the MIME type is the same as the given one.
    
    Note: If this UWS has no corresponding serializer, a default one should be returned !
    
    Parameters:
    
    mimeTypes - The MIME type of the searched serializer (may be more than one MIME types - comma separated ; see the format of the Accept header of a HTTP-Request).
    
    Returns:
    
    The corresponding serializer or the default serializer of this UWS if no corresponding serializer has been found.
    
    Throws:
    
    UWSException - If there is no corresponding serializer AND if the default serializer of this UWS can not be found.
    
    See Also:
    
    AcceptHeader.AcceptHeader(String), AcceptHeader.getOrderedMimeTypes()
  - getUrlInterpreter
```
UWSUrl getUrlInterpreter()
```
    Gets the object which is able to interpret and to build any UWS URL. It MUST be loaded with the root URL of this UWS: see UWSUrl.load(javax.servlet.http.HttpServletRequest) and UWSUrl.load(java.net.URL).
    
    note: This getter is particularly used to serialize the jobs lists and their jobs.
    
    Returns:
    
    Its UWS URL interpreter (SHOULD BE NOT NULL).
  - getLogger
```
UWSLog getLogger()
```
    Gets the logger of this UWS.
    
    note:A UWS logger is used to watch the HTTP requests received by the UWS and their responses. The activity of the UWS is also logged and particularly the life of the different jobs and their threads. A default implementation is available: DefaultUWSLog.
    
    Returns:
    
    Its logger (MUST BE NOT NULL).
  - getUserIdentifier
```
UserIdentifier getUserIdentifier()
```
    Gets the object which is able to identify a user from an HTTP request.
    
    Returns:
    
    Its user identifier.
  - getFactory
```
UWSFactory getFactory()
```
    Gets its job factory.
    
    note: This objects is the only one to know how to extract job parameters from an HTTP request, how to create a job and how to create its respective thread. A partial implementation which answers to the 2 first questions is available: AbstractUWSFactory
    
    Returns:
    
    Its job factory.
  - getRequestParser
```
RequestParser getRequestParser()
```
    Get its HTTP request parser.
    
    note: This parser is the only one to be able to extract UWS and TAP parameters from any HTTP request. Its behavior is adapted in function of the used HTTP method and of the content-type. A default implementation is provided by the UWS library: UWSRequestParser.
    
    Returns:
    
    Its request parser.
    
    Since:
    
    4.1
  - getFileManager
```
UWSFileManager getFileManager()
```
    Gets its file manager.
    
    note: A file manager tells to a UWS how to create, read and write the different managed files (i.e. log, result, errors, backup). A default implementation is available: LocalUWSFileManager.
    
    Returns:
    
    Its file manager.
  - getBackupManager
```
UWSBackupManager getBackupManager()
```
    Gets its backup manager.
    
    note: This object should be used at the initialization of the UWS to restore a previous "session" (see UWSBackupManager.restoreAll()) and must be used each time the list of jobs of a user (see UWSBackupManager.saveOwner(uws.job.user.JobOwner)) or all the jobs of this UWS must be saved (see UWSBackupManager.saveAll()).
    
    Returns:
    
    Its backup manager.

Interface UWS

Field Summary

Method Summary

Methods inherited from interface java.lang.Iterable

Field Detail

VERSION

STANDARD_ID

REQ_ATTRIBUTE_ID

REQ_ATTRIBUTE_PARAMETERS

REQ_ATTRIBUTE_USER

REQ_ATTRIBUTE_JOB_DESCRIPTION

Method Detail

getName

getDescription

destroy

addJobList

getJobList

getNbJobList

destroyJobList

getSerializer

getUrlInterpreter

getLogger

getUserIdentifier

getFactory

getRequestParser

getFileManager

getBackupManager