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.

This file has a very simple DTD:

<!ENTITY database (entity*,attribute*,action*)>

<!ATTLIST database
	user #REQUIRED
	password #REQUIRED
	url #REQUIRED
	driver #IMPLIED
schema #IMPLIED
	default-access #IMPLIED
default-caching #IMPLIED
case #IMPLIED>

<!ENTITY entity (attribute*)>

<!ATTLIST entity
	name #REQUIRED
table #IMPLIED
	access #IMPLIED
	class #IMPLIED
	caching #IMPLIED
obfuscate #IMPLIED
autofetch #IMPLIED>

<!ENTITY attribute #PCDATA> <!-- where #PCDATA is an SQL query with column tags -->

<!ATTLIST attribute
	name #REQUIRED
	result #IMPLIED
	foreign-key #IMPLIED>

<!ENTITY action #PCDATA> <!-- where #PCDATA is an SQL query with column tags -->

<!ATTLIST action
	name #REQUIRED>

(or look at the sample in the overview, anyway you should...).

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 | lowercase	(driver-dependant)	case-sensivity: sensitive, uppercase or lowercase - see remarks
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	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] | rowset[/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/>
  	</attribute>
  </entity>

  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/>
  </attribute>

  In VTL, you can then write :

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

  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.
  
  

• 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.
  
  
• 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 Velosurf must have with SQL keywords (tables and columns). 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.
  • lowercase: Same as above, lowercase.
  If this attribute is not specified, Velosurf will try to deduce the appropriate value from the database vendor. Please note that this behaviour does only concern the SQL facet of Velosurf, and has nothing to do with VTL or velosurf.xml.