546 lines
23 KiB
Plaintext
546 lines
23 KiB
Plaintext
# ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
|
|
|
|
#
|
|
|
|
# adl-1.4.dtd
|
|
|
|
#
|
|
|
|
# Purpose:
|
|
|
|
# Document Type Description for Application Description
|
|
|
|
# Language. Normative for now; will be replaced by a schema. `
|
|
|
|
#
|
|
|
|
# Author: Simon Brooke <simon@cygnets.co.uk>
|
|
|
|
# Created: 24th January 2006
|
|
|
|
# Copyright: (c) 2007 Cygnet Solutions
|
|
|
|
#
|
|
|
|
# ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
|
|
|
|
# $Revision: 1.5 $
|
|
|
|
# ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
|
|
|
|
# Before we start: import XHTML for use in documentation sections
|
|
|
|
# ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
|
|
|
|
# ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
|
|
|
|
# Before we start: some useful definitions
|
|
|
|
# ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
|
|
|
|
# some basic character entities inherited from HTML. Actually we probably ought to
|
|
# import all the HTML4 character entity files, and possibly the HTML4 Strict DTD (so
|
|
# that we can allow HTML block level entities within content elements
|
|
|
|
# boolean means true or false
|
|
|
|
Boolean = "true" | "false"
|
|
# Locale is a string comprising an ISO 639 language code followed by a space
|
|
# followed by an ISO 3166 country code, or else the string 'default'. See:
|
|
# <URL:http://www.ics.uci.edu/pub/ietf/http/related/iso639.txt>
|
|
# <URL:http://www.chemie.fu-berlin.de/diverse/doc/ISO_3166.html>
|
|
Locale = string
|
|
# permissions a group may have on an entity, list, page, form or field
|
|
# permissions are deemed to increase as you go right. A group cannot
|
|
# have greater permission on a field than on the form it is in, or
|
|
# greater permission on form than the entity it belongs to
|
|
#
|
|
# none: none
|
|
# read: select
|
|
# insert: insert
|
|
# noedit: select, insert
|
|
# edit: select, insert, update
|
|
# all: select, insert, update, delete
|
|
Permissions = "none" | "read" | "insert" | "noedit" | "edit" | "all"
|
|
# actions which should be cascaded to dependent objects. All these values except
|
|
# 'manual' are taken from Hibernate and should be passed through the adl2hibernate
|
|
# mapping transparently. Relevent only for properties with type='entity', type='link'
|
|
# and type='list'
|
|
#
|
|
# all : cascade delete, save and update
|
|
# all-delete-orphan : see hibernate documentation; relates to transient objects only
|
|
# delete : cascade delete actions, but not save and update
|
|
# manual : cascading will be handled in manually managed code, code to
|
|
# handle cascading should not be generated
|
|
# save-update : cascade save and update actions, but not delete.
|
|
CascadeActions =
|
|
"all" | "all-delete-orphan" | "delete" | "manual" | "save-update"
|
|
# data types which can be used in a typedef to provide validation -
|
|
# e.g. a string can be used with a regexp or a scalar can be used with
|
|
# min and max values
|
|
# string: varchar java.sql.Types.VARCHAR
|
|
# integer: int java.sql.Types.INTEGER
|
|
# real: double java.sql.Types.DOUBLE
|
|
# money: money java.sql.Types.INTEGER
|
|
# date: date java.sql.Types.DATE
|
|
# time: time java.sql.Types.TIME
|
|
# timestamp: timestamp java.sql.Types.TIMESTAMP
|
|
# uploadable: varchar java.sql.Types.VARCHAR
|
|
# image: varchar java.sql.Types.VARCHAR
|
|
#
|
|
# uploadable is as string but points to an uploaded file; image is as
|
|
# uploadable but points to an uploadable graphical image file
|
|
DefinableDataTypes =
|
|
"string"
|
|
| "integer"
|
|
| "real"
|
|
| "money"
|
|
| "date"
|
|
| "time"
|
|
| "timestamp"
|
|
| "uploadable"
|
|
# data types which are fairly straightforward translations of JDBC data types
|
|
# boolean: boolean or java.sql.Types.BIT
|
|
# char(1) java.sql.Types.CHAR
|
|
# text: text or java.sql.Types.LONGVARCHAR
|
|
# memo java.sql.Types.CLOB
|
|
SimpleDataTypes = DefinableDataTypes | "boolean" | "text"
|
|
# data types which are more complex than SimpleDataTypes...
|
|
# entity : a foreign key link to another entity (i.e. the 'many' end of a
|
|
# one-to-many link);
|
|
# list : a list of some other entity that links to me (i.e. the 'one' end of
|
|
# a one-to-many link);
|
|
# link : a many to many link (via a link table);
|
|
# defined : a type defined by a typedef.
|
|
ComplexDataTypes = "entity" | "link" | "list" | "defined"
|
|
# data types which require special handling - which don't simply map onto
|
|
# common SQL data types
|
|
# geopos : a latitude/longitude pair (experimental and not yet implemented)
|
|
# image : a raster image file, in jpeg|gif|png format (experimental, not yet implemented)
|
|
# message : an internationalised message, having different translations for different locales
|
|
SpecialDataTypes = "geopos" | "image" | "message"
|
|
# all data types
|
|
AllDataTypes = ComplexDataTypes | SimpleDataTypes | SpecialDataTypes
|
|
# content, for things like pages (i.e. forms, lists, pages)
|
|
Content = head | top | foot
|
|
FieldStuff = field | fieldgroup | auxlist | verb
|
|
PageContent = Content | FieldStuff
|
|
PageStuff = PageContent | permission | pragma
|
|
# Properties for pages:
|
|
# name: obviously, the name (URL stub) of the page
|
|
# properties: the properties of the entity the page describes to be shown
|
|
# as fields on the page
|
|
# all: obviously, all properties (except the abstract primary key, if
|
|
# present)
|
|
# user-distinct: all properties which are user-distinct (NOTE: Not yet implemented)
|
|
# listed: only those properties for which fields are explicitly listed
|
|
PageAttrs =
|
|
attribute name { text },
|
|
attribute properties { "all" | "user-distinct" | "listed" }
|
|
# Actions for generators (mainly for keyfields - see entity 'generator', below
|
|
# assigned: In manually-maintained code, you contract to assign a value
|
|
# to this property before it is persisted.
|
|
# guid: The system will supply a unique GUid value to this field
|
|
# before it is persisted.
|
|
# mannual: You contract to supply a generatos class in manually maintained
|
|
# code.
|
|
# native: The database will supply a unique value to this field when it
|
|
# is persisted; the value will be an integer. RECOMMENDED!
|
|
GeneratorActions = "assigned" | "guid" | "manual" | "native"
|
|
# sequences for orderings of lists - see entity 'order'
|
|
# canonical: Whatever the normal canonical ordering for this datatype is -
|
|
# typically alpha-numeric, except for dates, etc.
|
|
# reverse-canonical: The reverse of the above
|
|
#
|
|
# possibly there should be some further values but I have no idea what these are
|
|
Sequences = "canonical" | "reverse-canonical"
|
|
# ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
|
|
|
|
# Elements
|
|
|
|
# ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
|
|
|
|
# the application that the document describes: required top level element
|
|
#
|
|
# name: the name of this application
|
|
# version: the version number of this application
|
|
# revision: the revision of the ADL document
|
|
# currency: the base monetary currency, in the form of an ISO 4217 three-letter code
|
|
# xmlns: XML namespace, in case required
|
|
application =
|
|
element application {
|
|
attlist.application,
|
|
specification*,
|
|
documentation?,
|
|
content?,
|
|
typedef*,
|
|
group*,
|
|
entity*
|
|
}
|
|
attlist.application &=
|
|
attribute name { text },
|
|
attribute version { text }?,
|
|
attribute revision { text }?,
|
|
attribute currency { text }?
|
|
# the definition of a defined type. At this stage a defined type is either
|
|
# a string in which case it must have size and pattern, or
|
|
# a scalar in which case it must have minimum and/or maximum
|
|
# pattern must be a regular expression as interpreted by org.apache.regexp.RE
|
|
# minimum and maximum must be of appropriate format for the datatype specified.
|
|
# Validation may be done client-side and/or server-side at application layer
|
|
# and/or server side at database layer.
|
|
#
|
|
# name: the name of this typedef
|
|
# type: the simple type on which this defined type is based; must be
|
|
# present unless in-implementation children are supplied
|
|
# size: the data size of this defined type
|
|
# pattern: a regular expression which values for this type must match
|
|
# minimum: the minimum value for this type (if base type is scalar)
|
|
# maximum: the maximum value for this type (if base type is scalar)
|
|
typedef =
|
|
element typedef {
|
|
attlist.typedef, documentation?, in-implementation*, help*
|
|
}
|
|
attlist.typedef &=
|
|
attribute name { text },
|
|
attribute type { DefinableDataTypes }?,
|
|
attribute size { text }?,
|
|
attribute pattern { text }?,
|
|
attribute minimum { text }?,
|
|
attribute maximum { text }?
|
|
# information about how to translate a type into types known to different target
|
|
# languages. TODO: Once again I'm not wholly comfortable with the name; I'm not
|
|
# really comfortable that this belongs in ADL at all.
|
|
#
|
|
# target: the target language
|
|
# value: the type to use in that target language
|
|
# kind: OK, I confess I don't understand this, but Andrew needs it...
|
|
in-implementation =
|
|
element in-implementation {
|
|
attlist.in-implementation, documentation?
|
|
}
|
|
attlist.in-implementation &=
|
|
attribute target { text },
|
|
attribute value { text },
|
|
attribute kind { text }?
|
|
# a group of people with similar permissions to one another
|
|
#
|
|
# name: the name of this group
|
|
# parent: the name of a group of which this group is subset
|
|
group = element group { attlist.group, documentation? }
|
|
attlist.group &=
|
|
attribute name { text },
|
|
attribute parent { text }?
|
|
# an entity which has properties and relationships; maps onto a database
|
|
# table or a Java serialisable class - or, of course, various other things
|
|
#
|
|
# name: obviously, the name of this entity
|
|
# natural-key: if present, the name of a property of this entity which forms
|
|
# a natural primary key [NOTE: Only partly implemented. NOTE: much of
|
|
# the present implementation assumes all primary keys will be
|
|
# integers. This needs to be fixed!] DEPRECATED: remove; replace with the
|
|
# 'key' element, below.
|
|
# table: the name of the table in which this entity is stored. Defaults to same
|
|
# as name of entity. Strongly recommend this is not used unless it needs
|
|
# to be different from the name of the entity
|
|
# foreign: this entity is part of some other system; no code will be generated
|
|
# for it, although code which links to it will be generated
|
|
entity =
|
|
element entity {
|
|
attlist.entity,
|
|
documentation?,
|
|
prompt*,
|
|
content?,
|
|
key?,
|
|
property*,
|
|
permission*,
|
|
(form | page | \list)*
|
|
}
|
|
attlist.entity &=
|
|
attribute name { text },
|
|
attribute natural-key { text }?,
|
|
attribute table { text }?,
|
|
attribute foreign { Boolean }?
|
|
# contains documentation on the element which immediately contains it. TODO:
|
|
# should HTML markup within a documentation element be allowed? If so, are
|
|
# there restrictions?
|
|
documentation =
|
|
element documentation { attlist.documentation, (text | reference)* }
|
|
attlist.documentation &= empty
|
|
# an explicit primary key, possibly compound
|
|
key = element key { attlist.key, property* }
|
|
attlist.key &= empty
|
|
# a property (field) of an entity (table)
|
|
#
|
|
# name: the name of this property.
|
|
# type: the type of this property.
|
|
# default: the default value of this property. There will probably be
|
|
# magic values of this!
|
|
# typedef: name of the typedef to use, it type = 'defined'.
|
|
# distinct: distinct='system' required that every value in the system
|
|
# will be distinct (i.e. natural primary key);
|
|
# distinct='user' implies that the value may be used by users
|
|
# in distinguishing entities even if values are not formally
|
|
# unique;
|
|
# distinct='all' implies that the values are formally unique
|
|
# /and/ are user friendly (NOTE: not implemented).
|
|
# entity: if type='entity', the name of the entity this property is
|
|
# a foreign key link to.
|
|
# if type='list', the name of the entity that has a foreign
|
|
# key link to this entity
|
|
# farkey: if type='list', the name of farside key in the listed
|
|
# entity; if type='entity' and the farside field to join to
|
|
# is not the farside primary key, then the name of that
|
|
# farside field
|
|
# required: whether this propery is required (i.e. 'not null').
|
|
# immutable: if true, once a value has been set it cannot be changed.
|
|
# size: fieldwidth of the property if specified.
|
|
# concrete: if set to 'false', this property is not stored in the
|
|
# database but must be computed (manually written code must
|
|
# be provided to support this)
|
|
# cascade: what action(s) on the parent entity should be cascaded to
|
|
# entitie(s) linked on this property. Valid only if type='entity',
|
|
# type='link' or type='list'.
|
|
# column: name of the column in a SQL database table in which this property
|
|
# is stored. TODO: Think about this.
|
|
# unsaved-value:
|
|
# of a property whose persistent value is set on first being
|
|
# committed to persistent store, the value which it holds before
|
|
# it has been committed
|
|
property =
|
|
element property {
|
|
attlist.property,
|
|
documentation?,
|
|
generator?,
|
|
(permission | option | prompt | help | ifmissing)*
|
|
}
|
|
attlist.property &=
|
|
attribute name { text },
|
|
attribute type { AllDataTypes },
|
|
attribute default { text }?,
|
|
attribute typedef { text }?,
|
|
attribute distinct { "none" | "all" | "user" | "system" }?,
|
|
attribute entity { text }?,
|
|
attribute farkey { text }?,
|
|
attribute required { Boolean }?,
|
|
attribute immutable { Boolean }?,
|
|
attribute size { text }?,
|
|
attribute column { text }?,
|
|
attribute concrete { Boolean }?,
|
|
attribute cascade { CascadeActions }?
|
|
# marks a property which is auto-generated by some part of the system.
|
|
# This is based on the Hibernate construct, except that the Hibernate
|
|
# implementation folds both its internal generators and custom generators
|
|
# onto the same attribute. This separates them onto two attributes so we
|
|
# can police values for Hibernate's 'builtin' generators.
|
|
#
|
|
# action: one of the supported Hibernate builtin generators, or
|
|
# 'manual'. 'native' is strongly recommended in most instances
|
|
# class: if action is 'manual', the name of a manually maintained
|
|
# class conforming to the Hibernate IdentifierGenerator
|
|
# interface, or its equivalent in other languages
|
|
generator =
|
|
element generator { attlist.generator, documentation?, param* }
|
|
attlist.generator &=
|
|
attribute action { GeneratorActions },
|
|
attribute class { text }?
|
|
# A parameter passed to the generator. Again, based on the Hibernate
|
|
# implementation. TODO: #PCDATA is wrong as the content model, as embedded
|
|
# markup is definitely not allowed!
|
|
#
|
|
# name: the name of this parameter
|
|
#
|
|
# TODO: This needs to be renamed or removed because it conflicts with the
|
|
# XHTML element of the same name. In fact it could be simply removed since
|
|
# our usage is compatible with the XHTML usage, but it might be less
|
|
# ambiguous to rename it.
|
|
param = element param { attlist.param, text }
|
|
attlist.param &= attribute name { text }
|
|
# one of an explicit list of optional values a property may have
|
|
# NOTE: whether options get encoded at application layer or at database layer
|
|
# is UNDEFINED; either behaviour is correct. If at database layer it's also
|
|
# UNDEFINED whether they're encoded as a single reference data table or as
|
|
# separate reference data tables for each property.
|
|
#
|
|
# value: the value of this option
|
|
#
|
|
# TODO: This needs to be renamed or removed because it conflicts with the
|
|
# XHTML element of the same name. In fact it could be simply removed since
|
|
# our usage is compatible with the XHTML usage, but it might be less
|
|
# ambiguous to rename it.
|
|
option = element option { attlist.option, documentation?, prompt* }
|
|
# if the value is different from the prompt the user sees, specify it
|
|
attlist.option &= attribute value { text }?
|
|
# permissions policy on an entity, a page, form, list or field
|
|
#
|
|
# group: the group to which permission is granted
|
|
# permission: the permission which is granted to that group
|
|
permission = element permission { attlist.permission, documentation? }
|
|
attlist.permission &=
|
|
attribute group { text },
|
|
attribute permission { Permissions }
|
|
# pragmatic advice to generators of lists and forms, in the form of
|
|
# name/value pairs which may contain anything. Over time some pragmas
|
|
# will become 'well known', but the whole point of having a pragma
|
|
# architecture is that it is extensible.
|
|
pragma = element pragma { attlist.pragma, documentation? }
|
|
attlist.pragma &=
|
|
attribute name { text },
|
|
attribute value { text }
|
|
# a prompt for a property or field; used as the prompt text for a widget
|
|
# which edits it. Typically there will be only one of these per property
|
|
# per locale; if there are more than one all those matching the locale may
|
|
# be concatenated, or just one may be used.
|
|
#
|
|
# prompt: the prompt to use
|
|
# locale: the locale in which to prefer this prompt
|
|
prompt = element prompt { attlist.prompt, documentation? }
|
|
attlist.prompt &=
|
|
attribute prompt { text },
|
|
attribute locale { Locale }
|
|
# helptext about a property of an entity, or a field of a page, form or
|
|
# list, or a typedef. Typically there will be only one of these per property
|
|
# per locale; if there are more than one all those matching the locale may
|
|
# be concatenated, or just one may be used.
|
|
#
|
|
# locale: the locale in which to prefer this prompt
|
|
help = element help { attlist.help, text }
|
|
attlist.help &= attribute locale { Locale }
|
|
# helpful text to be shown if a property value is missing, typically when
|
|
# a form is submitted. Typically there will be only one of these per property
|
|
# per locale; if there are more than one all those matching the locale may
|
|
# be concatenated, or just one may be used. Later there may be more sophisticated
|
|
# behaviour here.
|
|
ifmissing = element ifmissing { attlist.ifmissing, text }
|
|
attlist.ifmissing &= attribute locale { Locale }
|
|
# a form through which an entity may be added or edited
|
|
#
|
|
# TODO: This needs to be renamed because it conflicts with the
|
|
# XHTML element of the same name.
|
|
form = element form { attlist.form, documentation?, PageStuff* }
|
|
attlist.form &= PageAttrs
|
|
# a page on which an entity may be displayed
|
|
page = element page { attlist.page, documentation?, PageStuff* }
|
|
attlist.page &= PageAttrs
|
|
# an ordering or records in a list
|
|
# property: the property on which to order
|
|
# sequence: the sequence in which to order
|
|
order = element order { attlist.order, documentation? }
|
|
attlist.order &=
|
|
attribute property { text },
|
|
attribute sequence { Sequences }?
|
|
# a list on which entities of a given type are listed
|
|
#
|
|
# onselect: name of form/page/list to go to when
|
|
# a selection is made from the list
|
|
\list =
|
|
element list { attlist.list, documentation?, (PageStuff | order)* }
|
|
attlist.list &=
|
|
PageAttrs,
|
|
attribute onselect { text }?
|
|
# a subsidiary list, on which entities related to primary
|
|
# entities in the enclosing page or list are listed
|
|
#
|
|
# property: the property of the enclosing entity that this
|
|
# list displays (obviously, must be of type='list')
|
|
# onselect: the form or page of the listed entity to call
|
|
# when an item from the list is selected
|
|
# canadd: true if the user should be able to add records
|
|
# to this list
|
|
auxlist =
|
|
element auxlist {
|
|
attlist.auxlist, documentation?, (prompt | FieldStuff)*
|
|
}
|
|
attlist.auxlist &=
|
|
PageAttrs,
|
|
attribute property { text },
|
|
attribute onselect { text }?,
|
|
attribute canadd { Boolean }?
|
|
# a group of fields and other controls within a form or list, which the
|
|
# renderer might render as a single pane in a tabbed display, for example.
|
|
fieldgroup =
|
|
element fieldgroup {
|
|
attlist.fieldgroup,
|
|
documentation?,
|
|
(prompt | permission | FieldStuff)*
|
|
}
|
|
attlist.fieldgroup &= attribute name { text }
|
|
# a field in a form or page
|
|
#
|
|
# property: the property which this field displays/edits
|
|
field =
|
|
element field {
|
|
attlist.field, documentation?, (prompt | help | permission)*
|
|
}
|
|
attlist.field &= attribute property { text }
|
|
# a verb is something that may be done through a form. Probably the verbs 'store'
|
|
# and 'delete' are implied, but maybe they need to be explicitly declared. The 'verb'
|
|
# attribute of the verb is what gets returned to the controller
|
|
verb =
|
|
element verb {
|
|
attlist.verb, documentation?, (prompt | help | permission)*
|
|
}
|
|
attlist.verb &=
|
|
attribute verb { text },
|
|
attribute dangerous { Boolean }
|
|
# a container for global content
|
|
content = element content { attlist.content, Content* }
|
|
attlist.content &= empty
|
|
# content to place in the head of the generated document; this is #PCDATA
|
|
# because it will almost certainly belong to a different namespace
|
|
# (usually HTML)
|
|
#
|
|
# TODO: This needs to be renamed or removed because it conflicts with the
|
|
# XHTML element of the same name. In fact it could be simply removed since
|
|
# our usage is compatible with the XHTML usage, but it might be less
|
|
# ambiguous to rename it.
|
|
head = element head { attlist.head, text }
|
|
attlist.head &= empty
|
|
# content to place in the top of the body of the generated document;
|
|
# this is %Flow; which is any HTML block or inline level element.
|
|
top = element top { attlist.top, text }
|
|
attlist.top &= empty
|
|
# content to place at the foot of the body of the generated document;
|
|
# this is %Flow; which is any HTML block or inline level element.
|
|
foot = element foot { attlist.foot, text }
|
|
attlist.foot &= empty
|
|
# The 'specification' and 'reference' elements are for documentation only,
|
|
# and do not contribute to the engineering of the application described.
|
|
#
|
|
# A specification element is intended chiefly to declare the reference
|
|
# documents which may be used in documentation elements later in the
|
|
# document.
|
|
#
|
|
# url: The URL from which the document referenced can be retrieved
|
|
# name: The full name (title) given to this document
|
|
# abbr: A convenient abbreviated name
|
|
specification =
|
|
element specification {
|
|
attlist.specification, documentation?, reference*
|
|
}
|
|
attlist.specification &=
|
|
attribute url { text }?,
|
|
attribute name { text },
|
|
attribute abbr { text }
|
|
# The 'specification' and 'reference' elements are for documentation only,
|
|
# and do not contribute to the engineering of the application described.
|
|
#
|
|
# A reference element is a reference to a specifying document.
|
|
#
|
|
# abbr: The abbreviated name of the specification to which this
|
|
# reference refers
|
|
# section: The 'anchor part' (part following a hash character) which,
|
|
# when appended to the URL, will locate the exact section
|
|
# referenced.
|
|
# entity: A reference to another entity within this ADL document
|
|
# property: A reference to another property within this ADL document;
|
|
# if entity is also specified then of that entity, else of
|
|
# the ancestor entity if any
|
|
reference = element reference { attlist.reference, documentation? }
|
|
attlist.reference &=
|
|
attribute abbr { text }?,
|
|
attribute section { text }?,
|
|
attribute entity { text }?,
|
|
attribute property { text }?
|
|
start = application
|