uws.service
Class AbstractUWS<JL extends JobList<J>,J extends AbstractJob>

java.lang.Object
  uws.job.SerializableUWSObject
      uws.service.AbstractUWS<JL,J>

All Implemented Interfaces:

java.io.Serializable, java.lang.Iterable<JL>, java.util.EventListener, javax.servlet.http.HttpSessionBindingListener

Direct Known Subclasses:

BasicUWS, ExtendedUWS

public abstract class AbstractUWS<JL extends JobList<J>,J extends AbstractJob>
extends SerializableUWSObject
implements java.lang.Iterable<JL>, javax.servlet.http.HttpSessionBindingListener

General description

An abstract facility to implement the Universal Worker Service pattern.

It can manage several jobs lists (create new, get and remove).

It also interprets HttpServletRequest, applies the action specified in its given URL and parameters (according to the IVOA Proposed Recommendation of 2010-02-10) and returns the corresponding response in a HttpServletResponse.

The UWS URL interpreter

Any subclass of AbstractUWS has one object called the UWS URL interpreter. It is stored in the field urlInterpreter. It lets interpreting the URL of any received request. Thus you can know on which jobs list, job and/or job attribute(s) the request applies.

This interpreter must be initialized with the base URL/URI of this UWS. By using the default constructor (the one with no parameter), the URL interpreter will be built at the first request (see UWSUrl.UWSUrl(HttpServletRequest)) and so the base URI is extracted directly from the request).

You want to set another base URI or to use a custom URL interpreter, you have to set yourself the interpreter by using the method setUrlInterpreter(UWSUrl).

Create a job

The most important abstract function of this class is createJob(Map). It allows to create an instance of the type of job which is managed by this UWS. The only parameter is a map of a job attributes. It is the same map that take the functions AbstractJob.AbstractJob(Map) and AbstractJob.addOrUpdateParameters(Map).

There are two convenient implementations of this abstract method in BasicUWS and ExtendedUWS. These two implementations are based on the Java Reflection.

UWS actions

All the actions described in the IVOA recommendation are already managed. Each of these actions are defined in an instance of UWSAction:

• LIST_JOBS: see the class ListJobs
• ADD_JOB: see the class AddJob
• DESTROY_JOB: see the class DestroyJob
• JOB_SUMMARY: see the class JobSummary
• GET_JOB_PARAM: see the class GetJobParam
• SET_JOB_PARAM: see the class SetJobParam
• HOME_PAGE: see the class ShowHomePage

However you can add your own UWS actions ! To do that you just need to implement the abstract class UWSAction and to call the method addUWSAction(UWSAction) with an instance of this implementation.

IMPORTANT: You must be careful when you override the function UWSAction.match(UWSUrl, String, HttpServletRequest) so that your test is as precise as possible ! Indeed the order in which the actions of a UWS are evaluated is very important !
If you want to be sure your custom UWS action is always evaluated before any other UWS action you can use the function addUWSAction(int, UWSAction) with 0 as first parameter !

Note: You can also replace an existing UWS action thanks to the method replaceUWSAction(UWSAction) or setUWSAction(int, UWSAction) !

User identification

Some UWS actions need to know the current user so that they can adapt their response (i.e. LIST_JOBS must return the jobs of only one user: the current one). Thus, before executing a UWS action (and even before choosing the good action in function of the request) the function UserIdentifier.extractUserId(UWSUrl, HttpServletRequest) is called. Its goal is to identify the current user in function of the received request.

Notes:

• If this function returns NULL, the UWS actions must be executed on all jobs, whatever is their owner !
• UserIdentifier is an interface. So you must implement it and then set its extension to this UWS by using setUserIdentifier(UserIdentifier).

Queue management

One of the goals of a UWS is to manage an execution queue for all managed jobs. This task is given to an instance of DefaultExecutionManager, stored in the field executionManager. Each time a job is created, the UWS sets it the execution manager (see AddJob). Thus the AbstractJob.start() method will ask to the manager whether it can execute now or whether it must be put in a QUEUED phase until enough resources are available for its execution.

By extending the class DefaultExecutionManager and by overriding DefaultExecutionManager.isReadyForExecution(AbstractJob) you can change the condition which puts a job in the EXECUTING or in the QUEUED phase. By default, a job is put in the QUEUED phase if there are more running jobs than a given number.

With this manager it is also possible to list all running jobs in addition of all queued jobs, thanks to the methods: DefaultExecutionManager.getRunningJobs(), DefaultExecutionManager.getQueuedJobs(), DefaultExecutionManager.getNbRunningJobs() and DefaultExecutionManager.getNbQueuedJobs().

Serializers & MIME types

According to the IVOA recommendation, the XML format is the default format in which each UWS resource must be returned. However it is told that other formats can also be managed. To allow that, AbstractUWS manages a list of UWSSerializer and lets define which is the default one to use. By default, there are two serializers: XMLSerializer (the default choice) and JSONSerializer.

One proposed way to choose automatically the format to use is to look at the Accept header of a HTTP-Request. This header field is a list of MIME types (each one with a quality - a sort of priority). Thus each UWSSerializer is associated with a MIME type so that AbstractUWS can choose automatically the preferred format and so, the serializer to use.

WARNING: Only one UWSSerializer can be associated with a given MIME type in an AbstractUWS instance ! Thus, if you add a UWSSerializer to a UWS, and this UWS has already a serializer for the same MIME type, it will be replaced by the added one.

Note: A XML document can be linked to a XSLT style-sheet. By using the method XMLSerializer.setXSLTPath(String) you can define the path/URL of the XLST to link to each UWS resource.
Since the XMLSerializer is the default format for a UWS resource you can also use the function setXsltURL(String) !

The UWS Home page

As for a job or a jobs list, a UWS is also a UWS resource. That's why it can also be serialized !

However in some cases it could more interesting to substitute this resource by a home page of the whole UWS by using the function: setHomePage(String) or setHomePage(URL, boolean).

Note: To go back to the UWS serialization (that is to say to abort a call to setHomePage(String)), use the method setDefaultHomePage() !

Version:

02/2011

Author:

Grégory Mantelet (CDS)

See Also:

AbstractJob, BasicUWS, ExtendedUWS, Serialized Form

Field Summary

protected UWSSerializer	choosenSerializer The serializer choosen during the last call of executeRequest(HttpServletRequest, HttpServletResponse).
protected java.lang.String	defaultSerializer The MIME type of the default serialization format.
protected java.lang.String	description Description of this UWS.
protected UWSAction<JL,J>	executedAction The action executed during the last call of executeRequest(HttpServletRequest, HttpServletResponse).
protected java.lang.String	homePage URL of the home page.
protected boolean	homeRedirection Indicates whether the home page must be a copy or a redirection to the given URL.
protected java.util.Map<java.lang.String,JL>	mapJobLists List of all managed jobs lists.
protected java.lang.String	name Name of this UWS.
protected boolean	reInitUrlInterpreter Indicates whether the UWS URL interpreter must be re-initialize after each de-serialization.
protected java.util.Map<java.lang.String,UWSSerializer>	serializers List of available serializers.
protected UWSUrl	urlInterpreter The "interpreter" of UWS URLs.
protected UserIdentifier	userIdentifier The object to use to extract the user ID from the received request.
protected java.util.Vector<UWSAction<JL,J>>	uwsActions List of UWS actions (i.e. to list jobs, to get a job, to set a job parameter, etc...).

Constructor Summary

	AbstractUWS() Builds a UWS (the base URI will be extracted at the first request directly from the request itself).
protected	AbstractUWS(java.lang.String baseURI) Builds a UWS with its base UWS URI.
protected	AbstractUWS(UWSUrl urlInterpreter) Builds a UWS with the given UWS URL interpreter.

Method Summary

boolean	addJobList(JL jl) Adds a jobs list to this UWS.
boolean	addSerializer(UWSSerializer serializer) Adds a serializer to this UWS WARNING: If there is already a serializer with the same MIME type in this UWS , it will be replaced by the given one !
boolean	addUWSAction(int indAction, UWSAction<JL,J> action) Lets inserting the given action at the given position in the actions list of this UWS.
boolean	addUWSAction(UWSAction<JL,J> action) Lets adding the given action to this UWS.
abstract J	createJob(java.util.Map<java.lang.String,java.lang.String> parameters) Creates a job of the type (extension of AbstractJob) which parameterized this implementation of AbstractUWS.
void	destroyAllJobLists() Destroys all managed jobs lists.
boolean	destroyJobList(JL jl) Destroys the given jobs list.
boolean	destroyJobList(java.lang.String name) Destroys the specified jobs list.
boolean	executeRequest(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response) Executes the given request according to the IVOA Proposed Recommendation of 2010-02-10.
java.lang.String	getBaseURI() Gets the base UWS URL.
UWSSerializer	getChoosenSerializer() Gets the serializer choosen during the last call of getSerializer(String).
java.lang.String	getDefaultSerializer() Gets the MIME type of the serializer to use by default.
java.lang.String	getDescription() Gets the description of this UWS.
DestructionManager	getDestructionManager() Gets the destruction manager.
DestructionTimeController	getDestructionTimeController() Gets the object which lets the UWS controlling the destruction time of all managed jobs.
UWSAction<JL,J>	getExecutedAction() Gets the UWS action executed during the last call of executeRequest(HttpServletRequest, HttpServletResponse).
ExecutionDurationController	getExecutionDurationController() Gets the object which lets the UWS controlling the execution duration of all managed jobs.
ExecutionManager	getExecutionManager() Gets the execution manager.
java.lang.String	getHomePage() Gets the URL of the resource which must be used as home page of this UWS.
JL	getJobList(java.lang.String name) Lets retrieve a jobs list in function of its name.
java.lang.String	getName() Gets the name of this UWS.
int	getNbJobList() Gets the number of managed jobs lists.
int	getNbSerializers() Gets the total number of serializers available in this UWS.
int	getNbUWSActions() Gets the number of actions this UWS has.
UWSSerializer	getSerializer(java.lang.String mimeTypes) Gets the serializer whose the MIME type is the same as the given one.
java.util.Iterator<UWSSerializer>	getSerializers() Gets an iterator of the list of all serializers available in this UWS.
UWSUrl	getUrlInterpreter() Gets the UWS URL interpreter of this UWS.
UserIdentifier	getUserIdentifier() Gets the object which lets extracting the user ID from a received request.
UWSAction<JL,J>	getUWSAction(java.lang.String actionName) Gets the action of this UWS which has the same name as the given one.
java.util.Iterator<UWSAction<JL,J>>	getUWSActions() Gets all actions of this UWS.
java.lang.String	getXsltURL() Gets the URL of the XSLT style-sheet that the XML serializer of this UWS is using.
boolean	hasSerializerFor(java.lang.String mimeType) Tells whether this UWS has already a serializer with the given MIME type.
boolean	isDefaultHomePage() Indicates whether the current home page is the default one (the UWS serialization) or if it has been specified manually using setHomePage(URL, boolean).
boolean	isHomePageRedirection() Tells whether a redirection to the specified home page must be done or not.
java.util.Iterator<JL>	iterator() An iterator on the jobs lists list.
void	redirect(java.lang.String url, javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response) Sends a redirection (with the HTTP status code 303) to the given URL/URI into the given response.
void	removeAllJobLists() Removes all managed jobs lists.
boolean	removeJobList(JL jl) Removes the given jobs list from this UWS.
JL	removeJobList(java.lang.String name) Removes the specified jobs list.
UWSSerializer	removeSerializer(java.lang.String mimeType) Removes the serializer whose the MIME type is the same as the given one.
UWSAction<JL,J>	removeUWSAction(int indAction) Removes the specified action from this UWS.
UWSAction<JL,J>	removeUWSAction(java.lang.String actionName) Removes the action of this UWS which has the same name as the given one.
UWSAction<JL,J>	replaceUWSAction(UWSAction<JL,J> action) Replaces the action which has the same name that the given action.
void	sendError(java.lang.Exception error, javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response) Fills the response with the given error.
void	sendError(UWSException error, javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response) Fills the response with the given error.
java.lang.String	serialize(UWSSerializer serializer, java.lang.String ownerId) Serializes the whole object considering the given owner ID (supposed to be the ID of the current user) and thanks to the given serializer.
void	setDefaultHomePage() Forgets the home page specified by using setHomePage(URL, boolean) - if any - and go back to the default home page (XML format).
void	setDefaultSerializer(java.lang.String mimeType) Sets the MIME of the serializer to use by default.
void	setDescription(java.lang.String description) Sets the description of this UWS.
void	setDestructionManager(DestructionManager newManager) Sets its destruction manager.
void	setDestructionTimeController(DestructionTimeController controller) Sets the object which lets the UWS controlling the destruction time of all managed jobs.
void	setExecutionDurationController(ExecutionDurationController controller) Sets the object which lets the UWS controlling the execution duration of all managed jobs.
void	setExecutionManager(ExecutionManager newManager) Sets its execution manager.
void	setHomePage(java.lang.String homePageURI) Sets the URI of the resource which must be used as home page of this UWS.
void	setHomePage(java.net.URL homePageUrl, boolean redirect) Sets the URL of the resource which must be used as home page of this UWS.
void	setName(java.lang.String name) Sets the name of this UWS.
void	setUrlInterpreter(UWSUrl urlInterpreter) Sets the UWS URL interpreter to use in this UWS.
void	setUserIdentifier(UserIdentifier identifier) Sets the object which lets extracting the use ID from a received request.
boolean	setUWSAction(int indAction, UWSAction<JL,J> action) Replaces the specified action by the given action.
boolean	setXsltURL(java.lang.String xsltPath) Sets the URL of the XSLT style-sheet that the XML serializer of this UWS must use.
void	sync() This method is called just after a de-serialization of this UWS.
void	valueBound(javax.servlet.http.HttpSessionBindingEvent e) Called by an HttpSession while adding an instance of AbstractUWS in its attributes list.
void	valueUnbound(javax.servlet.http.HttpSessionBindingEvent e) Called by an HttpSession while removing an instance of AbstractUWS from its attributes list.

Methods inherited from class uws.job.SerializableUWSObject

serialize, serialize, serialize

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

name

protected java.lang.String name

Name of this UWS.

description

protected java.lang.String description

Description of this UWS.

mapJobLists

protected final java.util.Map<java.lang.String,JL extends JobList<J>> mapJobLists

List of all managed jobs lists. (it is a LinkedHashMap so that jobs lists are ordered by insertion)

urlInterpreter

protected UWSUrl urlInterpreter

The "interpreter" of UWS URLs.

reInitUrlInterpreter

protected boolean reInitUrlInterpreter

Indicates whether the UWS URL interpreter must be re-initialize after each de-serialization.

serializers

protected final java.util.Map<java.lang.String,UWSSerializer> serializers

List of available serializers.

defaultSerializer

protected java.lang.String defaultSerializer

The MIME type of the default serialization format.

choosenSerializer

protected UWSSerializer choosenSerializer

The serializer choosen during the last call of executeRequest(HttpServletRequest, HttpServletResponse).

homePage

protected java.lang.String homePage

URL of the home page. (NULL if there is no home page)

homeRedirection

protected boolean homeRedirection

Indicates whether the home page must be a copy or a redirection to the given URL.

uwsActions

protected final java.util.Vector<UWSAction<JL extends JobList<J>,J extends AbstractJob>> uwsActions

List of UWS actions (i.e. to list jobs, to get a job, to set a job parameter, etc...).

executedAction

protected UWSAction<JL extends JobList<J>,J extends AbstractJob> executedAction

The action executed during the last call of executeRequest(HttpServletRequest, HttpServletResponse).

userIdentifier

protected UserIdentifier userIdentifier

The object to use to extract the user ID from the received request.

Constructor Detail

AbstractUWS

public AbstractUWS()

Builds a UWS (the base URI will be extracted at the first request directly from the request itself).

See Also:

XMLSerializer, JSONSerializer, ListJobs, AddJob, DestroyJob, JobSummary, GetJobParam, SetJobParam, ShowHomePage

AbstractUWS

protected AbstractUWS(java.lang.String baseURI)
               throws UWSException

Builds a UWS with its base UWS URI.

Parameters:

baseURI - Base UWS URI.

Throws:

UWSException - If the given URI is null or empty.

See Also:

UWSUrl.UWSUrl(String)

AbstractUWS

protected AbstractUWS(UWSUrl urlInterpreter)

Builds a UWS with the given UWS URL interpreter.

Parameters:

urlInterpreter - The UWS URL interpreter to use in this UWS.

Method Detail

sync

public final void sync()

This method is called just after a de-serialization of this UWS. It re-initializes all the jobs lists.

See Also:

JobList.sync()

getName

public final java.lang.String getName()

Gets the name of this UWS.

Returns:

Its name.

setName

public final void setName(java.lang.String name)

Sets the name of this UWS.

Parameters:

name - Its new name.

getDescription

public final java.lang.String getDescription()

Gets the description of this UWS.

Returns:

Its description.

setDescription

public final void setDescription(java.lang.String description)

Sets the description of this UWS.

Parameters:

description - Its new description.

getBaseURI

public final java.lang.String getBaseURI()

Gets the base UWS URL.

Returns:

The base UWS URL.

See Also:

UWSUrl.getBaseURI()

getUrlInterpreter

public final UWSUrl getUrlInterpreter()

Gets the UWS URL interpreter of this UWS.

Returns:

Its UWS URL interpreter.

setUrlInterpreter

public final void setUrlInterpreter(UWSUrl urlInterpreter)

Sets the UWS URL interpreter to use in this UWS.

Parameters:

urlInterpreter - Its new UWS URL interpreter (may be null. In this case, it will be created from the next request ; see executeRequest(HttpServletRequest, HttpServletResponse)).

getExecutionDurationController

public final ExecutionDurationController getExecutionDurationController()

Gets the object which lets the UWS controlling the execution duration of all managed jobs.

Returns:

The used execution duration controller

setExecutionDurationController

public final void setExecutionDurationController(ExecutionDurationController controller)

Sets the object which lets the UWS controlling the execution duration of all managed jobs.

Note: If the given controller is NULL, nothing is done.

Parameters:

controller - Its new execution duration controller.

getDestructionTimeController

public final DestructionTimeController getDestructionTimeController()

Gets the object which lets the UWS controlling the destruction time of all managed jobs.

Returns:

The used destruction time controller.

setDestructionTimeController

public final void setDestructionTimeController(DestructionTimeController controller)

Sets the object which lets the UWS controlling the destruction time of all managed jobs.

Note: If the given controller is NULL, nothing is done.

Parameters:

controller - Its new destruction time controller.

getUserIdentifier

public final UserIdentifier getUserIdentifier()

Gets the object which lets extracting the user ID from a received request.

Returns:

The used UserIdentifier (may be null).

setUserIdentifier

public final void setUserIdentifier(UserIdentifier identifier)

Sets the object which lets extracting the use ID from a received request.

Parameters:

identifier - The UserIdentifier to use (may be null).

getDestructionManager

public final DestructionManager getDestructionManager()

Gets the destruction manager.

Returns:

Its destruction manager (may be null).

setDestructionManager

public final void setDestructionManager(DestructionManager newManager)

Sets its destruction manager.

Note: The given manager (even if NULL) is set for all managed jobs lists.

Parameters:

newManager - Its new destruction manager.

See Also:

JobList.setDestructionManager(DestructionManager)

getExecutionManager

public final ExecutionManager getExecutionManager()

Gets the execution manager.

Returns:

Its execution manager (may be null).

setExecutionManager

public final void setExecutionManager(ExecutionManager newManager)
                               throws UWSException

Sets its execution manager.

Note: The execution manager is set for all managed jobs (whatever is their jobs list).

Parameters:

newManager - Its new execution manager.

Throws:

UWSException - If the given manager is null or if there is an error while setting the new execution manager to a job.

See Also:

AbstractJob.setExecutionManager(ExecutionManager)

getHomePage

public final java.lang.String getHomePage()

Gets the URL of the resource which must be used as home page of this UWS.

Returns:

The URL of the home page.

isHomePageRedirection

public final boolean isHomePageRedirection()

Tells whether a redirection to the specified home page must be done or not.

Returns:

true if a redirection to the specified resource must be done or false to copy it.

setHomePage

public final void setHomePage(java.net.URL homePageUrl,
                              boolean redirect)

Sets the URL of the resource which must be used as home page of this UWS.

Parameters:

homePageUrl - The URL of the home page (may be null).

redirect - true if a redirection to the specified resource must be done or false to copy it.

setHomePage

public final void setHomePage(java.lang.String homePageURI)

Sets the URI of the resource which must be used as home page of this UWS.

A redirection will always be done on the specified resource.

Parameters:

homePageURI - The URL of the home page.

isDefaultHomePage

public final boolean isDefaultHomePage()

Indicates whether the current home page is the default one (the UWS serialization) or if it has been specified manually using setHomePage(URL, boolean).

Returns:

true if it is the default home page, false otherwise.

setDefaultHomePage

public final void setDefaultHomePage()

Forgets the home page specified by using setHomePage(URL, boolean) - if any - and go back to the default home page (XML format).

getDefaultSerializer

public final java.lang.String getDefaultSerializer()

Gets the MIME type of the serializer to use by default.

Returns:

The MIME type of the default serializer.

setDefaultSerializer

public final void setDefaultSerializer(java.lang.String mimeType)
                                throws UWSException

Sets the MIME of the serializer to use by default.

Parameters:

mimeType - The MIME type (only one).

Throws:

UWSException - If there is no serializer with this MIME type available in this UWS.

addSerializer

public final boolean addSerializer(UWSSerializer serializer)

Adds a serializer to this UWS

WARNING: If there is already a serializer with the same MIME type in this UWS , it will be replaced by the given one !

Parameters:

serializer - The serializer to add.

Returns:

true if the serializer has been successfully added, false otherwise.

See Also:

UWSSerializer.getMimeType()

hasSerializerFor

public final boolean hasSerializerFor(java.lang.String mimeType)

Tells whether this UWS has already a serializer with the given MIME type.

Parameters:

mimeType - A MIME type (only one).

Returns:

true if a serializer exists with the given MIME type, false otherwise.

getNbSerializers

public final int getNbSerializers()

Gets the total number of serializers available in this UWS.

Returns:

The number of its serializers.

getSerializers

public final java.util.Iterator<UWSSerializer> getSerializers()

Gets an iterator of the list of all serializers available in this UWS.

Returns:

An iterator on its serializers.

getSerializer

public final 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, its default one will 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()

getChoosenSerializer

public final UWSSerializer getChoosenSerializer()

Gets the serializer choosen during the last call of getSerializer(String).

Returns:

The last used serializer.

removeSerializer

public final UWSSerializer removeSerializer(java.lang.String mimeType)

Removes the serializer whose the MIME type is the same as the given one.

Parameters:

mimeType - MIME type of the serializer to remove.

Returns:

The removed serializer or null if no corresponding serializer has been found.

getXsltURL

public final java.lang.String getXsltURL()

Gets the URL of the XSLT style-sheet that the XML serializer of this UWS is using.

Returns:

The used XSLT URL.

setXsltURL

public final boolean setXsltURL(java.lang.String xsltPath)

Sets the URL of the XSLT style-sheet that the XML serializer of this UWS must use.

Parameters:

xsltPath - The new XSLT URL.

Returns:

true if the given path/url has been successfully set, false otherwise.

iterator

public final java.util.Iterator<JL> iterator()

An iterator on the jobs lists list.

Specified by:

iterator in interface java.lang.Iterable<JL extends JobList<J>>

See Also:

Iterable.iterator()

getJobList

public final JL getJobList(java.lang.String name)

Lets retrieve a jobs list in function of its name.

Parameters:

name - Name of the jobs list to get.

Returns:

The corresponding jobs list or null if there is no jobs list with the given name in this UWS.

getNbJobList

public final int getNbJobList()

Gets the number of managed jobs lists.

Returns:

The number of jobs lists.

addJobList

public final boolean addJobList(JL jl)

Adds a jobs list to this UWS.

Parameters:

jl - The jobs list to add.

Returns:

true if the jobs list has been successfully added or if a jobs list with this name already exists, false if the given jobs list is null.

See Also:

JobList.setUWS(AbstractUWS)

removeJobList

public final JL removeJobList(java.lang.String name)

Removes the specified jobs list.

Parameters:

name - Name of the jobs list to remove.

Returns:

The removed jobs list or null if no jobs list with the given name has been found.

See Also:

removeJobList(JobList)

removeJobList

public boolean removeJobList(JL jl)

Removes the given jobs list from this UWS.

Parameters:

jl - The jobs list to remove.

Returns:

true if the jobs list has been successfully removed, false otherwise.

See Also:

JobList.removeAll(), JobList.setUWS(AbstractUWS)

destroyJobList

public final boolean destroyJobList(java.lang.String name)

Destroys the specified jobs list.

Parameters:

name - Name of the jobs list to destroy.

Returns:

true if the given jobs list has been destroyed, false otherwise.

See Also:

destroyJobList(JobList)

destroyJobList

public boolean destroyJobList(JL jl)

Destroys the given jobs list.

Parameters:

jl - The jobs list to destroy.

Returns:

true if the given jobs list has been destroyed, false otherwise.

See Also:

JobList.clear(), JobList.setUWS(AbstractUWS)

removeAllJobLists

public final void removeAllJobLists()

Removes all managed jobs lists.

See Also:

removeJobList(String)

destroyAllJobLists

public final void destroyAllJobLists()

Destroys all managed jobs lists.

See Also:

destroyJobList(String)

addUWSAction

public final boolean addUWSAction(UWSAction<JL,J> action)

Lets adding the given action to this UWS.

WARNING: The action will be added at the end of the actions list of this UWS. That means, it will be evaluated (call of the method UWSAction.match(UWSUrl, String, HttpServletRequest)) lastly !

Parameters:

action - The UWS action to add.

Returns:

true if the given action has been successfully added, false otherwise.

addUWSAction

public final boolean addUWSAction(int indAction,
                                  UWSAction<JL,J> action)
                           throws java.lang.ArrayIndexOutOfBoundsException

Lets inserting the given action at the given position in the actions list of this UWS.

Parameters:

indAction - The index where the given action must be inserted.

action - The action to add.

Returns:

true if the given action has been successfully added, false otherwise.

Throws:

java.lang.ArrayIndexOutOfBoundsException - If the given index is incorrect (index < 0 || index >= uwsActions.size()).

setUWSAction

public final boolean setUWSAction(int indAction,
                                  UWSAction<JL,J> action)
                           throws java.lang.ArrayIndexOutOfBoundsException

Replaces the specified action by the given action.

Parameters:

indAction - Index of the action to replace.

action - The replacer.

Returns:

true if the replacement has been a success, false otherwise.

Throws:

java.lang.ArrayIndexOutOfBoundsException - If the index is incorrect (index < 0 || index >= uwsActions.size()).

replaceUWSAction

public final UWSAction<JL,J> replaceUWSAction(UWSAction<JL,J> action)

Replaces the action which has the same name that the given action.

Parameters:

action - The replacer.

Returns:

The replaced action or null if the given action is null or if there is no action with the same name (in this case, the given action is not added).

getNbUWSActions

public final int getNbUWSActions()

Gets the number of actions this UWS has.

Returns:

The number of its actions.

getUWSAction

public final UWSAction<JL,J> getUWSAction(java.lang.String actionName)

Gets the action of this UWS which has the same name as the given one.

Parameters:

actionName - The name of the searched action.

Returns:

The corresponding action or null if there is no corresponding action.

getUWSActions

public final java.util.Iterator<UWSAction<JL,J>> getUWSActions()

Gets all actions of this UWS.

Returns:

An iterator on its actions.

getExecutedAction

public final UWSAction<JL,J> getExecutedAction()

Gets the UWS action executed during the last call of executeRequest(HttpServletRequest, HttpServletResponse).

Returns:

The last used UWS action.

removeUWSAction

public final UWSAction<JL,J> removeUWSAction(int indAction)
                                                                             throws java.lang.ArrayIndexOutOfBoundsException

Removes the specified action from this UWS.

Parameters:

indAction - The index of the UWS action to remove.

Returns:

The removed action.

Throws:

java.lang.ArrayIndexOutOfBoundsException - If the given index is incorrect (index < 0 || index >= uwsActions.size()).

removeUWSAction

public final UWSAction<JL,J> removeUWSAction(java.lang.String actionName)

Removes the action of this UWS which has the same name as the given one.

Parameters:

actionName - The name of the UWS to remove.

Returns:

The removed action or null if there is no corresponding action.

createJob

public abstract J createJob(java.util.Map<java.lang.String,java.lang.String> parameters)
                                         throws UWSException

Creates a job of the type (extension of AbstractJob) which parameterized this implementation of AbstractUWS.

Parameters:

parameters - The map of parameters to give to the constructor of AbstractJob.

Returns:

The created job.

Throws:

UWSException - If any error occurs while creating the job.

See Also:

AddJob.apply(UWSUrl, String, HttpServletRequest, HttpServletResponse)

executeRequest

public boolean executeRequest(javax.servlet.http.HttpServletRequest request,
                              javax.servlet.http.HttpServletResponse response)
                       throws UWSException,
                              java.io.IOException

Executes the given request according to the IVOA Proposed Recommendation of 2010-02-10. The result is returned in the given response.

Here is the followed algorithm:

1. Load the request in the UWS URL interpreter (see UWSUrl.load(HttpServletRequest))
2. Extract the user ID (see UserIdentifier.extractUserId(UWSUrl, HttpServletRequest))
3. Iterate - in order - on all available actions and apply the first which matches. (see UWSAction.match(UWSUrl, String, HttpServletRequest) and UWSAction.apply(UWSUrl, String, HttpServletRequest, HttpServletResponse))

Parameters:

request - The UWS request.

response - The response of this request which will be edited by the found UWS actions.

Returns:

true if the request has been executed successfully, false otherwise.

Throws:

UWSException - If no action matches or if any error has occurred while applying the found action.

java.io.IOException - If it is impossible to write in the given HttpServletResponse.

See Also:

UWSUrl.UWSUrl(HttpServletRequest), UWSUrl.load(HttpServletRequest), UserIdentifier.extractUserId(UWSUrl, HttpServletRequest), UWSAction.match(UWSUrl, String, HttpServletRequest), UWSAction.apply(UWSUrl, String, HttpServletRequest, HttpServletResponse)

redirect

public void redirect(java.lang.String url,
                     javax.servlet.http.HttpServletRequest request,
                     javax.servlet.http.HttpServletResponse response)
              throws java.io.IOException,
                     UWSException

Sends a redirection (with the HTTP status code 303) to the given URL/URI into the given response.

Parameters:

url - The redirection URL/URI.

request - The HttpServletRequest which may be used to make a redirection.

response - The HttpServletResponse which must contain all information to make a redirection.

Throws:

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

UWSException - If there is any other error.

sendError

public void sendError(UWSException error,
                      javax.servlet.http.HttpServletRequest request,
                      javax.servlet.http.HttpServletResponse response)
               throws java.io.IOException,
                      UWSException

Fills the response with the given error. The HTTP status code is set in function of the error code of the given UWSException. If the error code is UWSException.SEE_OTHER this method calls redirect(String, HttpServletRequest, HttpServletResponse). Otherwise the function HttpServletResponse.sendError(int, String) is called.

Parameters:

error - The error to send/display.

request - The request which has caused the given error (not used by default).

response - The response in which the error must be published.

Throws:

java.io.IOException - If there is an error when calling redirect(String, HttpServletRequest, HttpServletResponse) or HttpServletResponse.sendError(int, String).

UWSException - If there is an error when calling redirect(String, HttpServletRequest, HttpServletResponse).

See Also:

redirect(String, HttpServletRequest, HttpServletResponse), HttpServletResponse.sendError(int, String)

sendError

public void sendError(java.lang.Exception error,
                      javax.servlet.http.HttpServletRequest request,
                      javax.servlet.http.HttpServletResponse response)
               throws java.io.IOException,
                      UWSException

Fills the response with the given error. The stack trace of the error is printed on the standard output and then the function HttpServletResponse.sendError(int, String) is called with the HTTP status code is UWSException.INTERNAL_SERVER_ERROR and the message of the given exception.

Parameters:

error - The error to send/display.

request - The request which has caused the given error (not used by default).

response - The response in which the error must be published.

Throws:

java.io.IOException - If there is an error when calling HttpServletResponse.sendError(int, String).

UWSException

See Also:

HttpServletResponse.sendError(int, String)

serialize

public java.lang.String serialize(UWSSerializer serializer,
                                  java.lang.String ownerId)
                           throws UWSException

Description copied from class: SerializableUWSObject

Serializes the whole object considering the given owner ID (supposed to be the ID of the current user) and thanks to the given serializer.

Specified by:

serialize in class SerializableUWSObject

Parameters:

serializer - The serializer to use.

ownerId - The ID of the current user.

Returns:

The serialized representation of this object.

Throws:

UWSException - If there is an error during the serialization.

valueBound

public void valueBound(javax.servlet.http.HttpSessionBindingEvent e)

Called by an HttpSession while adding an instance of AbstractUWS in its attributes list.

Specified by:

valueBound in interface javax.servlet.http.HttpSessionBindingListener

See Also:

HttpSessionBindingListener.valueBound(javax.servlet.http.HttpSessionBindingEvent)

valueUnbound

public void valueUnbound(javax.servlet.http.HttpSessionBindingEvent e)

Called by an HttpSession while removing an instance of AbstractUWS from its attributes list. By default, all managed jobs lists are destroyed and so all running jobs are stopped and destroyed.

Specified by:

valueUnbound in interface javax.servlet.http.HttpSessionBindingListener

See Also:

HttpSessionBindingListener.valueUnbound(javax.servlet.http.HttpSessionBindingEvent), removeAllJobLists()