VTL reference
Java reference
Velosurf FAQ

XML Configuration

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

The DTD can be found here.
Here is the syntax and meaning of all the XML attributes:

XML entity XML attribute syntax default value meaning
database user string  (required) database account login
database password  string (required) database account password
database url  string (required) 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 default-access ro | rw ro entities default access mode, read-only or read-write
database default-caching none | soft | full none default caching method
database case sensitive |
uppercase |
(driver-dependant) case-sensivity: sensitive, uppercase or lowercase - see remarks
database reverse none | partial | full full degree of reverse-enginering: in the 'partial' mode, only the tables corresponding to entities listed in the config file are reverse-enginered - it may become the default mode in future versions
database loglevel trace | debug | info | warn | error trace 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
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 access ro | rw ro 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 (that must inherit velosurf.context.Instance and have the same constructor, see the javadoc)
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 autofetch [[query.]name =] http_param_name (none) whenever http_param_name is found in the HTTP query string, the HttpQueryTool interprets it as a primary key and fetches the corresponding instance, storing it in the context under $name or $query.name (or the name of the entity if unspecified)
attribute name  string (required) attribute name, can overload an existing column
attribute result scalar |
row[/entity] |
(none) result type: scalar, single row or rowset ; in the last two cases, the resulting entity can be specified, so that access can be re-entrant; in the first case (scalar), the engine will return the value found in the first column of the first row.
attribute foreign-key column_name (none) foreign-key column towards the entity specified as a result (that is required in this case) ; when this XML attribute is used, the SQL query is ignored ; in fact this XML attribute is just a shorthand for the join query
action name  string (required) action name

And some important remarks on this config file:

  • root attributes and actions: Along with attributes and actions declared inside an entity (that become properties of this entity), attributes and actions can be declared directly under <database>: they become root attributes and root actions, direct properties of $db.
    If specified, the root action named startup is executed at startup.

  • using current instance values: SQL queries of attributes and actions may (and often have to) reference columns of the current instance, by simply inserting XML tags at the right place.

    For instance, assuming 'owner_id' is a field of the 'event' table:
    <entity name="event">
    	<attribute name="owner" result="row/user">
    		select * from user where user_id = <owner_id/>

    Then, in VTL, if $event contains an event, then $event.owner will return the user that owns the event.

  • external parameters: sometimes there is the need for an external parameter to appear in an SQL query. In that case, it can be named as an XML tag inside the query, and later used by setting its value on the surrounding entity (or on $db for root actions/attributes).

    For instance, here is the definition of a root attribute that lists all events of a month:
    <attribute name="month_events" result="rowset/event">
    	select * from event where month(event_date) = <selected_month/>

    In VTL, you can then write:

    #set($db.selected_month = 3)
    #foreach($event in $db.month_events)
     ... display the event ...

    Note that the name selected_month does not correspond to anything in the database: it is only a label that can be used as a prepared statement parameter.

    Note also that external parameters only retain their value within the scope of one VelosurfTool instance (which is the request scope by default).

  • XML parsing of queries: Since XML parsers may add spaces here and there inside #PCDATA, and since that may sometimes break the syntax of SQL queries, it is a good idea to specify xml-space="preserve" as an XML attribute of any XML entity containing a SQL query.

  • escaping of XML special characters: be sure to escapes characters < > & and ' with their XML equivalent whenever they appear inside your queries.

  • IDs obfuscation: When you obfuscate a key column, be sure to also obfuscate all foreign-keys that reference this column. If you want to specify an explicit value to an obfuscated column (via an update or an insert), you have to obfuscate it first since it will always be deobfuscated - you can do so with the entity.obfuscate(value) method. Please note that this feature requires some javax.crypto classes that are not included by default in the jdk for versions prior to 1.4 ; in this case, you'll have to download the Java Cryptographic Extension (jce1_2_2.jar and sunjce_provider.jar) from java.sun.com.

  • Autofetching: Autofetching only works if you are using the toolbox.xml mechanism and the velosurf.tool.HttpQueryTool tool. Here are the VTL equivalent for the three forms of the declaration (assuming the HttpQueryTool is named $query):
    • <entity name="user" autofetch="user_id"/> is equivalent to:
      #if( $query.user_id ) #set( $user = $db.user.fetch( $query.user_id )) #end
    • <entity name="user" autofetch="logged_user=user_id"/> is equivalent to:
      #if( $query.user_id ) #set( $logged_user = $db.user.fetch( $query.user_id )) #end
    • <entity name="user" autofetch="query.logged_user=user_id"/> is equivalent to:
      #if( $query.user_id ) #set( $query.loggued_user = $db.user.fetch( $query.user_id )) #end

  • Case-sensivity: Indicates the policy that Velosurf must follow with SQL keywords (tables and columns). It should mimic the behaviour the database engine has with its metadata tables, and the default is choosen depending on the database vendor (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.

  • Connection pooling: Velosurf uses two connection pools. One with connections having the autocommit flag set to true for all standard queries, and one with connections having the autocommit flag set to false for transactionnal queries (i.e. composite queries made of a sequence of several atomic queries, and on wich a rollback must be issued when something goes wrong during the processing). Since such queries are usually less frequent and less heavy than standard ones, the latter pool is initialized with only one connection. The min-connections parameter only applies to the former pool.