JeeWiz Architect's Guide - MetaList Object


	The Model-Driven System Builder

JeeWiz Architect's Guide

Contents > 16. 'JeeWiz' Reference

16.8 MetaList Object

Used on

metaFactor

Superclass metaContainedElementBase

Description The list specifies that one or more objects can be nested below the current object. The list is added in XML using a nested element <list>, which creates the MetaList object. The list is implemented as a Java ArrayList, which can be accessed by the list name plus 'List' from Velocity. For example, a list named 'method' is accessible from Velocity by $methodList.

There are two common patterns for using indexes:

A string is listed.

In this case, the name and the type (of 'String') are specified. (Note that String must be specified - it is not the default type for a list.)

The generated code allows lists of strings to be specified in two ways:

as a property, with individual values separated by commas
as nested elements. In this case, the tags used on the nested elements are the name of the list.
For example, if we have a string list defined :

<list name="choice" type="String" >
the choices can be specified in a comma-separated property - choice="A,B" - or as a list:
<choice>A <choice>B
For string lists, the 'unique' property can also be specified. Normally this is false. When unique is set true, validation code is generated to check that all values in the string list are unique.
An object is listed.

In this case, the name of the list gives the XML element tag by which the list will be recognised.

The type of the list can be omitted (and this is quite common): in this case, the list name must also be the name of the meta-class to be listed: this will be the type of the objects created by this list.

If the type is specified, it must be the name of the meta-class; instances of this meta-class's Java class will be created for this list. This can come from the current meta-model or a parent meta-model.

The end result of this form is that

an add[Name]([Type] x) adder method is created on the meta-class, to add <name> elements to the list as 'type' objects
a get[Name]List() getter is created to get the complete list as an ArrayList, containing 'type' objects.
Where objects are listed, JeeWiz provides

the 'index' property, to give automatic indexing of the listed property on the object (usually the name property)
the 'generate-all-list' property to allow derived meta-classes to be listed too.
The generate-all-list feature requires some explanation.

The 'object' (Java language) meta-model defines a list of methods on the jwclass:

<meta-class name="jwclass" <list name="method" description="List of class methods, including constructors" index="name" generate-all-list="true" /> </meta-class>
This gives a list of all methods on the 'jwclass' ('jwclass' is used in the JeeWiz meta-model as the name of the Java 'class'). So the Jwclass class has

an adder 'addMethod(Method)' to add to the list, so elements can be added nested within jwclasses
a getter 'getMethodList()' to get the list.
a lookup method 'getMethodByName(name)' which returns the Method if one of this name exists.
However, because the 'generate-all-list' property is set, constructors, which derive from methods, are also listed by the same statement.

So the Jwclass also has

an adder 'addConstructor(Constructor)' to add to the list, so elements can be added nested within jwclasses
a getter 'getConstructorList()' to get the list.
a lookup method 'getConstructorByName(name)'.
The list feature also works across meta-models. For example, the Business Object meta-model (BOM) derives from the java meta-model, in which the jwclass lists are defined. The BOM has an 'internal-class' meta-class, which derives from java:jwclass. The internal-class declares this list:

<list name="method" index="name" type="java:method" previousMetaModel="java" >
This is saying that the internal-class meta-class wants to add a list of methods (there is a BOM:method that overrides java:method). However, it does not start from scratch, because the java:jwclass already has a list of methods. So the base type being indexed is java:method, and the 'previousMetaModel' is the java meta-model.

The combination of these two properties says: 'create, under internal-class, indexed lists for all meta-classes that derive from java:method, except those already listed in the java model.'

In the BOM, there is a method, which derives from java:method. There are also bom-creator and business-method meta-classes, that derive from BOM:method.

The result of the above list is that the following are added to BOM InternalClass.java:

an 'AddMethod(Method)' adder. Because BOM:method has the same name as its base class, this does not have its own list, it just adds the method onto java:jwclass's method list. However, note that the Method being added here is the BOM variety - so this allows BOM features to be added and the BOM:method to be used. This allows the specifications to be automatically overloaded (i.e. use different underlying meta-classes) without changing the names in the specification.
the adder, getter and lookup for BOM:bom-creator
the adder, getter and lookup for BOM:business-method.
Note that these last two also add their entries onto the java:method list. This means that a business method can be lookup up, or iterated, as a business method, or as one of the wider list of methods.

Inherited
properties

description (base property)

template (base property)

text (base property)

jwpattern (base property)

advanced from metaElementBase.advanced

16.8.1	Property 'name'
16.8.2	Property 'type'
16.8.3	Property 'index'
16.8.4	Property 'unique'
16.8.5	Property 'generateAllList'
16.8.6	Property 'uniqueObject'
16.8.7	Property 'removeDuplicates'
16.8.8	Property 'uniqueString'
16.8.9	Property 'previousModel'
16.8.10	Property 'occurs'
16.8.11	Property 'minOccurs'
16.8.12	Property 'maxOccurs'
16.8.13	Property 'filterCode'

16.8.1 Property 'name'

*Overrides*	metaElementBase.name
*Description*	The name of the meta-class to list.
*Type*	String

16.8.2 Property 'type'

Description

For String lists, this should be String. For meta-class lists of objects in this meta-model, this can be omitted and the type will be deduced from the 'name' property. To join this list onto a list into a parent meta-model, this should be the type of object indexed in the parent (e.g. java:jwclass in the example above).

In the case where generateAllList is set (the normal case), the type should be the very lowest type where this list originated. This prevents the Velocity script from generating a method with the same signature but returning a different value. For example, java:method is indexed by the java:jwclass. Then in BOM:internal-class, there is an 'inherited' list, that is a child of the jwclass's java:method list. The BOM:internal-class specifies type='java:method' on the index.

Type

String

16.8.3 Property 'index'

*Description*	If the index is set, an index will be generated for this list using the value of this property as the field to index. Indexed lists have a 'getXByY(name)' lookup method, where X is the name of the list and Y is the name of the indexed property - e.g. getMethodByName(). Almost invariably, the 'name' property is the one that is indexed. If this property is omitted, the field is not indexed.
*Type*	String

16.8.4 Property 'unique'

*Description*	For object-valued lists, this is used in conjunction with the 'index' property. If unique is set and a property is indexed, non-prephase validation code will be generated to checked that all the indexed objects have distinct (unique) values for their index property. Currently not implemented: For String-valued lists, if 'unique' is set and a property is indexed, non-prephase validation code will be generated to ensure that all strings in the list are unique.
*Type*	boolean
*Default*	false

16.8.5 Property 'generateAllList'

*Description*	If set, this generates a list for the specified meta-class name's type and all its derived meta-classes (up to and including the current meta-model). When generate-all-list is used, the name is ignored. This is because the names of generated lists must be based on the meta-class type names (because there is nothing else sensible to use!). For generate-all-list's, only one index is created when 'index' is used. By default, this is on the base type for the list (as defined in 'type', or 'name'). This default can be changed by 'unique-object'. If generate-all-list is not set, only one list is generated, for the specified meta-class type.
*Type*	boolean
*Default*	false

16.8.6 Property 'uniqueObject'

Description

'unique-object is used in conjunction with the 'index' and generate-all-list properties. When both are set, the default is that the base object type (as specified in the 'type' (or 'name') properties) is indexed. However, it may be that this is not the item that should not be unique.

For example, in the Business Object meta-model, business objects must have unique names, but this does not apply to 'internal-classes' (which are normal Java classes with a base and implementation split). When the internal-class index is defined, unique-object is set to restrict the index to business objects.

This property has no effect on String lists, un-indexed lists, or lists without 'generate-all-list' set.

Type

String

16.8.7 Property 'removeDuplicates'

*Description*	Currently this is only implemented for String-valued lists. If set, any duplicates in the list are removed. This is useful, for example, when specifying exceptions at various levels of the model tree. If the same exception is specified at the multiple points and then used on the list of exceptions, there is would be a duplicate in the generated code without the remove-duplicates facility.
*Type*	boolean
*Default*	false

16.8.8 Property 'uniqueString'

*Description*	Deprecated. Use 'unique' instead, which now applies to String-valued properties as well. Applies only to string lists. If true, causes validation code to be generated to check that all values are unique.
*Type*	boolean
*Default*	false

16.8.9 Property 'previousModel'

*Description*	The previous meta-model that holds a 'base' for this list. Lists will be generated for all meta-models after previous model, up to and including the current one. Objects added to lists in this meta-model will also be added to lists holding base classes for that object, even if the base is in a previous meta-model.
*Type*	String

16.8.10 Property 'occurs'

*Description*	Specifies the precise number of items that must occur in this list. If this value is not set, no check on the exact number of items is generated. This property has no effect on lists with generate-all-list set.
*Type*	int
*Default*	-1

16.8.11 Property 'minOccurs'

*Description*	Specifies the minimum number of items that must occur in this list. If this value is not set, no check on the minimum number of items is generated. This property has no effect on lists with generate-all-list set.
*Type*	int
*Default*	-1

16.8.12 Property 'maxOccurs'

*Description*	Specifies the maximum number of items that may occur in this list. If this value is not set, no check on the maximum number of items is generated. This property has no effect on lists with generate-all-list set.
*Type*	int
*Default*	-1

16.8.13 Property 'filterCode'

*Description*	Where lists need type coercion or other filtering at run-time, specify in this property. This implements automatic type conversion between Java meta-model types. See examples in the Java meta-model.
*Type*	String