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.
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.
|
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.
|
static final java.lang.String VERSION
static final java.lang.String STANDARD_ID
static final java.lang.String REQ_ATTRIBUTE_ID
static final java.lang.String REQ_ATTRIBUTE_PARAMETERS
static final java.lang.String REQ_ATTRIBUTE_USER
static final java.lang.String REQ_ATTRIBUTE_JOB_DESCRIPTION
java.lang.String getName()
java.lang.String getDescription()
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.
boolean addJobList(JobList newJL)
newJL
- The jobs list to add.JobList getJobList(java.lang.String name) throws UWSException
name
- Name of the jobs list to get.UWSException
- If the given name is null or empty, or if no jobs list matches.int getNbJobList()
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)
).
name
- Name of the jobs list to destroy.UWSException
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 !
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).UWSException
- If there is no corresponding serializer AND if the default serializer of this UWS can not be found.AcceptHeader.AcceptHeader(String)
,
AcceptHeader.getOrderedMimeTypes()
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.
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
.
UserIdentifier getUserIdentifier()
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
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
.
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
.
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()
).