Configuration Reference

This page gives the reference of the Velosurf configuration file syntax.

Don't be confused here, 'entity' and 'attribute' are both used as XML concepts and velosurf concepts... The velosurf entity has a corresponding XML element, the velosurf attribute has a corresponding XML element as well, and both have XML attributes.

The configuration file follows this DTD.

In brief:

• the <database> tag is the root element and must provide connection credentials (unless gathered in a <credentials> tag) and an optional schema name. It can contains any number of <entity>, <scalar>, <row>, <rowset> and <action> tags. Attributes and actions defined at this level are qualified as root attributes and actions. Note that you can also specify the username and password within the JDBC url.
• Gathering the credentials (user, password and url) in a <credentials> tag, in conjunction with the use of xinclude, allows to put them in an external file (typically unversionned - very useful to change credetials in different instances of the same webapp). Note that driver and schema can also be specified in the <credentials> tag.
• If present, the root action named startup is executed when Velosurf is initialized.
• <entity> tags usually correspond to a table (but not necessarily). They can contain any number of <scalar>, <row>, <rowset>, <action> and <constraint> tags.
• <scalar>, <row> and <rowset> tags describe a custom entity attribute. Their content is an SQL query where entity columns and other external parameters appear as embedded tags. Their result is respectively a scalar, a row and a rowset.
• <action> tags contain one or several SQL queries where entity columns and other external parameters appear as embedded tags. They return the number of affected rows.
• <constraint> tags gather all the constraints applying to one column input value. Each constraint has a short syntax form (an XML attribute of the <constraint> tag) and an equivalent long syntax form (a child tag) that allows one to customize the error message of the constraint. Warning: the Data Validation module is not actively maintained and could become deprecated or evolve in something else.

The following table describes the meaning of all XML attributes per XML entity.

<database> element (no parent)
XML element	XML attribute	syntax	default value	meaning
database	user	string	(required unless specified in the JDBC URL or in a <credentials> tag)	database account login
database	password	string	(required unless specified in the JDBC URL or in a <credentials> tag)	database account password
database	url	string	(required unless specified in a <credentials> tag)	database URL
database	driver	java_class_name	(none)	database driver class - if not specified, Velosurf will try to deduce it from the database URL
database	schema	string	(none)	schema used, if any
database	read-only	yes | no | true | false	yes	entities default access mode, read-only or read-write
database	caching	none | soft | full	none	default entities caching method (see caching attribute for entities)
database	case	sensitive | uppercase | lowercase	(driver-dependant)	case-sensivity policy used by Velosurf: sensitive, uppercase or lowercase(1)
database	reverse	none | partial | tables | full	full	degree of reverse engineering: in 'partial' mode, only the tables corresponding to entities listed in the configuration file are reverse engineered - in 'full' mode, all tables and foreign keys are reverse engineered
database	loglevel	trace | debug | info | warn | error | fatal	info	logging level, from the most verbose to the less verbose
database	min-connections	integer	1	the initial number of connections in the connection pool
database	max-connections	integer	50	the maximum number of connections in the connection pool
database	seed	string	database url	seed of the encryption engine random generator
database	check-connections	yes | no	yes	states whether connections are checked (and re-opened if necessary) before every statement execution
<credentials> element (optional child of <database> used to gather credentials)
XML element	XML attribute	syntax	default value	meaning
credentials	user	string	(required unless specified in the JDBC URL or in the <database> tag)	database account login
credentials	password	string	(required unless specified in the JDBC URL or in the <database> tag)	database account password
credentials	url	string	(required unless specified in the <database> tag)	database URL
credentials	driver	java_class_name	(none)	database driver class - if not specified, Velosurf will try to deduce it from the database URL
database	schema	string	(none)	schema used, if any
<entity> element (child of <database>)
XML element	XML attribute	syntax	default value	meaning
entity	name	string	(required)	entity name; if it is the name of an existing table, the columns of the table will automatically become attributes of this entity
entity	table	string	entity name	use this attribute if the table name and the entity name are to be different
entity	read-only	yes | no	yes	access mode, read-only or read-write
entity	class	java_class_name	velosurf.context.Instance	java class used to map an instance of this entity
entity	caching	none | soft | full	(none)	caching method: none, soft (automatic with respect to memory) or full (only cleared on Entity.clearCache() calls)
entity	obfuscate	column [,column...]	(none)	columns that will be obfuscated
entity	localize	column [,column...]	(none)	columns that will be localized
<scalar> element (child of <entity>, or of <database> for root attributes)
XML element	XML attribute	syntax	default value	meaning
scalar	name	string	(required)	attribute name, can overload an existing column
scalar	caching	yes | no	no	whether or not this scalar attribute should be cached
<row> element (child of <entity>, or of <database> for root attributes)
XML element	XML attribute	syntax	default value	meaning
row	name	string	(required)	attribute name, can overload an existing column
row	result	entity	(none)	resulting entity, if any, so that other attributes can be called on the result.
row	caching	yes | no	no	whether or not this row attribute should be cached
<rowset> element (child of <entity>, or of <database> for root attributes)
XML element	XML attribute	syntax	default value	meaning
rowset	name	string	(required)	attribute name, can overload an existing column
rowset	result	entity	(none)	resulting entity, if any, so that other attributes can be called on the result.
rowset	caching	yes | no	no	whether or not this rowset attribute should be cached
<aliases> element (child of <entity>)
XML element	XML attribute	syntax	default value	meaning
aliases	string	string	(required)	define all aliases for this entity - for instance: <aliases alias_1='column_1' alias_2='column_2' ... />
<imported-key> element (child of <entity>)
XML element	XML attribute	syntax	default value	meaning
imported-key	name	string	(required)	name given to the relationship
imported-key	entity	string	(required)	name of the entity corresponding to the foreign table
imported-key	foreign-cols	col [ , col... ]	(required)	comma-separated list of the local columns matching the key columns of the foreign table
<exported-key> element (child of <entity>)
XML element	XML attribute	syntax	default value	meaning
exported-key	name	string	(required)	name given to the relationship
exported-key	entity	string	(required)	name of the entity corresponding to the foreign table
exported-key	foreign-cols	col [ , col... ]	(required)	comma-separated list of the foreign columns matching the key columns of the local table
exported-key	order	col [ , col... ]	(none)	comma-separated list of the foreign columns by which the result should be ordered
<action> element (child of <entity>, or of <database> for root actions)
XML element	XML attribute	syntax	default value	meaning
action	name	string	(required)	Action name. If present, the root startup action is performed when Velosurf is initialized.
The following tags belong to the data validation module.
<constaint> element (child of <entity>)
XML element	XML attribute	syntax	default value	meaning
constraint	column	string	(required)	name of this entity's column the constraint is to be applied to
constraint	type	integer | number | date | email	(none)	expected data type - short syntax
constraint	min-len	positive integer	(none)	minimum length - short syntax
constraint	max-len	positive integer	(none)	maximum length - short syntax
constraint	min	integer	(none)	minimum value (implies 'number' data type if none specified) - short syntax
constraint	max	integer	(none)	maximum value (implies 'number' data type if none specified) - short syntax
constraint	after	YYYYMMDD	(none)	data must be a date >= this value (implies 'date' type if none specified) - short syntax
constraint	before	YYYYMMDD	(none)	data must be a date <= this value (implies 'date' type if none specified) - short syntax
constraint	not-empty	true | false	false	data must not be null or empty - short syntax
constraint	not-null	true | false	false	data must not be null - short syntax
constraint	one-of	value[,value...]	false	data must be one of the supplied values - short syntax
constraint	reference	table.column	(none)	data must be present in table.column - short syntax
constraint	regex	pattern	(none)	data must follow the provided pattern - short syntax
<integer> element (child of <constaint>)
XML element	XML attribute	syntax	default value	meaning
integer	min	integer	(none)	minimum value - long syntax
integer	max	integer	(none)	maximum value - long syntax
integer	message	string	field {0}: '{1}' is not in the valid range	message to display when constraint fails
<number> element (child of <constaint>)
XML element	XML attribute	syntax	default value	meaning
number	min	number	(none)	minimum value - long syntax
number	max	number	(none)	maximum value - long syntax
number	message	string	field {0}: '{1}' is not in the valid range	message to display when constraint fails
<min-len> element (child of <constaint>)
XML element	XML attribute	syntax	default value	meaning
min-len	value	positive integer	(required)	minimum length - long syntax
min-len	message	string	field {0}: '{1}' is not in the valid range	message to display when constraint fails
<max-len> element (child of <constraint>)
XML element	XML attribute	syntax	default value	meaning
max-len	value	positive integer	(required)	maximum length - long syntax
max-len	message	string	field {0}: '{1}' is not in the valid range	message to display when constraint fails
<date> element (child of <constraint>)
XML element	XML attribute	syntax	default value	meaning
date	after	YYYYMMDD	(none)	data must be a date >= this value - long syntax
date	before	YYYYMMDD	(none)	data must be a date <= this value - long syntax
date	message	string	field {0}: '{1}' is not a valid date or is outside range	message to display when constraint fails
<email> element (child of <constraint>)
XML element	XML attribute	syntax	default value	meaning
email	check-dns	true | false	false	whether to issue a DNS lookup query to check the validity of the email
email	check-smtp	true | false	false	whether to issue an SMTP login to check the validity of the email
email	message	string	field {0}: '{1}' is not a valid email	message to display when constraint fails
<not-null> element (child of <constraint>)
XML element	XML attribute	syntax	default value	meaning
not-null	message	string	field {0} cannot be null	message to display when constraint fails
<not-empty> element (child of <constraint>)
XML element	XML attribute	syntax	default value	meaning
not-empty	message	string	field {0} cannot be empty	message to display when constraint fails
<one-of> element (child of <constraint>)
XML element	XML attribute	syntax	default value	meaning
one-of	message	string	field {0}: value '{1}' must be one of: value,...	message to display when constraint fails
<value> element (child of <one-of>)
XML element	XML attribute	syntax	default value	meaning
value				specifies a value for the long syntax form of the <one-of> constraint (text content)
<reference> element (child of <constraint>)
XML element	XML attribute	syntax	default value	meaning
reference	foreign-key	table.column	(required)	data must be present in table.column - long syntax
reference	message	string	field {0}: value '{1}' not found in table.column	message to display when constraint fails
<regex> element (child of <constraint>)
XML element	XML attribute	syntax	default value	meaning
regex	pattern	string	(required)	data must follow the provided pattern - long syntax
regex	message	string	field {0}: value '{1}' is not valid	message to display when constraint fails

(1) This case-sensivity parameter indicates the policy that Velosurf must follow with SQL keywords (tables and columns) when speaking with the relational database. It should mimic the behaviour the database engine has with its metadata tables, and the default is chosen depending on the database vendor when known (see DriverInfo.java). It is one of:

• sensitive: It does not necessarily mean that the database is case-sensitive, only that Velosurf won't issue any conversion.
• uppercase: Entities and attributes are case-insensitive; all identifiers will be stored internally and passed to the JDBC driver as uppercase strings (references in templates and names in the configuration file are then case-insensitive).
• lowercase: Same as above, lowercase.

It doesn't impact case of identifiers used in the configuration file or in the templates. Those ones are converted to lowercase by default and this behaviour can be changed via the velosurf.case Java system property.