D. How to customize a UWS ?

2. UWS administration

Jobs lists management

As a jobs list is a container of jobs, a UWS is mainly a container of jobs lists. Thus to add a jobs list you must use the method addJobList(JobList).

Warning !

A job list can be added in a UWS only if there is not already another job list with the same name. Indeed the name of a job list is used to build its URI. If two jobs list have the same name, there would be no way to determine the corresponding jobs list from the same URI.

In AbstractUWS two kinds of method can be used to remove jobs lists: removeJobList(String), removeJobList(JobList) and removeAllJobLists() ONLY remove the specified jobs list(s) from the UWS whereas destroyJobList(String), destroyJobList(JL) and destroyAllJobLists() also destroy its (their) job(s).

Remember that destroying a job means stopping the job if running and destroying all its resources (thread, files, ...) (see C.5. Destruction for more details).

And finally, jobs lists can also be retrieved either by their name (hence the name unicity), with the function getJobList(String), or thanks to an iterator with the function iterator().

Controllers

Since a web-service may be used by many clients (human or software), all the occupied resources may increase in an unpredictable manner. This, is particularly true for a UWS whose the clients may create more than one job. Indeed, each job is associated to one thread for its execution and to two managers - one for its execution and the other for its destruction - which must be notified of any modification of all their managed jobs. Besides the execution itself may need to generate some additional threads. And obviously one job may write one or several results files whose the size is likelly unpredictable (it depends of the type of job).

However the computing and the memory resources can be more controlled thanks to the attributes executionDuration and destruction of all managed jobs. Indeed, provided that all managed jobs are created, updated and destroyed by requests interpreted in first by the UWS, it is possible for a UWS to allow or to forbid some ranges of value for these job attributes.

For that a UWS is associated to two objects which let it setting a default and a maximum value for these attributes. The first one is an instance of ExecutionDurationController and the second one of DestructionTimeController. Here is a UML class diagram of these classes:

The UML class diagram of the two UWS controllers.

Both classes have two common methods: init(Map<String, String>) and control(AbstractJob, Map<String,String>). The first method is used to initialize the destruction or the execution duration attribute at the creation of a new job. The map parameter contains all the parameters with which the new job must be initialized. And the second method checks the destruction or the execution duration attribute given in the map parameter when a request has for goal to set the specified attribute to the given job.

Note:

Even if these controllers have common methods, there is no common interface because there are only two job attributes for which there is a real reason to be controlled by a UWS (additional parameters are not considered here because they are specific to a given type of job, and so there is no reason that they can be controlled globaly by a UWS). However if it becomes needed to have a common interface and an extendable list of controllers in a UWS, please send me a mail so that changing the library in this way.

For both of these attributes there is a default value (used only at the job creation) and a maximum value. They have been both set in the second UWS example - Algorithms:

public class UWSAlgorithms extends HttpServlet {
	...
	@Override
	public void init(ServletConfig config) throws ServletException {
		...
		// Set the destruction time for all jobs:
		DestructionTimeController destController = uws.getDestructionTimeController();
		destController.setDefaultDestructionInterval(1, DateField.MONTH);				// = job destroyed 1 month after its creation
		destController.allowModification(false);										// = no modification
		
		// Set the execution time for all jobs:
		ExecutionDurationController execController = uws.getExecutionDurationController();
		execController.setDefaultExecutionDuration(3600);								// = job execution limited to 3600s (1 hour)
		execController.allowModification(false);										// = no modification
		...
	}
	...
}

Information about a UWS

The following functions give several information about the current status of the UWS which can be usefull for the administrator:

AbstractUWS:
- getName()
- getDescription()
- getBaseURI(): gets the base URI (that's to say the URI of the UWS)
- getExecutedAction(): gets the last executed action (see D.6. Actions)
- getChoosenSerializer(): gets the serialize used by the last executed action (see D.7 Serialization)
ExecutionManager:
- getNbRunningJobs()
- getRunningJobs()
- getNbQueuedJobs()
- getQueuedJobs()
QueuedExecutionManager:
- getNbMaxRunningJobs(): gets the maximum number that can run in the same time. The other jobs are put in the queue.
DestructionManager:
- getNextDestruction(): gets the date of the next automatic job destruction
- getNextJobToDestroy()
- getNbJobsToDestroy()
JobList:
- getNbJobs(): gets the number of all the jobs
- getNbJobs(String): gets the total number that the specified owner has in this jobs list
- getNbUsers(): gets the number of users that have at least one job in this jobs list
- getUsers(): gets the list of users that have at least one job in this jobs list
AbstractJob:
- getPhase(): gets the current phase of the job

All these information can be used to display an information page about the UWS, as it has been done in the second UWS example (see D.6. Actions for more details). We could also imagine an administrator page where some points of the UWS can be dynamically set (for instance: set the number of maximum running jobs, set the default value for the execution duration or for the destruction time, ....).

Previous Top Next