JeeWiz Architect's Guide - DataViewField Object


	The Model-Driven System Builder

JeeWiz Architect's Guide

Contents > 14. 'Business Object' Reference

14.18 DataViewField Object

Superclass baseViewField

Description The data-view-field is used to hold an an external representation of a 'simple' piece of information available from the entity level, or from the user.

'Simple' means, it will be displayed or transmitted to the user as one property (e.g. in XML) or one logical screen field (e.g. in browsers). [A logical screen field could be a group of radio buttons returning a single value or day,month,year fields returning a single date.] It extends the business object model's field by adding relations and an external name.

Fields can be

'inbound' only - specified by user input
'outbound' only - unchangeable information coming from the database
both inbound and outbound - these are fields on the initial entity for the data-view, which can be retrieved from persistent store (outbound) or set/changed by user input (inbound).
neither 'inbound' nor 'outbound'. These are set as default values for display only and can't be changed either by the user or from the database. They may be set programatically and so are not true constants.
It is possible to specify groups of attributes to come from a database, as described in the related-attribute property.

Constraints are allowed for any field, although particular constraints may onlt apply to certain field types. The constraints may be actioned at multiple levels. At the presentation layer, automatically generated create and update events will fire off constraint checking that applies the the dataview field. At the service layer, the same constraints may be fired off by a programmed access which bypasses the standard events. And at the persistence layer the attribute constraints will also fire on an attempt to update the database.

In both the presentation level and the programmatic service level cases, the constaints checked on the dataview field will include those that will be checked on the attributes.

Contained
Lists

1

Name   constraint

Type   constraint

Inherited from   baseViewField

2

Name   style

Type   String

Inherited from   internalClass

3

Name   rolesReadonly

Type   String

Inherited from   entity

4

Name   rolesAllowed

Type   String

Inherited from   entity

5

Name   rolesBlocked

Type   String

Inherited from   entity

Validation 1.   If a data-view-field's related-attribute is specified, there must be an initial entity for the data-view
2.   If a data-view-field's relation is specified, there must also be a related-attribute
3.   Either the name property or the related-attribute property must be specified
4.   If a data-view-field is mapped to an autokey it should not also be classified as required
5.   A data-view-field cannot relate to an attribute that is hidden

Inherited
properties

description from java:interfaceMethod.description

template (base property)

text from java:interfaceMethod.text

jwpattern (base property)

type from baseViewField.type

annotation from java:interfaceMethod.annotation

default from baseViewField.default

access from java:method.access

static from java:method.static

final from java:method.final

volatile from java:field.volatile

readonly from java:field.readonly

readable from baseViewRelation.readable

writeable from baseViewRelation.writeable

uid from constraint.uid

onLoadExpression from baseViewField.onLoadExpression

onStoreExpression from baseViewField.onStoreExpression

filterExpression from baseViewField.filterExpression

lookupGroup from baseViewField.lookupGroup

lookupDataView from baseViewField.lookupDataView

lookupField from baseViewField.lookupField

orderable from baseViewField.orderable

renderSpecial from baseViewField.renderSpecial

htmlInsert from baseViewField.htmlInsert

group from businessMethod.group

required from baseViewField.required

convertEmptyStringsToNull from baseView.convertEmptyStringsToNull

dontDisplay from baseViewField.dontDisplay

externalName from baseViewField.externalName

summaryName from baseViewField.summaryName

useOnSummary from baseViewField.useOnSummary

useOnSearch from baseViewField.useOnSearch

textEvent from baseViewField.textEvent

screenPosition from baseViewField.screenPosition

uiControl from baseViewField.uiControl

format from baseViewField.format

14.18.1	Property 'name'
14.18.2	Property 'switchNameToRelatedAttribute'
14.18.3	Property 'relatedAttribute'
14.18.4	Property 'relation'

14.18.1 Property 'name'

*Overrides*	baseViewField.name
*Description*	The name will become the name of the field in the generated data-view class. The name is required for 'inbound' fields - fields that are set by user input. The name is optional for single 'outbound' fields - fields that are being sent from persistent storage to the user. In this case, the default for the name will be the 'related-attribute' value. See the related-attribute property for a description of groups of attributes and detailed rules. N.B. Because UML requires a model element to have a name, and data-views are a type of model element, we have a special feature to support UML users. This feature is switched on by the 'switch-data-view-field-name-to-related-attribute' flag, which is on by default. When this flag is on, the name is 'transferred' to the related-attribute field under certain conditions. This makes it possible for UML users to specify the name in place of the related-attribute, to create valid UML. (This is relevant when the name can be omitted because it is inferred from the related attribute.) The switch takes place under the following conditions: (a) contains a '*' - indicating that it is a group name (b) both the name is the name of an attribute on the initial entity (or on the effective entity, as indicated by the relation field) and the switch-data-view-field-name-to-related-attribute is set.
*Type*	String

14.18.2 Property 'switchNameToRelatedAttribute'

*Description*	See the description of the 'name' property for details of this field.
*Type*	boolean
*Delegates*	true

14.18.3 Property 'relatedAttribute'

Description

This property should be left blank if the data-view field is derived from user input.

Otherwise, the data-view field comes from a data source which is linked to an attribute (or groups of attributes, as described below) on a related entity.

If the relation property is specified, then the related entity will be the entity implied by the relation. Otherwise, it will be an entity on the data-view's initial entity.

Data-view fields on the initial entity are handled specially because they are potentially 'inbound' (i.e. when a view is destined for writing to persistent storage). Such fields are

pre-validated on input. In other words, the validation from the entity's field is propagated up the architectural stack (to user screens, or to business methods).
they are sent to persistent storage by the view being created or updated.

In contrast, data-view fields that have no related-attribute, or have a relation, are not considered capable of being 'inbound'.

Not all the attributes on an entity need to be specified on a data-view; having a partial view, where some attributes are missing, is the normal case.

On update of an existing record, the existing record is read from persistent storage, the data-view field values set into their corresponding field

Groups of attributes are specified by names consisting of zero or more initial characters ending with a *. This specifies that all fields on the relation or entity that start with the initial characters should be included. The special case of '*' is allowed: this will copy all attributes on the target entity. If this feature is used, it must identify one or more elements: a group with no attributes results in a validation error. The group feature also takes into account data-view-fields that have already been added, and does not re-add them. For example, if you manually data-view-fields of 'name' and '*', then the name field will not be re-added by the '*' group.

To summarise:

inbound fields: related-attribute property not present, so name property is required
outbound single fields: non-group related-attribute property present. Name property is optional.
outbound group fields: identified by '*' in the related-attribute property; name property can be specified (to keep UML tools happy for example), but is ignored.

Type

String

14.18.4 Property 'relation'

*Description*	When a data-view is backed by an entity (the 'initial' entity), the fields can be sourced from that entity, simply by giving the name of the entity's attribute (in the 'related-attribute' property). However, it is also possible to source fields from related entities, using the 'relation' property. To do this, you specify in the 'relation' property the sequence of relationship accessors that must be traversed to get to the related entity. For example, say the initial entity is Order which has has a (many-to-one) relationship to Customer, and the accessor from Order to Customer is 'customer'. Then the relation would be specified as 'customer'. By specifying the 'relation', you identify the related entity; the related-attribute then names the attribute on the related object. Only single-valued relationships (one-to-one or many-to-one) are allowed. In other words, the value of the relationship must be a single entity, so the indicated object is unique. Multi-step relations are possible, by specifying a sequence of accessor names separated with '.'. For example, if our customer has a relation to an employ accessed as 'serviceRep', then a relation of 'customer.serviceRep' would traverse two relations to load the target object. There is no limit on the number of relations that can be used in a multi-step relation.
*Type*	String
*Default*