Entity(3NS)

NAME

SYNOPSIS

DESCRIPTION

IMPLEMENTATION

NOTES

WARNINGS

NAME

Entity - Abstract base class ythat handles persistance.

SYNOPSIS

Entity

Namespace Procedure Constructors

EntityCreate	{ entity }
EntityArrayCopy	{ entity }
EntityQuery	{ entity }
EntityNext	{ entity }
EntityInsert	{ entity }
EntityInsertUpdate	{ entity }
EntityUpdate	{ entity }

EntityUpdateWhere	{ entity }
EntityDelete	{ entity }
EntityDeleteWhere	{ entity }
EntityRefresh	{ entity }
EntityRetrieve	{ entity }
EntityMdtRetrieve	{ entity }
EntityGetAttribute	{ entity }
EntityValue	{ entity }
EntityRetrieveOidBy	{ entity }
EntityRetrieveObjBy	{ entity }
EntityGetListOf	{ entity }
EntityContainedList	{ entity }
EntityContainer	{ entity }
EntityCount	{ entity }
EntityTransition	{ entity }

Static Public Interface

Entity::Create	{ class objRef {selectList} }
Entity::ArrayCopy	{ class objRef {selectList} }	: objList
Entity::Query	{ class objRef {where} {order} }
Entity::Next	{ class objRef }	: 1(Success), 0(Failure)
Entity::Insert	{ class objRef }	: oid
Entity::InsertUpdate	{ class objRef attr value {attr value} ... }	: oid
Entity::Update	{ class objRef }
Entity::UpdateWhere	{ class objref attr value {attr value} ... }
Entity::Delete	{ class objRef }
Entity::DeleteWhere	{ class attr value {attr value} ... }
Entity::Refresh	{ class objRef }	: 1(Success), 0(Failure)
Entity::Retrieve	{ class oid objRef {selectList} }	: 1(Success), 0(Failure)
Entity::MdtRetrieve	{ class oid objRef }	: 1(Success), 0(Failure)
Entity::GetAttribute	{ class {attribute} {property} {enumTagList} }	: results - See documentation
Entity::ContainedList	{ class containerOid {selectList} }	: objList
Entity::Container	{ class oid objref }	: 1(Success), 0(Failure)
Entity::Value	{ class oid attr {value} }	: value
Entity::RetrieveOidBy	{class attr value ...}	: oidList
Entity::RetrieveObjBy	{class attr value ... }	: objList
Entity::GetListOf	{class attr}	: valueList
Entity::Count	{ class {attr} {attr value} ... }	: count
Entity::Transition	{ class event objref }	: newState
Entity::EnumValue	{enumValueList value}	: enumValue {terse : Verbose}
Entity::Verbose	{enumValue}	: verboseValue
Entity::Terse	{enumValue}	: terseValue
Entity::Tag	{ enumValueList value }	: tag
Entity::EnumMax	{enumList}	: lengthList {terselength verboselength}

Specific Private Interface

Entity::BuildWhere	{ class arrtRef }	: whereStr
Entity::BuildOrder	{ class args }	: orderClause
Entity::GetTableList	{ class objref }	: tableList
Entity::SplitTables	{ class objref table }	: objList

This section will walk through the process of specifying the Building Service entity as the example. Each Entity file contains a namespace definition, an initialization function, the standard procedure instantiations, and the specialized procedure defintions. Definition of an entity requires the following steps:

Create the underlying database tables with the required attributes. This goes beyond the scope of this paper but the table constructor code for the examples are here for those interested:
Define the Entity namespace with the directives and the attributes and their properties.
Specify the set of standard procedures by applying the constructors.
Specify the Initialization function
Specify any specialized procedure definitions

Definition of the Namespace

A namespace definition contains a definition of directives, attributes and their properties, and entity initializations. While an entity can map to several database tables, each namespace should map to a single table. A namespace definition can then pull in other namespaces for a multiple table mapping. Definition of a namespace requires the following steps:

Define a namespace
The convention is to begin the Entity name with a capital letter. It does not have to be the same name as the underlying Table that the namespace represents. The convention in the example is to use the same name.
Initialize any immediate base classes, contained classes, or referred to classes
Set the Directives
Import Base class and refers to class attributes
Define the attributes and their properties

Entity Initializations

Initialize any immediate base classes or contained classes. Entity Initialization for BuildingService are as follows:

namespace eval BuildingService {
   variable this
   variable attr
   cariable oid
   variable dt
   variable buildingLocation

   # Insure the base class is initialized
   ServiceInit

   #Insure the refers to class is initialized
        #The refers to class is initialized in Service according to the model

   #Insure the contained class is Initialized
         #There are no contained classes
   .
   .
   .   
}

Directives

Each namespace contains certain required directives in a this array. These directives define the relationships of the entity to other entities and to the underlying database table or tables. Each directive will be described.

The directives provide a mapping from the entity to one or more database tables. An Entity can map to a single database table or to several database tables with the case of inheritance or other relationships. The following relationships can be encapsulated with an entity

Inheritance
Containment
Reference

this(from): This directive contains the from clause for doing a SQL select join, (read-only access to the tables). Each table in an inheritance or reference relationship must be specified here. It is important to specify aliases for each table. The aliases for any base table must match the alias given in that base entity definition. All aliases must be unique with a given namespace defintion (eg. the base alias is different from the derived alias). Specify the base table followed by their derivatives in the derived order by a comma separated list. The order is important. If a table stands alone, it just has a table name and alias. The most derived entity is the one being specified here. This clause must contain each table in the entire inheritance hierarchy, not just the immediate base table.
this(table): This directive contains the table name and an alias. If this entity stands alone (no base class), this is identical to this(from). An alias must be provided.
this(class): This contains the name of the namespace.
this(containedClass): This directive specifies a Tcl list (space separated) of contained classes. Specify the most derived entity name for each contained entity. If no entities are contained, set to {}.
this(where): This contains the join constraint portion of a SQL where clause. There must be one constraint for each table joined. For three tables, (aliases a, b, c) the join constraint would look somethig like "a.oid=b.oid and b.oid=c.oid" If this entity stands alone, set to {}.
this(hierarchy): This is a Tcl list of class names of the inheritance hierarchy starting with the base Entity and ending with the most derived Entity (the one being defined here). The order is important since this will affect the order that tables are written. Note also, that this directive specifies write access to the table. This may differ from the this(from) directive when static tables (read-only) are part of an object. If a table is not to be written to it must not be specified here. If the Entity is a stand-alone, set to this(class)
this(dbObject): This specifies the DbObject class to use. An entity can be initialized with the database interface. The Sybase DbObject is the default.
this(inst): This specifies the connection instance to use. The connection to the database is gotten external to the entity and must be given on entity initialization. The default is 1.

An example of the directives for BuildingService is as follows:

namespace eval BuildingService {
   .
   .
   .
   #The directives
   #This is a derived class so a join is needed with the base class and any refers to classes
   #The from clause specifies the tables and aliases to be read in order from base to derived
   #Table specifies the derived table name and alias
   #Class specifies the namespace
   #Where specifies the join constraint
   #Hierarchy specifies the order of the tables to be written from base to derived

   set this(from) "ManagedObj m, Service s, ServiceDescription sd, BuildingService bs"
   set this(table) "BuildingService bs"
   set this(class) BuildingService
   set this(containedClass) {}
   set this(container) {ManagedObj}
   set this(where) "m.oid = s.managedObjOid and s.serviceDescriptionOid = sd.oid and bs.serviceOid = s.managedObjOid"
   set this(hierarchy) [list ManagedObj Service $this(class)]
   .
   .
   .
}

Import Base Class Attributes

Base class attributes must be imported before defining the derived class attributes. They are imported using the standard interface procedure, GetAttribute. The base class for BuildingService is Service as follows:

namespace eval BuildingService {
   .
   .
   .
   #Import the Base class attributes
   array set attr [Service::GetAttribute]
   .
   .
   .
}

Attributes

There are required attributes for different situations which are sumarized as follows

oid (object id)

Every Entity needs an oid to uniquely identify it in the database. It is generated by the database as an identity column. If using it in an inheritance, the identity is found in the base class table. It must have key, type, column, table, defWidth, label, and default properties
coid (container object id)

This attribute specifies the container oid. it is only needed in an entity that is contained by another entity. It must have type, column, table, defWidth, label, and default properties
mdt (most derived type)

This attribute is required in any parent base class of an inheritance hierarchy. The attribute, mdt, must be specified for any class that is to be manipulated polymorphically. It does not need to be specified in the most derived entity. It must have type, column, table, defWidth, label, and default properties
dt

This attribute is required in every class of the inheritance hierarchy. It must have type, column, table, defWidth, label, and default properties

All attributes must map one-to-one to the columns of the table. The column names do not have to match the attribute names.

Attribute Properties

key

This property is only used on the oid attribute. It can take one of two values; Primary or Foreign. If the oid directly represents an identity column in the database such as for a root base class or a standalone class, set to Primary. Otherwise, set to Foreign.
type
This property defines the type of attribute. Each attribute in an entity has a certain type; Integer, Text, EnumInt, EnumText, Datetime, Binary
- Integer - this is used for any numerical column in the database such as a int, tinyint, smallint or numeric that represents a number. It is used for oid and coid.
- EnumInt - This also maps to a numerical column in the database where each number represents an enumeration defined with an enum property.
- Text - This is used for any string that maps to a database column of char(x) or varchar.
- EnumText - This is used for any single character , char(1), that represents an enumeration defined with an enum property.
- Datetime - This maps to a database column such as datetime or smalldatetime.
- Binary - This maps to a database column, binary, and is represented as a hex value.
column

This property is a string that takes the form of alias.columnName. It maps the column to the entity attribute.
table

This property is a string that matches the namespace name and the tablename. It maps the attribute with the table in the database.
enum
This property list all of the possible enumerations for the attribute. It takes the form of a tcl list of tag-value pairs. The tags are the handles to the enumerations that are to be hardcoded in the code. The values contain both a terse and verbose value of the form {terse: Verbose} for the enumeration. It is to be specified as
```
set attribute(enum) {tag value tag value ...} 
```
defWidth
This property is used by view management for knowing the bounds of the attribute. It is an integer that corresponds with the maximum size of the column in the database. If the attribut is of type EnumInt or EnumText, set the size by the following procedure:
```
set attribute(defWidth) [Entity::EnumMax $attribute(enum)]
```
label

This property is used by view management to prompt a user with a prototype or with acceptable values to use.
default

This contains the default value for the attribute.

An example of the attributes and properties for BuildingService is defined as follows:

namespace eval buildingService {
   .
   .
   .
   #Specify the derive class attributes
   #oid
   lappend this(attrs) oid
   set oid(type) Integer
   set oid(key) Foreign
   set oid(column) {bs.serviceOid)
   set oid(table) $this(class)
   set oid(defWidth) 9
   set oid(label) {}
   set oid(default) {}
   set attr(oid) [array get oid]
   #dt
   lappend this(attrs) dt
   set dt(type) Text
   set dt(column) {bs.dt}
   set dt(table) $this(class)
   set dt(label) {(a,A - z,Z); 24 characters max}
   set dt(defWidth) 24
   set dt(default) {}
   set attr(dt) [array get dt]
   #buildingLocation
   lappend this(attrs) buildingLocation
   set buildingLocation(type) Text
   set buildingLocation(table) $this(class)
   set buildingLocation(label) {(a,A - z,Z); 50 characters max}
   set buildingLocation(defWidth) 50
   set buildingLocation(column) {bs.buildingLocation}
   set buildingLocation(default) {}
   set attr(buildingLocation) [array get buildingLocation]
     #Import base class attr list
   set this(attrs) [union $this(attrs) $Service::this(attrs)]
}

This is the Entity namespace specification. Notice the easy mapping from the information in the object model. This is a candidate for automatic code generation.

Standard Procedure Constructors

The standard set of constructors are specified in the form

<standard procedure constructor> <newEntity::this(class)>

These are intialized outside the namepace definition.

      //Always Specify
EntityCreate $MyEntity::this(class)
EntityQuery $MyEntity::this(class)
EntityNext $MyEntity::this(class)
EntityRefresh $MyEntity::this(class)
EntityGetAttribute $MyEntity::this(class)
EntityGetListOf $MyEntity::this(class)
EntityRetrieve $MyEntity::this(class)
EntityMdtRetrieve $MyEntity::this(class)
EntityRetrieveOidBy $MyEntity::this(class)
EntityRetrieveObjBy $MyEntity::this(class)
EntityArrayCopy $MyEntity::this(class)
EntityCount $MyEntity::this(class)

      //Optional
EntityInsert $MyEntity::this(class)
EntityInsertUpdate $MyEntity::this(class)
EntityUpdate $MyEntity::this(class)
EntityUpdateWhere $MyEntity::this(class)
EntityDelete $MyEntity::this(class)
EntityDeleteWhere $MyEntity::this(class)
EntityContainedList $MyEntity::this(class)
EntityContainer $MyEntity::this(class)
EntityValue $MyEntity::this(class)

The behavior of an entity can be controlled by selective specification. Overriding the standard behavior is done by not specifying the constructor and redefining the standard procedure within this file. The following rules apply for different entities.

Persistent Abstract Base class - Remove the EntityInsert.
Read-only Entity - Remove the EntityInsert, EntityUpdate, EntityDelete, and perhaps EntityValue.
A non-contained entity - Remove EntityContainedList.

Initialization Procedure

The namespace is loaded by the following initialization function. Invocation of this function causes the Tcl interpreter to load the namespace. It also allows the entity to be initialized with a different DbObject and connection instance.

proc BuildingServiceInit { {db DbObject} {connection 1} } {
   set BuildingService::this(dbObject) $db
   set BuildingService::this(inst) $connection
}

Virtual Procedure definition

Occasionally it is neccesary to override the standard interface procedure with one that enforces specific business rules. I provide an example of theServiceInsert override to implement the automatic linkage with the ServiceDescription instance. This example also serves to show how the standard interface is used within a program

proc BuildingService::Insert {objref} {
   upvar $objref obj
   variable this

   #Test if ServiceDescriptionOid or serviceName are provided and valid
   if {[ string match $obj(serviceDescriptionOid) {} ]} {
      #See if serviceName was provided
      if {[ string match $obj(serviceName) {} ]} {
         error "BuildingService::Insert failed.  Object reference doesn't contain a ServiceDescriptionOid or serviceName."
   } else {
      #validate serviceName and obtain ServiceDescriptionOid
      set serviceOid [ServiceDecription::RetrieveOidBy serviceName $obj(serviceName)]
      if {[ string match $serviceOid {} ]} {
         error "BuildingService::Insert failed.  The provided serviceName, $obj(serviceName), is not valid"
      } else {
         set obj(serviceDescriptionOid) $serviceOid
      }
   } else {
      #validate the serviceDescriptionOid
      if { ![ServiceDescription::Count * oid $obj(serviceDescriptionOid)] } {
         error "BuildingService::Insert failed.  The provided serviceDescriptionOid is not valid."
      }
   }
   #Insert into Database
   return [Entity::Insert $this(class) obj]
}