|
|
|
The Model-Driven System Builder
|
|
JeeWiz Architect's Guide
|
|
|
|
Contents >
14. 'Business Object' Reference
|
|
|
14.5 Attribute Object
| Superclass | field |
| Description | An attribute (in the business object model) is a specialisation of the BOM field (which is in turn a specialisation of the field in the object model).
It adds the following facilities compared to the BOM field:
- getters and setters (from the BOM filed) with readable/writable flags to prevent generation of getters and setters
- persistence for
- session information (across calls into the object)
- entity information (which can be mapped to a database).
The intent is that an attribute should be used where the information is of logical significance - defined in a UML model for example - whereas a field is defined for use in implementation only.
The persistence modelling follows the concepts in J2EE's EJB2.0. There are two formats.
The first format is only used for automatically-generated primary keys of container-managed entity beans. This format is :
name, type, and autokey (=true)
See the 'autokey' attribute description for information on the use of the autokey feature.
The second format is where autokey is false. In that case, only the 'name' of the attribute is mandatory: all other fields have defaults.
|
Contained
Lists |
| 1 |
|
| |
| 2 |
| Name | style |
| Type | String |
| Description | You can specify one or more styles to give information to the code generation scripts.
The meaning of the styles is up to the script writer.
The styles can be used as flags by the script calling
$styleList.contains( "styleOfInterest" )
[ Currently, there is no built-in support for style="styleType=value" type semantics.
This would have to be defined by each script writer.
]
Examples of the use of styles:
- characteristics of a web page (e.g. should it be included in one of the menus)
- whether an entity should be automatically mapped to a data-view (the 'maintain' style).
Note that styles and the 'group' property are different concepts, and therefore complimentary.
Many modelling objects - such as data-views and their fields, or business methods - can be put into groups as a hint as to where to render the UI pages.
Typically groups are used to define 'where' to place the meta class, whereas styles indicate how to render the object.
|
| Unique | false |
|
| |
| 3 |
| Name | rolesReadonly |
| Type | String |
| Description | If the principal is not in the roles-allowed or the roles-blocked, they may have
their access limited to read only by being included in a role here.
|
| Unique | false |
|
| |
| 4 |
| Name | rolesAllowed |
| Type | String |
| Description | If no roles are specified all roles are allowed that are not explicitly prohibited,
otherwise only the specified roles are allowed.
|
| Unique | false |
|
| |
| 5 |
| Name | rolesBlocked |
| Type | String |
| Description | Members of these roles are blocked, whether they are granted permission elsewhere or not.
|
| Unique | false |
|
|
| Validation |
1.
The required attribute is only allowed on entities
2.
Attributes cannot be abstract
3.
Attributes cannot be final
4.
Attributes cannot be volatile
5.
Attributes can not be defined as both autokey and key
6.
The dbms-colum attribute is only allowed on entities
7.
Can not specify dbms-column as a SQL reserved word
|
Inherited
properties |
|
14.5.1 Property 'autokey'
|
| Description | Specifies that automatic keys are to be used.
This implies a persistence model where a 'container' (e.g. the J2EE EJB container) can generate keys automatically.
It is the responsibility of the container's persistence manager to generate the run-time value for this field, which will be available after the entity is created.
By default, attributes are not autokey.
The type of the autokey attributes must be "Integer" or "Long" - the Java class wrappers for "int" and "long".
The type of the autokey attribute becomes the primary key class. Do not mark an autokey attribute as also a key attribute.
|
| Type | boolean |
| Default | false |
14.5.2 Property 'dbmsColumn'
|
| Description | Specifies the DBMS column name where the attribute is persisted.
'dbmsColumn' is used when the attribute forms part of an entity bean and specifies the column name in the table in a DBMS store to where the attribute is persisted.
|
| Type | String |
14.5.3 Property 'key'
|
| Description | Indicates whether attribute forms part of the primary key class.
'key' is either "true" or "false" and indicates whether the attribute forms part of the primary key class for the owning element.
It is ignored by stateful session beans and bean-managed entity beans.
The default value is "false".
'key' should not be specified [or specified as "false"] if 'autokey' is specified as "true" for any attributes of the bean.
|
| Type | boolean |
| Default | false |
14.5.4 Property 'versionController'
|
| Description | Indicates whether attribute is used to validate concurrent changes on update. If data is picked up by a user
and updated, the version-controller field may be used to test whether someone else has altered the record in the interim.
If the property on the entity versionControl=true (also set globally in system.properties) an altered validator
field will cause a runtime error.
|
| Type | boolean |
| Default | false |
14.5.5 Property 'required'
|
| Description | This determines whether a value needs to be input into this attribute.
We refer to attributes with required="true" as 'required' attributes, otherwise as 'optional'.
It is mainly relevant to attributes on entities.
It is equivalent to 'NOT NULL' at the database level.
The standard patterns use this property to
- propagate 'null' to persistent storage (if unset)
- enforce values are present before storage (if set)
- enforce entry of values into screens (if set).
This field applies to strings (text fields), dates and references to other objects.
There is a similar property on data-views.
The standard patterns that create data-views from entities propagate this property from the entity to the corresponding data-view.
Because primitive types cannot be 'unset' - they always have a value - they will alway set a non-null value in persistent storage.
Primitive/value types are ones that are defined by the language and passed as atomic values - like 'int', 'short', 'char' and 'boolean'.
Therefore the only meaning of setting a 'required' attribute for these values is so that it can be propagated by the standard patterns to require entry of a value into a screen.
If you do need to be able to control whether null values can be propagated to persistent storage, use the object type rather than the primitive type.
For example, use 'Integer', 'Short', 'Character, 'Boolean' rather than the primitive types.
By using these types, you will be able to determine whether a value is present (a non-null reference) or missing (a null reference).
Of course this feature comes at a price, namely the incovenience of using the object versions.
Note the following points about processing nulls and empty object types (like Strings or Booleans):
- If the attribute is required and no default is specified, the attribute is initialised with an empty object (an empty string, a Boolean false etc.).
This only applies to required attributes, not optional ones.
This is done at the entity and data-view levels.
- There is a delegated property - 'convert-empty-strings-to-null' - which when set causes empty values input (e.g. on screens) into optional values, to be converted to null.
This property is present on the attribute or data-view-field and their parents.
This property has no effect on required values.
By default, this property is set, because without it there is no way to express 'no value' on input screens.
- A 'required' String value means that the string must be non-null - i.e. there must be a string object available.
However, this does not require the strength to not be empty (length of 0). To express this, add a constraint with min-length=1.
|
| Type | boolean |
14.5.6 Property 'hidden'
|
| Description | Attributes are normally settable by the user, and appear on value objects that are sent to other systems.
However, some attributes may be set internally and so should not be 'published'. Mark these as 'hidden'.
On entities attached to a data-store, hidden fields can be used to establish multiple entities in the same database table.
Hidden attributes cannot appear on data-views, and will not appear on value objects.
|
| Type | boolean |
| Default | false |
14.5.7 Property 'filterExpression'
|
| Description | This property gives an expression to filter incoming string values to be set into a data-view-field
and allows minor pre-processing of values before validation checks are made. When placed on an
attribute it is only intended to be mapped up to default data-view-fields, and will not be reapplied
at the persistence layer.
|
| Type | String |
14.5.8 Property 'collectionElementType'
|
| Description | This property is not used in the standard JeeWiz patterns.
It is only relevant when the value is a collection (or set), and the types of individual objects in the collection.
The type given here can be either the concrete class, an abstract class or an interface implemented by objects in the collection.
You can use a library class name (e.g. 'String'), or the name of a jwclass or interface defined in your JeeWiz model.
|
| Type | String |
| Default | \null |
14.5.9 Property 'dbType'
|
| Description | The db-type is the type held in the entity bean/object, but not how it is accessed from the service layer.
This allows an attribute by attribute mapping to the database to be set up.
Whatever value is set here will need to be mapped in the application server's control settings to whatever
is in the database.
The default is set by the type's default database control, or the attribute's overridden database control.
|
| Type | String |
14.5.10 Property 'ormControl'
|
| Description | Specifies the Java-to-SQL control to use for this property.
This is only necessary if there is a specific style of database mapping that you want to perform;
in this case your architect will tell you the available values of this property and their meaning.
If orm-control is not specified, the default database control for the type will be used.
|
| Type | String |
14.5.11 Property 'dbStyle'
|
| Description | The db-style is used as a request from the modeller to treat the database connection in a particular way. In
practise it is used to select the database control which selects the db-type. At the moment database controls
have no other function and there are very few of them. Most types only have one control and one db-type mapping.
|
| Type | String |
14.5.12 Property 'lookupGroup'
|
| Description | The dataview field can get values from a field in a corresponding search/select page. It
and all other dataview fields with the same lookup group name will be populated on a successful
return from the search/select page. Unlike a relationship lookup, this will not link the
dataview to the dataview backing the search page. This is just a transfer of values from
one screen to another. The lookup-group on an attribute is only useful to map up to the dv field.
|
| Type | String |
14.5.13 Property 'lookupDataView'
|
| Description | The lookup takes place on a search/select page backed by this dataview. This only should
be specified once for the lookup group. If it is specified differently on different lookup
fields of the same lookup group, the result is undefined.
The lookup-data-view on an attribute is only useful to map up to the dv field.
|
| Type | String |
14.5.14 Property 'lookupField'
|
| Description | The data view field is populated from the specified lookup-field on the lookup dataview.
The lookup-group on an attribute is only useful to map up to the dv field.
|
| Type | String |
14.5.15 Property 'access'
|
| Overrides | java:field.access |
| Description | In the business model, business object/methods and attributes are by definition public - they are designed for access by clients outside the object. Therefore the 'access' value is fixed at 'public'.
This factor hides the 'access' property from users.
However, the attribute can be set programmatically (i.e. in some patterns access is set to private) so that it will be rendered via normal field generators according to the architect's design.
|
| Type | String |
| Default | public |
| Hidden | true |
14.5.16 Property 'abstract'
|
| Description | The class or method cannot be abstract. The code generation templates generate this level of detail.
|
| Type | boolean |
| Default | false |
| Hidden | true |
14.5.17 Property 'final'
|
| Overrides | java:field.final |
| Description | This class or method cannot be defined as final. The code generation templates generate this level of detail.
|
| Type | boolean |
| Default | false |
| Hidden | true |
14.5.18 Property 'volatile'
|
| Overrides | java:field.volatile |
| Description | Attributes cannot be volatile.
|
| Type | boolean |
| Default | false |
| Hidden | true |
14.5.19 Property 'convertEmptyStringsToNull'
|
| Description | This delegated property when set causes empty values, on input (e.g. on screens) into optional fields, to be converted to null.
This property is present on the attribute or data-view-field and their parents.
This property has no effect on required values.
By default, this property is set (in the Business Object Model's system.properties).
If this value is not set, there is no way to express 'no value' on input screens.
|
| Type | boolean |
| Delegates | true |
14.5.20 Property 'goodValue'
|
| Description | An acceptable value for this parameter, when used in the encompassing business method
|
| Type | String |
14.5.21 Property 'badValue'
|
| Description | An unacceptable value for this parameter, when used in the encompassing business method
|
| Type | String |
14.5.22 Property 'dontDisplay'
|
| Description | Set this property to prevent the field appearing on a page.
By default this value is false - so the field will appear on the page.
However, the standard patterns set this value true if the type is not displayable.
|
| Type | boolean |
14.5.23 Property 'externalName'
|
| Description | This is the basis for the external name used for the field.
For example, users may think of 'Order Number', whereas the field itself is ord_num (following local variable naming conventions possibly).
For input fields (i.e. one with no related attribute) the external-name defaults to the name (with spaces and capitals added to separate words).
For fields with a related attribute, the external-name defaults to
- the data-view's name if there is one, otherwise to
- the related-attribute's external-name if there is one, otherwise to
- the related-attribute's name.
This can be further mapped to the actual name presented by particular interfaces. This can be done automatically in the component.properties file for the data-view-field.
For example, variants of the name are available through helper methods - getExternal[XML/JavaClass/CapsAndSpaces]Name formats, which may be useful in XML or screen representations of the name.
|
| Type | String |
14.5.24 Property 'summaryName'
|
| Description | A field holding a short name used in grid headers, etc
|
| Type | String |
14.5.25 Property 'useOnSummary'
|
| Description | Use-on-summary tells the standard patterns whether to use this view field on a summary list.
A summary list is shown when the view is the subject of a search (e.g. find all orders for a particular customer) which returns multiple rows.
Rather than bring back all information in an entity or data-view, the summary (based on the summary fields/attributes) is displayed.
The group of all summary fields should be distinctive enough to allow the user to identify a particular record.
There is a related 'use-on-summary' property on the entity's attribute; the relationship between these two is described below.
The standard patterns construct the 'summary' of a view automatically, using the first of the following approaches that succeed:
- One or more fields on the view are explicitly marked 'use-on-summary'.
In this case, the summary is the list of all such fields.
- Failing that, for data-views, the data-view-field may have a related-attribute on the initial entity that is explicitly marked as 'use-on-summary'.
If there are any such data-view-fields, the summary is the list of all such fields.
- Failing that, for data-views, the data-view-field may have a related-attribute on the initial entity that is part of the primary key for the entity.
If there are any such data-view-fields, the summary is the list of all such fields.
- Finally, when all else fails, all fields on the data-view are used. This may result in an interesting rendering!
|
| Type | boolean |
| Default | false |
14.5.26 Property 'useOnSearch'
|
| Description | Use-on-search tells the patterns whether to use this field on a search screen.
|
| Type | boolean |
| Default | false |
14.5.27 Property 'textEvent'
|
| Description | If an event is entered here, when the summary text is printed in a gridline, it will form a URL that fires the event.
|
| Type | String |
14.5.28 Property 'screenPosition'
|
| Description | A numeric value indicating the position of this page or control within a group. This affects the position of the item's display on the screen, relative to other members of the group. The value is a string of 1-6 digits; the order is calculated numerically rather than alphabetically - so 25 is higher than 5. Lower-valued positions appear first. The value of '-1' indicates that the this field should not placed on the ScreenPositionList (determined by the DataView). This would be used when the specific renderer would want to handle the placing of the field rather than via the automatic rendering which is based on the ScreenPositionList. If this is not specified, then the order of controls within a group is determined by the order in the XML specification file. The order within the specification can be set if the XML is being specified directly and this field need not be specified. However, for specifications from UML design tools this may not be possible and it will be necessary to set this field to control screen order.
|
| Type | String |
14.5.29 Property 'uiControl'
|
| Description | Specifies the ui control to use for this field. If specified, this field must correctly name a UI control - see your local standards for a complete list.
The standard JeeWiz options are:
TBD
If there is no value for the ui-control property, a suitable UI control for the type will be chosen.
See also ui-style, which can guide the selection process if ui-control is not specified.
|
| Type | String |
14.5.30 Property 'format'
|
| Description | The format works together with the display style at the presentation layer. It might override the date format for
a textbox date or numeric, or it might override the height and width of a textarea. It is up to the UiControl
as to how, or whether this property is processed.
|
| Type | String |
Copyright (c) 2001-2008 New Technology/enterprise Ltd.
| |
