Contents

  1. Introduction
  2. Naming rules
  3. Usage convention
  4. Several models splitting
  5. DTD vs. Schemas
  6. Management of multilingualism
  7. Using object references
  8. Using templates
  9. Using content lists
  10. Using marks
  11. Java classes references

Full sample

Introduction

The purpose of this document is to present all the potential of the data descriptive grammar of Leonardi.

This grammar uses the XML (eXtended Markup Language) standard notation. It is required from the reader to have some little knowledge of this technology (see http://www.w3.org/XML/ for more information).

XML documents that follow this grammar are describing, on a logical point of view, the data models of the application programs made with Leonardi.

Main elements defined inside are :

XML documents are also describing information about the mapping between the logical data and the physical data sources.

Finally, XML documents enable to describe the sequence of actions invoked during the execution of the program.

Naming rules

The names of XML tags are written with capital letters. When those names are composed of several words, a separator character is used, the underscore character ( _ ).

The names of attributes of XML tags are written with small letters, unless the first character of the second word if the name is composed of two words.

When the value of an attribute is alphanumeric, the type of this value is CDATA.

When the value of an attribute is numeric, the type of this value is NMTOKEN.

When the value of an attribute is Boolean, available values are true and false, both written with small letters.

When the value of an attribute belongs to a list of discrete values, all the discrete values are written with capital letters using the underscore character as a separator if their name is composed of several words.

Attributes of the type ID are named id.

Attributes of type IDREF are named idref unless several attributes of the same XML tag have the same type.

Attributes of type IDREFS are named idrefs.

Usage convention

A full applicative model is generally splitted into several files: These files are placed by convention in a directory named info.

If project contains sub-projects, sub-directories named are added to this directory with a similar organisation.

Several models splitting

In addition to the splitting mentioned above, an applicative model may be splitted in several models containing specific information:

app root model containing inclusion of models described below.
data data model containing classes and attributes definition.
bind binding model containing information about conversion between logical model defined in the data model and physical model representing the datasource model.
gui GUI model (Graphical User Interface) containing information for GUI construction such as displayable labels and actions definition.
label labels model containing dynamic labels (optional).

In this case, classes definition will be splitted into at least 3 parts: data, binding and GUI.

The usage involve to split the info directory (and potential sub-projects directories) in sub-directories corresponding to each type of model (app, data, bind, gui, label).

The grammars corresponding to the different types of models are the following :

GrammarDTD
Completeleon.dtd
Rootleon_app.dtd
Data (DATA)leon_data.dtd
Bindings (BIND)leon_bind.dtd
GUI, Labelsleon_gui.dtd

The use of a unique model or of a splitted model are strictly the same. This choice mainly depends on the way to organize the information.

DTD vs. Schemas

For more concision and readability, the definitions of the tags and entities forming the data descriptive grammar are presented as an extract of a DTD. However the set of grammars presented in the previous chapter exists as schemas.

The set of available grammars is:

GrammarDTDSchema
Completeleon.dtdleon.xsd
Rootleon_app.dtdleon_app.xsd
Dataleon_data.dtdleon_data.xsd
Bindingsleon_bind.dtdleon_bind.xsd
GUI, Labelsleon_gui.dtdleon_gui.xsd

The use of one or other of the definitions is left with the choice of the developer, the features are strictly the same.

Management of multilingualism

All the strings that will be displayed in the future application can be managed with a key inside the data model. The translations of those keys are stored inside files that can be regarded as dictionaries.

Those dictionaries follow these rules:

Inside XML data models, those keys will be used rather than raw strings.

Keys are written with capital letters and the underscore character is used as a separator when names are composed of several words.

	<NAME value="The title of the application"/>

	<NAME value="TITLE_KEY"/>
However, in all the examples of this manual, raw strings will be used rather than keys to insure better readability.

Using object references

The main objects described inside the XML data model (ACTION, CHOICE, CLASS, DATE, FILE, FILTER, NUMBER, PACKAGE, RELATION, SORT, TEXT) should be identified with a unique identifier in the whole model.

The identifier of an object is defined with an attribute that is named id and should be always filled in. Identifiers should follow the naming rules of the XML grammar.

	<ATTLIST OBJECT
		id ID #REQUIRED
	... >

Note: OBJECT is a fictitious element that just gives an example of the syntax.

This identifier enables referencing the current object. It can be referenced by other objects of the data model with the help of IDREF or IDREFS attributes. Examples: template object, attributes of a class, target attribute of a sort...

Forward references are permitted since the Leonardi parser will solve them.

	<ATTLIST OBJECT
		id ID #REQUIRED
		target IDREF #IMPLIED
		list IDREFS #IMPLIED
		... >

Note: OBJECT is a fictitious element that just gives an example of the syntax.

An error is raised during the parsing if a reference that does not match any object is found.

In most cases, references are expecting objects of a certain type (the attributes of a CLASS object should be defined as reference to FIELD objects). When a defined reference refers an object of the wrong type, an error is raised during the parsing. Required types will be defined throughout this manual.

Some references refer to predefined objects of Leonardi. In order to avoid confusion, all the identifiers of those predefined objects start with the underscore ( _ ) character.

Users should not use this naming convention for defining their own objects and keep in mind that this method is reserved for Leonardi. The reasons are: avoid confusion and keep consistency with future evolutions of the Leonardi software.

Using templates

The main objects described inside the XML data model (ACTION, CHOICE, CLASS, DATE, FILE, FILTER, NUMBER, PACKAGE, RELATION, SORT, TEXT) can be defined by using an existing object of the same type as a template.

When using a template object, all the properties are copied to the current object, except from the identifier, which is unique. Using this technique enables to create a new object with a pattern and to define only the distinct properties.

The following example illustrates the creation of an element, object2, with the use of the element object1 as a template.

	<OBJECT id='object2' template='object1'>
		<!-- Only distinct properties are defined there -->
		...
	</OBJECT>

Note: OBJECT is a fictitious element that just gives an example of the syntax.

The only constraint of this technique is that both elements should of the same type (OBJECT in the example); otherwise, an error would be raised during the parsing of the XML model.

Using content lists

A content list is a list of element that is contained inside an element of higher level. Examples: list of attributes of a CLASS element, list of target classes of a RELATION element...

In most cases, the syntax followed by those content lists looks like the one below.

	<!ELEMENT PARENT
		...
		(OBJECTS*)
		...>

This example of DTD shows an element of type PARENT that can contain several content list definitions. The way in which all occurrences of the content list are merged is defined with the value of the operation attribute, which is described below.

	<!ELEMENT OBJECTS
		(OBJECT | OBJECT_REF)+>

The content list is a combination of objects declarations and objects references. Creating an empty content list is not permitted.

	<!ATTLIST OBJECTS
		idrefs IDREFS #IMPLIED
		condition CDATA #IMPLIED
		operation (RESET | ADD | REMOVE) 'ADD'
		position NMTOKEN #IMPLIED>

Note: PARENT, OBJECTS, OBJECT, OBJECT_REF are fictitious elements that just gives an example of the syntax.

A content list has the following attributes:

Attribute Mand. Description Default
idrefs no This attribute contains a list of objects identifiers. This method is another way to define the references of objects inside this list.

The references of objects of the list could be defined by using this method or by giving their definition or their object reference inside the content of this list. Both methods can be used at the same time.

The references of objects of the list could be defined by using this method or by giving their definition or their object reference inside the content of this list. Both methods can be used at the same time.

Identifiers should refer objects of the expected type; otherwise, an exception would be raised during parsing. Expected object types will be defined throughout this manual.

 
condition no The value of this attribute is a convenient way to control the existence of this list. The condition refers to the name of a property that has to be defined inside the initialisation file of the application. (.ini)

If this property does not exists or its value equals false or 0, the list will be ignored during the parsing process. Otherwise, it is taken into account.

This attribute can help to manage on a same system several applications that have nearly the same data model. Using this condition enables to define differences between applications.

 
operation yes This attributes tells how several content list are merged:
ADDObjects referred inside this content list are just added to the list of objects contained inside the object of higher level.
REMOVEObjects referred inside this content list are removed from the list of objects contained inside the object of higher level
RESETThe current list replace the existing list of objects contained inside the object of higher level

This attribute is very useful when an object is created with the help of a template. Then, it avoids defining again the complete list of object references because it enables to define only differences with the list owned by the template object.

ADD
position no This attributes gives the index where the current list is inserted inside the existing list of objects when the merge method defined in the operation attribute is ADD. Otherwise, it is not taken into account.

The value should be an integer that should be greater or equal to zero and lower than the size of the existing list of objects. If this rule is not followed, an error is raised during the parsing process.

 

Using marks

Some elements of the data model can have some marks defined (actions, classes, fields, filters).

A common property is defined for all objects that have a same mark. This property is related to a treatment inside Leonardi.

Like contents lists, an object of the data model can have several lists of marks. The method for merging those lists of marks is described below.

	<!ELEMENT OBJECT
		...
		(OBJ_MARKS*)
		...>
Two kinds of marks are available: Predefined marks are defined inside an object as attributes of the A_MARKS element for the actions, attributes of the C_MARKS element for the classes and attributes of the F_MARKS element for the fields. Each predefined mark is connected to a generic behaviour in the Leonardi application.

Specific marks can be used for the specific needs of an application made with Leonardi. Those marks are created with help of the MARK element and are identified with their name.

	<!ELEMENT OBJ_MARKS (MARK*)>

	<!ATTLIST MARK
		name CDATA #REQUIRED>
The list of marks has the attributes condition and operation that are the same as those of the content list.
	<!ATTLIST OBJ_MARKS
		condition CDATA #IMPLIED
		operation (RESET | CLEAR | AND | OR | XOR) 'OR'
		... predefined marks
		...>
Note: OBJECT and OBJ_MARKS are fictitious elements that just give an example of the syntax.

Attribute Mand. Description Default
condition no The value of this attribute is a convenient way to control the existence of this list of marks. The condition refers to the name of a property that has to be defined inside the initialisation file of the application. (.ini)

If this property does not exists or its value equals false or 0, this list of marks will be ignored during the parsing process. Otherwise, it is taken into account.

This attribute can help to manage on a same system several applications that have nearly the same data model. Using this condition enables to define differences between applications.

 
operation yes This attributes tells how several list of marks are merged.

Each list of marks has the same behavior as bit set, so the merge of two of these list is a logical operation.

The permitted values for this attribute are:
OREach mark of the current list is added to the list of existing marks of the object of higher level.
ANDEach mark that belongs to the current list and the previous list of marks of the object of higher level are kept and are defined the new list of the marks of this object.
XOREach mark of the current list that was not defined yet for the object of higher level is added to its list of marks. Marks that belong to the current list and the existing list are removed from the existing list of marks.
CLEAREach mark of the current list that belongs to the existing list of marks of the object of higher level is removed.
RESETThe current list of marks replace the existing list of marks, which is discarded.

This attribute gives a convenient method to create an object with a template and to change its list of marks without rebuilding it entirely.

OR

Java classes references

Some elements have attributes that expect a JAVA class name as a value. The names of the classes for those attributes should contain the package name and the class name:
	<package name>.<class name>

	(Example: "leon.app.behavior.LySessionBehavior").
Usually, such attributes are used to define specific behaviors for an object of the data model.

The classes that define specific behaviour should implement interfaces that are defined inside the Leonardi API. The usual way is to override a public class from the leon.app.behavior package and to override the appropriate methods to create specific behaviours. Further explanations will be given throughout this document.

Those classes should also have a constructor method that has the suitable parameters in order to ensure instantiations with introspection mechanisms. The user should look at the generic class used to implement the generic behaviour to use its constructor method as a pattern.

Finally, the named classes have to be present inside the CLASSPATH for the application to access them at the starting.