D.2. PDL Reserved Words

D.2.1. PDL Keywords

The following list, in conjunction with the Section D.2.2 PDL Attribute Types, details all PDL reserved words. Explanations are provided where applicable. Examples of how to use almost all of these keywords can be found in the Chapter 9 Persistence Tutorial.

D.2.1.1. Escaping PDL Keywords

Similar to most other languages, the PDL reserved words are not valid except in the context defined for them unless they are properly escaped. For instance, naming something "composite" or "component" will cause a compilation error because the parser found a "composite" token instead of an "id" token.

The desire to use keywords as well as legal SQL identifiers that would not otherwise be allowed in PDL (such as '#') has prompted the ability to escape special characters and words. In order to use a reserved word or character in a PDL identifier, it is necessary to precede the character with a '\'. For example:

object type StereoReceiver {
    ...
    String[1..1] serial\# = stereo_receiver.serial\#;
    String[0..1] \unique = stereo_receiver.unique_column VARCHAR(100);
    Component[0..1] \component = join stereo_receiver.component_id
                                   to components.component_id;
    ...
}

D.2.1.2. Reserved Words

Reserved Words
---------------------------------------
ADAPTER        = adapter
ADD            = add
AGGRESSIVE     = aggressive <WS> load
ALL            = all
ASSOCIATION    = association
ATTRIBUTES     = attributes
CALL           = do <WS> call
CLASS          = class
CLEAR          = clear
COMPONENT      = component
COMPOSITE      = composite
DATA_OPERATION = data <WS> operation
DELETE         = delete
DO             = do
EXTENDS        = extends
FALSE          = false
FOREIGNKEY     = foreign <WS> key
IMMEDIATE      = immediate
IMPORT         = import
INSERT         = insert
JOIN           = join
MAP            = map
MODEL          = model
OBJECTKEY      = object <WS> key
OBJECTTYPE     = object <WS> type
OPTION         = option
OPTIONS        = options
QUERY          = query
REFERENCEKEY   = reference <WS> key
REMOVE         = remove
RETRIEVE       = retrieve
RETURNS        = returns
SUPER          = super
TO             = to
TRUE           = true
UNIQUE         = unique
UNVERSIONED    = unversioned
UPDATE         = update
VERSIONED      = versioned
WS             = ([ , \t, \n, \r, \f])+

Punctuation
-----------
SEMI     = ;
EQ       = =
DOT      = .
COMMA    = ,
STAR     = *
LBRACE   = {
RBRACE   = }
LBRACKET = [
RBRACKET = ]
LPAREN   = (
RPAREN   = )
COLON    = :

Regular expressions
-------
ID        = (<ESC>|<CH>) (<ESC>|<CH>|<DIGIT>)*
CH        = [a-z, A-Z, _, $]
ESC       = "\\" ~[]
INT       = (<DIGIT>)+
DIGIT     = [0-9]
STRINGLIT = \" ( ~[\"] | \\\" )* \"

Special Tokens
--------------
COMMENT: // (~[\n, \r])* (\n | \r | \r\n)

  • add — used with associations. The PDL file uses the add keyword, along with an association name, to signify that a given association should be inserted into the database.

  • call — used to signify that a Data Operation contains PL/SQL and should use a CallableStatement to execute the block of SQL defined in the do block.

  • clear — used with associations. The PDL file uses the clear keyword, along with an association name, to signify that all associations of the given name should be deleted from the database. This can be thought of as a "remove all" keyword.

  • component — this word is reserved for future use.

  • composite — used to signify a definition of a composite relationship between the current Object Type and another Object Type. This is used in the same fashion as the association keyword.

  • data operation — the keyword used to signify the beginning of a SQL block that is used outside of an object type. It is used for any type of data modeling language (DML) operations, such as insert, update, delete, and PL/SQL procedure calls.

  • default — this word is reserved for future use.

  • delete — used to signify the beginning of the block of code defining the delete event (for example, how to insert an object of the defined type).

  • do — used to signify the beginning of a block of SQL that should be executed by the persistence layer. This is typically used inside defined events.

  • dml — the token used to represent the string data operation. This is used to signify that DML may be executed within the code block.

  • extends — used to signify that the declared object type is a subclass of another object type. This is similar to the Java extends keyword.

  • false — the boolean value false.

  • flexfields — this word is reserved for future use.

  • foreign key — used to signify a foreign key when defining the table schema. It is not currently used in PDL files, but will be added in the future.

  • import — used to signify that another ObjectType will be used by the containing object type. For instance, for an ObjectType that extends ACSObject, the second line of the PDL file would be import com.arsdigita.kernel.*;.

  • insert — used to signify the beginning of the block of code defining the "insert" event (for example, how to insert an object of the defined type).

  • join — a keyword, used in association with to, to define the way to join two database tables together. In object types, sequences of join-to statements are defined to assist the metadata-driven SQL system in generating the standard queries.

  • map — used to signify the beginning of the block that maps attribute names to specific database columns.

  • model — used to define the namespace for the given object type. This is analogous to the package definition in Java.

  • object key — used to uniquely identify a single object of the defined type. For instance, for an ACSObject, the object key is id.

  • object type — used to define the name of the given object type. This is analogous to the Class definition in Java.

  • options — used to signify that the following PDL block is a group of options for the given query or type.

  • query — used to signify the beginning of a named SQL block that is used outside of the standard create, retrieve, update, and delete blocks. It is typically followed by a name (the name is used to identify it in the Java code) and then the block of SQL to execute and the mapping of the block to attribute names.

  • reference key — the keyword used to specify the column that holds an object type's object id locally. In metadata-driven SQL, this information is used to join against the super object type tables.

  • remove — used with associations. The PDL file uses the remove keyword, along with an association name, to signify that a given association should be deleted from the database.

  • retrieve — used to signify the beginning of the block of code defining the retrieve event. One example of this would be a code block specifying how to retrieve an object of the defined type. It can also be used with the keyword all to retrieve all objects of the defined type.

  • returns — used to signify that a definition returns something. One example is returns within a Data Query definition. In that case, it is used as an optional parameter in conjunction with two values to indicate the number of rows that may be returned by the given query.

  • super — used to designate calling the same named method within the parent category. This can only be used when the object type extends another object type and is typically used within SQL event declarations.

  • to — a keyword, used in association with join, to define the way to join two database tables together. In object types, sequences of join-to statements are defined to assist the metadata-driven SQL system in generating the standard queries.

  • true — the boolean value true.

  • unique — signifies that only one object type may have a given value for the attribute or combination of attributes. It also tells the DDL Generator to create a unique constraint.

  • unversioned — means that the versioning service should not version this attribute.

  • update — the keyword used to signify the beginning of the block of code defining the update event (for example, how to update an object of the defined type).

  • versioned — when used in front of an object type, this keyword tells the versioning service to version all instances of this type; when used in front of a compound attribute, this keyword tells the versioning service to version this attribute, even though it would not normally be versioned otherwise.

  • White Space — the token used to signify spaces. That is, " ", "\t", "\n", "\r", or "\f".

D.2.2. PDL Attribute Types

The PDL Attribute Types are the allowed Java types for attributes defined in PDL. Therefore, every type seen here is the Java type returned by the persistence system.

BigInteger
BigDecimal
Boolean
Byte
Character
Date
Double
Float
Integer
Long
Short
String // This should be used for both Strings and Clobs.
Blob   // This actually returns a Byte[] and will be deprecated once
       // the PDL compiler supports arrays.