# UWS Configuration File

All properties listed in the below table are all the possible UWS configuration properties. Some of them are mandatory. If one of these properties is missing, the UWS Service will not be able to start: an error will be displayed immediately in the application server log and a HTTP 503 error will be sent when accessing the UWS URL.

Besides, you should know that any property key not listed in this table will be ignored without error or warning message.

However, any not allowed property value will generate a warning message in the application server log and the default value will be kept. Thus, the UWS Service will be started and available but the desired configuration value will not be set. So, you should take a look at the application server log every times you start the UWS Service!

Here is an empty minimum UWS configuration file: uws_min.properties and a complete one: uws_full.properties.

Important note: Any limit value is an integer and so can be at most: 231-1 bytes/rows = 2147483647B/R (or also for the byte unit: = 2147483kB = 2147MB = 2GB). Otherwise, you should use the null value 0 to raise the limit constraint.

Legend: M means that the property is mandatory. If nothing is written for the second column, the property is optional.

/ mandatory properties

Property |  | Type | Description | Example
--- | --- | --- | --- | ---
General

home_page

text

This property lets set a custom home page. 4 different kinds of value are accepted:

- nothing (default): the default home page provided by the library (a XML document listing all available job lists).
- name or relative path of a file: this method MUST be chosen if the new home page is a JSP file. This file MUST be inside the directory WebContent of your web application.
- a URI starting with `file://`: in this method the local file pointed by the URI will be merely returned when the home page will be requested.
- a URL: here, a redirection toward this URL will be made at each request on the home page
- a class name: the class name of an extension of uws.service.actions.ShowHomePage which must replace the default home page action. This class MUST have at least one constructor with exactly one parameter not NULL of type uws.service.UWSService.

By default, the default home page provided by the library is used.

- my_uws_homepage.jsp
- jsp/my_uws_homepage.jsp
- file:///home/foo/customHomePage.html
- http://...
- {aPackage.NewHomePage}

home_page_mime_type

text

MIME type of the service home page.

This property is used only if the specified "home_page" is a local file path (i.e. if "home_page=file://...").

If no value is provided "text/html" will be set by default.

Default: `text/html`

- text/html (default)
- text/plain
- application/xml

Service
service_name |  | text | Name of the UWS Service. |
service_description |  | text | Description of the UWS Service. |
Job list

joblists

text

Comma separated list of job list.

At least one name MUST be provided. Otherwise, the UWS service will have no job list and the job execution will not be possible.

- jobs
- myjobs,foo,bar

Job
<jlName>.job_thread |  | text | Class describing the execution of all jobs managed by the job list specified as prefixed of the property name. This property must be a class name (given between {...}). It must reference an extension of uws.job.JobThread. This implementation must have at least a constructor with one parameter of type uws.job.UWSJob. | {aPackage.MySuperJob}

<jlName>.job_parameters

text

List of all expected parameters.

The value of this property is expected to be a comma separated list of parameters. At least a name without any space character is expected. Limits about each parameter MAY be provided. Below are described all types of parameter definition that are supported in this property file:

- Just a name:

  paramName

- String parameter:

  [ paramName , modif? , string , "default" , / regular_expr / i ]

- Numeric parameter:

  [ paramName , modif? , numeric , default , minimum , maximum ]

- Duration parameter:

  [ paramName , modif? , numeric , default , minimum , maximum ]

- Custom:

  [ paramName , { aPackage.ClassName } ]

It is not mandatory to declare all expected parameters in this list. Even non listed parameters will appear in the job description. However any parameter name provided in this list will be recognized case insensitively among the parameters of a job. For instance, if the list contains the parameter `foo` and the user has provided the parameters `foo=bar&FOO=stuff` when creating a job, the library will consider them as the same. It will take the last given value and will report this parameter in its job description as `foo=stuff`.

All attributes except the name and the type (or the class name) are optional. They can be omitted which implies they will be set to their default value ; generally `null`. Here are more details about each attribute:

modif? is a boolean flag aiming to indicate whether the value of the parameter can be modified after initialization of the job. Any value (case insensitive) among the following list is interpreted as `true` ; any other value as `false`: `true`, `t`, `yes` and `y`. If this flag is omitted it will be by default set to `true` (i.e. the parameter can be modified after initialization).

The regular expression must be enclosed by `/`. It can contain any character except `/`. If a such character has to be provided anyway, it can be done by doubling it. For instance: `/foo//bar/i`. The letter `i` after the regular expression is optional. It indicates that the regular expression must be evaluated case insensitively.

The default, minimum and maximum values of numeric and duration parameters must be valid numeric values. For a numeric, any kind of numerical value is accepted. For a duration, only positive or zero long/integer values are accepted. If one of these values is omitted it will be considered as `null` (i.e. no limitation in the case of the minimum and maximum).

A duration value (default, minimum, maximum and even a user value provided when submitting/updating a job) must be a positive or zero long/integer value eventually followed by a unit. Without a unit, by default the duration will be considered as being expressed in milliseconds. The supported unit suffixes are the following (case sensitive): `milliseconds` (or `ms`), `seconds` (or `sec` or `s`), `minutes` (or `min` or `m`), `hours` (or `h`), `days` (or `D`), `weeks` (or `W` ; = 7 days), `months` (or `M` ; = 30 days) and `years` (or `Y` ; = 365 days).

- myFreeParam
- [myCustomParam, {aPackage.MyCustomController}]
- [myNumericParam,false,numeric,0,-180,180]
- [myDurationParam,,duration,,1min,3 hours]
- myFreeParam, [myStringParam,yes,string,"foo",/(foo|bar|other)/i]

Execution management

<jlName>.default_execution_duration

integer/text

Default execution duration of the jobs of the specified job list. The prefix "default" means here that the execution duration will be this one if the client does not set one.

The default duration MUST be less or equals to the maximum execution duration. If this rule is not respected, the default execution duration is set immediately to the maximum execution duration.

A negative or null value means there is no restriction on the default execution duration: the execution could never end. Float values are not allowed.

This duration is expressed by default in milliseconds, but a different unit can be specified. This unit must suffix the value. Allowed units are the following (case sensitive!!): `milliseconds` (or `ms`), `seconds` (or `sec` or `s`), `minutes` (or `min` or `m`), `hours` (or `h`), `days` (or `D`), `weeks` (or `W` ; = 7 days), `months` (or `M` ; = 30 days) and `years` (or `Y` ; = 365 days).

Default: `0` (no restriction)

- 600000 (10 minutes)
- 10m
- 10 minutes
- 10min

<jlName>.max_execution_duration

integer/text

Maximum execution duration of the jobs of the specified job list. The prefix "max" means here that the client can not set a time greater than this one.

The maximum duration MUST be greater or equals to the default execution duration. If this rule is not respected, the default execution duration is set immediately to the maximum execution duration.

A negative or null value means there is no restriction on the maximum execution duration: the execution could never end. Float values are not allowed.

This duration is expressed by default in milliseconds, but a different unit can be specified. This unit must suffix the value. Allowed units are the following (case sensitive!!): `milliseconds` (or `ms`), `seconds` (or `sec` or `s`), `minutes` (or `min` or `m`), `hours` (or `h`), `days` (or `D`), `weeks` (or `W` ; = 7 days), `months` (or `M` ; = 30 days) and `years` (or `Y` ; = 365 days).

Default: `0` (no restriction)

- 3600000 (1 hour)
- 1h
- 1 hours

<jlName>.max_running_jobs

integer

Maximum number of jobs that can run in parallel inside the specified job list.

If negative or `0`, no execution queue will be set. Thus the number of running jobs will be unlimited (default behaviour).

Default: ø (no execution queue)

- -1 (no execution queue)
- 100

<jlName>.execution_manager

text

Class responsible of the execution of all jobs inside the specified job list.

Each time a UWS user asks to start a job, the library will ask to the ExecutionManager of the parent job list in order to know if the execution must start now or later.

This property must be a class name (given between {...}). It must reference an implementation of uws.job.manager.ExecutionManager. This implementation must have at least a constructor with one parameter of type uws.service.log.UWSLog.

It is recommended to extend an existing implementation such as: uws.job.manager.DefaultExecutionManager, uws.job.manager.AbstractQueuedExecutionManager, uws.job.manager.QueuedExecutionManager.

By default, uws.job.manager.DefaultExecutionManager is used IF no `max_running_jobs` is set, otherwise uws.job.manager.QueuedExecutionManager is used.

{aPackage.MyExecutionManager}

Destruction management

<jlName>.default_destruction_interval

integer/text

Default interval between the creation and the automatic destruction of the jobs of the specified job list. The prefix "default" means here that the destruction date will be set automatically by the UWS service if the client does not set one.

The default destruction interval MUST be less or equals to the maximum execution duration. If this rule is not respected, a given destruction interval will be set immediately to the maximum execution interval.

A negative or null value means there is no restriction on the default destruction interval: the job could never be destroyed. Float values are not allowed.

This interval is expressed by default in milliseconds, but a different unit can be specified. This unit must suffix the value. Allowed units are the following (case sensitive!!): `milliseconds` (or `ms`), `seconds` (or `sec` or `s`), `minutes` (or `min` or `m`), `hours` (or `h`), `days` (or `D`), `weeks` (or `W` ; = 7 days), `months` (or `M` ; = 30 days) and `years` (or `Y` ; = 365 days).

Default: `0` (no restriction)

- 600000 (10 minutes)
- 10m
- 10 minutes
- 10min

<jlName>.max_destruction_interval

integer/text

Maximum interval between the creation and the automatic destruction of the jobs of the specified job list. The prefix "max" means here that the client can not set an interval bigger than this one.

The maximum destruction interval MUST be bigger or equals to the default destruction interval. If this rule is not respected, a given destruction interval will be set immediately to the maximum destruction interval.

A negative or null value means there is no restriction on the maximum destruction interval: the job could never be destroyed. Float values are not allowed.

This interval is expressed by default in milliseconds, but a different unit can be specified. This unit must suffix the value. Allowed units are the following (case sensitive!!): `milliseconds` (or `ms`), `seconds` (or `sec` or `s`), `minutes` (or `min` or `m`), `hours` (or `h`), `days` (or `D`), `weeks` (or `W` ; = 7 days), `months` (or `M` ; = 30 days) and `years` (or `Y` ; = 365 days).

Default: `0` (no restriction)

- 3600000 (1 hour)
- 1h
- 1 hours

<jlName>.destruction_manager

text

Class responsible of the destruction of jobs owned by the specified job list.

At each job creation, or each time the destruction time of a job is changed, the DestructionManager of its job list is notified, in order to schedule its automatic destruction when the destruction time is reached. This manager does NOT perform the destruction ; it is just responsible to trigger the automatic job destruction.

This property must be a class name (given between {...}). It must reference an implementation of uws.job.manager.DestructionManager. This implementation must have at least an empty constructor.

It is recommended to extend an existing implementation such as: uws.job.manager.DefaultDestructionManager.

By default, uws.job.manager.DefaultDestructionManager is used.

{aPackage.MyDestructionManager}

Files

file_manager

text

Type of the file manager.

Accepted values are: local (to manage files on the local system). You can also add another way to manage files by providing the name (within brackets: {...}) of a class implementing UWSFileManager and having at least one constructor with only a java.util.Properties parameter.

- local
- {apackage.MyUWSFileManager}

file_root_path

text

Local file path of the directory in which all UWS files (logs, errors, job results, backup, ...) must be.

The file path must be either an absolute local directory path or a directory path relative to WebContent (i.e. the web application directory in which there are WEB-INF and META-INF).

- /home/my_home_dir/uwsFiles
- uwsFiles
- WEB-INF/uwsFiles

directory_per_user

boolean

Tells whether a directory should be created for each user. If yes, the user directory will be named with the user ID. In this directory, there will be error files, job results and it may be the backup file of the user.

Default: `true`

- true (default)
- false

group_user_directories

boolean

Tells whether user directories must be grouped. If yes, directories are grouped by the first letter found in the user ID.

Default: `false`

- true
- false (default)

Log files

logger

text

Only two possibilities are already implemented.

- default: default logger provided by the library. Any logged message will be appended in the file 'service.log' inside the root directory of this service (cf property `file_root_path`).
- slf4j: wrapper for SLF4J. All log messages will be forwarded to SLF4J. It is up to the implementor to add the suitable JAR files in the Java class-path.

  Exactly two JAR files are expected by SLF4J to work as expected:

  - slf4j-api-{version}.jar (the main API)
  - and the slf4j-{binding}-{version}.jar

  Depending on the chosen SLF4J binding, you may also add another JAR file (e.g. Log4J, LogBack, ...) in the Java class-path.

  A configuration file might also be needed. There, it will be possible to configure the following loggers:

  - "uws.service" (general/root purpose log),
  - "uws.service.UWS" (UWS actions),
  - "uws.service.HTTP" (HTTP requests and responses),
  - "uws.service.JOB" (UWS's jobs actions),
  - "uws.service.THREAD" (job's thread actions)

Default: `default` (i.e. uws.service.log.DefaultUWSLog)

- default
- slf4j
- {aPackage.MyLogger}

min_log_level

text

Minimum level that a message must have in order to be logged by the default logger.

5 possible values:

- DEBUG: every messages are logged.
- INFO: every messages EXCEPT DEBUG are logged.
- WARNING: every messages EXCEPT DEBUG and INFO are logged.
- ERROR: only ERROR and FATAL messages are logged.
- FATAL: only FATAL messages are logged.

Note: This property is ignored if `logger != default`.

Default: `DEBUG` (every messages are logged)

- DEBUG
- INFO
- WANRING
- ERROR
- FATAL

log_rotation

text

Frequency of the log file rotation performed by the default logger. That's to say, logs will be written in a new file after this period. This avoid having too big log files. Old log files are renamed so that highlighting its logging period.

The frequency string must respect the following syntax:

- 'D' hh mm: daily schedule at hh:mm
- 'W' dd hh mm: weekly schedule at the given day of the week (1:sunday, 2:monday, ..., 7:saturday) at hh:mm
- 'M' dd hh mm: monthly schedule at the given day of the month at hh:mm
- 'h' mm: hourly schedule at the given minute
- 'm': scheduled every minute (for completness :-))

Where: hh = integer between 0 and 23, mm = integer between 0 and 59, dd (for 'W') = integer between 1 and 7 (1:sunday, 2:monday, ..., 7:saturday), dd (for 'M') = integer between 1 and 31.

Warning: The frequency type is case sensitive! Then you should particularly pay attention at the case when using the frequency types 'M' (monthly) and 'm' (every minute).

Note: This property is ignored if `logger != default`.

Default: `D 0 0` (daily at midnight)

- D 6 30
- W 2 6 30
- M 2 6 30
- h 10
- m

UWS Backup

backup_frequency

text or integer

Frequency at which the UWS service (that's to say, all its users and jobs) must be backuped.

Allowed values are: `never` (no backup will never be done), `user_action` (each time a user does a writing action, like creating or execution a job), a time (must be positive and not null) in milliseconds.

The value `user_action` can be used ONLY IF `backup_mode=true`.

Default: `backup_frequency=never` (no backup)

- never (default)
- user_action
- 3600000 (1 hour)

backup_by_user

text

Tells whether the backup must be one file for every user (`false`), or one file for each user (`true`). This second option should be chosen if your UWS Service is organizing its files by user directories ; see the property directory_per_user.

This option can be enabled ONLY IF a user identification method is provided ; see property `user_identifier`.

Default: `false`

- false (default)
- true

User identification

user_identifier

text

Class to use in order to identify a user of the UWS service. The same instance of this class will be used for every request sent to the service.

The value of this property MUST be a class name (with brackets: {...}) of a class implementing the interface uws.service.UserIdentifier. This class MUST have one of its constructors with no parameter.

By default, no identification is performed ; all users are then anonymous and their jobs can be seen by everybody.

{apackage.FooUserIdentifier}

Job serialization

additional_serializers

text

Comma-separated list of additional UWS serializers.

A UWS serializer lets convert a job description into a specific format. A given serializer is used when the HTTP content-type of a request is set to the MIME-Type of this serializer. The MIME-Type associated with a serializer is provided by its function getMimeType().

By default, the UWS library supports the XML (content-type: `text/xml`) and JSON (content-type: `application/json`) serializations. If the given MIME-Type is unknown or is not provided, the default behavior is to describe the jobs into the XML format.

By default, this list is empty ; only the default serializers (XML and JSON) are available.

- {aPackage.MySuperSerializer}
- {aPackage.MySerializer1}, {aPackage.MySerializer2}

xslt_stylesheet

text

URL of the XSLT stylesheet to link with all XML serializations of jobs (and its parameters).

By default, no XSLT stylesheet is defined.

- http://myuws.com/mySuperXSLT.xslt

error_writer |  | text | Class responsible of writing the error messages when an HTTP request fails. By default, all errors are returned in HTTP format using the class uws.service.error.DefaultUWSErrorWriter. | {aPackage.MySuperErrorWriter}
Additional UWS Actions

additional_actions

text

Comma-separated list of additional UWS actions.

By default, the following standard UWS actions are already existing (with exactly this name): `Show UWS Home Page` (0), `List Jobs` (1), `Add Job` (2), `Set UWS Parameter` (3), `Destroy Job` (4), `Get Job` (5), `Get Job Parameter` (6) and `Set Job Parameter` (7). With this property, you can add or replace a custom actions to your UWS service.

To merely add a new action, the syntax is:

`index:``className`

The `index` with the following `:` are optional. If an index is specified, the action will be inserted at this position in the list of all actions (standard and custom) of the UWS service ; above the index of all UWS standard actions is specified. If no index is specified, the `:` separator MUST be omitted, and the new action will be added at the end of the UWS actions list.

To replace an existing action, no index should be specified (if there is, it will be ignored) and the implementation of the function UWSAction.getName() MUST return the exact (case sensitivity is enabled) name of the action to replace.

Important note: An action name is used only to identify internally a UWS action. To effectively trigger the execution of an action you must carefully implement the function UWSAction.match(...). The whole list of actions (standard and custom) is evaluated in the creation order. So if a standard action matches a request, the additional actions will never be evaluated ; the evaluation of the standard actions must all fail before getting a chance to evaluate any of the custom actions. That's why you have the possibility to insert an action wherever you want in the list, and to replace existing actions.

Each item of the list MUST be the name of a class implementing uws.service.actions.UWSAction. This class MUST have at least one constructor with exactly one parameter of type uws.service.UWSService.

By default, this list is empty ; only the standard UWS actions exist.

- {aPackage.MySuperAction}
- 2:{aPackage.MyOtherSuperAction}
- 0:{aPackage.FirstAction}, {aPackage.LastAction}

HTTP request parser

request_parser

text

Class to use in replacement of the default UWSRequestParser. A request parser aims to interpret all incoming HTTP requests. You may need to customize it if, for instance, you want to handle a special way to provide parameters (note that 'multipart/form-data' is already supported by the default implementation of the UWS library).

This property must be a class name (given between {...}). It must reference an implementation of uws.service.request.RequestParser. This implementation must have at least a constructor with a single parameter of type uws.service.file.UWSFileManager.

It is recommended to extend an existing implementation such as: uws.service.request.UWSRequestParser.

By default, uws.service.request.UWSRequest is used

{aPackage.MyRequestParser}

Custom UWS Factory

uws_factory

text

Class to use in replacement of the default UWSFactory.

This property must be a class name (given between {...}). It must reference an implementation of UWSFactory. This implementation must have at least an empty constructor.

It is recommended to extend an existing implementation such as: uws.service.AbstractUWSFactory.

Warning! By default, the default UWSFactory (uws.config.ConfigurableUWSFactory) is used and support all the following properties:

- request_parser,
- <joblist>.job_thread,
- <joblist>.job_parameters,
- <joblist>.default_execution_duration,
- <joblist>.max_execution_duration,
- <joblist>.default_destruction_interval,
- <joblist>.max_destruction_interval.

Replacing the default UWSFactory by your own implementation implies that you will have to deal with all these properties by yourself.

{aPackage.MyUWSFactory}