Washington, September 15-18, 1999 – London, November 21-24, 1999

A reference guide to POM Objects, Methods and Properties

Ash Rofail

ApolloPOMLib

Main library of POM objects. Contains the developer-interface objects for instantiating POM objects for use in programs. Contains the classes that hold the meta-data describing any object persisted in the POM.

CApolloPOM

The highest level peristent object manager class, contains methods for creating individual persistent objects, as well as lists and collections of persistent objects.

CPOMMetaData

Contains the complete meta-data description of a persistent object. Most of the services this class provides are used by CPOMObject to pass CRUD requests from the object layer on to the database layer.

CMembers

Collection of objects that implement IObjectMember, each decsribing the type and encapsulating the behavior for an indivual object member.

IObjectMember

An individual object member, in a sense a property, that represents a single piece of information about the object that get persisted by the POM. Each object member of an object, if it is to be persisted, is represented in the POM as an object member. Individual member types each have their own implementation, and each implement this interface. While IObjectMember provides services common to all member types, the implementation of the interface provides behaviors specific to the member type.

CPOMObject

The class that must be contained by any object that wishes to be persisted with the POM. Provides generic services for communicating with the lower layers of the POM to persist data  members, while providing a structure to provide different objects with their own behaviors. Also has a number of events that are raised from the lower level of the POM that can be captured at this level to further customize the behavior of a POM object.

CValues

The values for a given instance of a POM object.

CPOMList

Provides mechanism for creating a 'shallow' list of 'proxy' information about objects selected dynamically with user or developer provided criteria. Provides cursor services for scanning or displaying large amounts of specific object data, and provides services to create fully instantiated instances of specific objects in the list, or transform this 'shallow' list into a fully instantiated collection of objects.

CPOMCollection

A fully instantiated collection of POM objects, creating by dynamic user of developer provided criteria applied to the object's members. Provides methods for doing CRUD operations in batch on the object collection, as well as creation of detail objects that are in relation to the objects in the collection.

CDBLib

Abstract database services  layer. Provides the interface that may be implemented for any persistence device and technology. Also provides simple objects for representing and passing meta-data information, and providing selection criteria in a persistence device independent manner.

IDatabase

The interface that must be implemented to persist object data with a specific technology, to a specific device.

CCondition

A class for describing a specific condtion with name/operator/value properties. Also describes the conditions operational relationship to its context.

CPOMSQLColumns

A collection of POMSQLColumn objects. Also tracks the number of tables referenced by the column collection, their names, and relationships.

CPOMSQLColumn

A class for describing the mapping between an object member and a schema entity attribute.

CDBADO

CPOMADOSQL

An implementation of the IDatabase interface for persisting data to SQL Server with ADO.

Future Objects

CMemberViewLib

MemberView

Services for creating and using member views.

CUILib

UserViewServices

Provides CRUD operations for user view definitions. Returns lists of views, lists of views for certain objects, lists of object members that make up a given view, IDs for string lookups, and other things TBD.

CSmartListLib

The classes that manage object members of type 'SmartList'.

POMSmartList

Provides services in support of member type 'List' (MemberList implementation of IObjectMember) for maintaining and managing smart lists, the composition of the list items, the display values and columns, and the data to be persisted, as well as enforcing smart list rules.

CApolloPOM

ApolloPOM provides services for retrieving meta-data and instantiating object instances for objects defined in the POM meta-data.

Methods

public CreatePOMMetaData(ByVal sClassName as String,  ByVal sMemberViewName as String = "")

  as CPOMMetaData

CreatePOMMetaData returns an instance of the POMMetaData object. The class object contains the complete meta-data definition of a POM Object.

public CreatePOMObjects(ByVal sClassName as String,

  Optional ByVal sMemberViewName as String = "",

  Optional ByVal colConditions as CConditions = Nothing,

  Optional ByVal colSortOrder as Collection = Nothing)

  as POMCollection

CreatePOMObjects returns a POMCollection object, which is a collection of some class that contain POMObject. Which POM objects are included is determined by the parameters passed.

public CreatePOMObjectList (ByVal sClassName as string,

ByVal bFetchAsync as Boolean,

Optional ByVal sMemberViewName as String = "",

Optional ByVal colConditions as CConditions = Nothing,

Optional ByVal colSortOrder as Collection = Nothing)

as POMList     

CreatePOMObjectList returns an object of type POMList. The objects represented in the list are dependent upon the parameters passed.

public CreatePOMObject (ByVal sClassName as String,

Optional ByVal objOID as OIDObject = Nothing,

Optional ByVal sMemberViewName as String = "")

as Object     

CreatePOMObject returns a single instantiated object, of some class that contains an instance of CPOMObject. If OID is missing or zero, creates new object.

Design Details

CApolloPOM.CreatePOMObject (ByVal sClassName as String,

     Optional  ByVal objOID as OIDObject = Nothing,

  Optional ByVal sMemberViewName as String = "")

  as Object

CreatePOMObject returns a single instantiated object, of some class that contains an instance of CPOMObject.

A new POMMetaData object is created. This object is is set to the return value of ApolloPOM.CreatePOMMetaData. The value of this method is then set to the return value of POMMetaData.retreivePOMObject, passing the OID.

CApolloPOM.CreatePOMMetaData (ByVal sClassName as String,

   ByVal sMemberViewName as String)

   as POMMetaData

CreatePOMMetaData returns an instance of the POMMetaData object. The class object contains the complete meta-data definition of a POM Object.

A new POMMetaData object is created. POMMetaData.DB.retrieveMetaObject is called. POMMetaObjectName is passed as 'POMObject'. The row returned is passed to POMMetaData.InitMetaData. A MemberView object is used to create a CodingName collection. If sMemberViewName was not passed, "All" is passed as the member view name. The new POMMetaData object has a Members object. The RetrieveObject method of that object is called, passing the POMObjectID property of POMMetaData and the CodingName collection as parameters.

CApolloPOM.CreatePOMObjects (ByVal sClassName as String ,

Optional ByVal sMemberViewName as String = "",

Optional ByVal colConditions as CConditions = Nothing,

Optional ByVal colSortOrder as Collection = Nothing)

as POMCollection

CreatePOMObjects returns a POMCollection object, which is a collection of some class that contains an instance of CPOMObject. Which POM objects are included is determined by the parameters passed.

Declares and creates a new POMCollection object. Declares a local POMMetaData variable. Assigns this varialbe the retrun value of a call to CreatePOMMetaData, passing the ClassName and MemberViewName as parameters. Sets POMMetaData variable to returned object. Declares local ADO recordset. Sets recordset to return value of call to POMMetaData.retrievePOMObjectList, passing ClassName, OID only parameter as true, Conditions, and SortOrder. Declares local object variable. Iterates through recordset, calling POMMetaData.retrievePOMObject for each row, passing OID column of recordset. Adds the returned object to the collection using POMCollection.Add. At end of recordset, returns POMCollection.

CApolloPom.CreatePOMObjectList (ByVal sClassName as string,

Optional ByVal sMemberViewName as String = "",  

Optional ByVal colConditions as CConditions = Nothing,

Optional ByVal colSortOrder as Collection = Nothing)

as POMList

CreatePOMObjectList returns an object of type POMList. The objects represented in the list are dependent upon the parameters passed.

Declares local POMMetaData object. Assigns this variable to the return value of ApolloPOM.CreatePOMMetaData, passing ClassName as parameter. Declares and creates POMList  and sets POMMetaData variable of this POMList to this locally created variable. Calls POMList.InitPOMList, passing MemberViewName, Conditions, and SortOrder as parameters. Sets return value to POMList object. Sets POMList.POMObject to return of new CreatePOMObject.

CPOMObject

The CPOMObject interface must be contained by any class that wishes to be persisted by the POM. A default implementation of this containment will be provided on the 'Add Class' dialog window in the VB IDE.

Properties

let/get Name as String

The name of the object as stored in the object table.

set/get ID as ObjectID

The object containing the OID of this object instance.

set/get ObjectMetaData as POMMetaData With Events

This is a reference to an object that holds the entire meta-data definition of the object. This instance of the meta-data object is declared with its events, so all of those become available in objects implementing this interface.

get Values as Values

An object managing the recordset that stores the object instance's persistent data. The recordset fields are keyed off the 'CodingName' value of the object member and is retrieved by the default property RetrunProp. Therefore, a developer can retrieve and set its value with the syntax:

objref!CodingName

get/set Errors as ErrorItems

Reference to the POMMetaData's instance of the error handler object.

get IsNewObject as Boolean

Property that denotes the object instance is newly created, but has not been updated.

get IsDirty as Boolean

Denotes whether or not there have been any edits to the values of this object. As property changes, raises DirtyChange event.

get IsDeletedas Boolean

Denotes whether or not this object has been deleted from persistent storage. If it was, edits and updates are no longer allowed.

Methods

public Update

Be sure IsDeleted is false. Writes any changes made to the object out to the persistence device. Possible to trap raised events Before and After/ Create or Update from lower levels of call (POMMetaData).

public Delete

Be sure IsDeleted is false. Removes the object from the persistence device. Sets IsDeleted property to true. Possible to trap raised events BeforeDelete and AfterDelete from lower levels of call (POMMetaData).

public Refresh

Be sure IsDeleted and IsNewObject are false. Reads persistence data from the persistence device. Any changes not commited with Update will be lost upon calling this method.

public ReturnProp (ByVal sCodingName as String) as Variant

Default method that returns the value of one the Object members, retrieved from values collection by using CodingName as key. Can also return reference to value for purposes of modifying. Returns reference to Value object's Value property (its default) by using Values collection's default method 'Item'. When used to set item the event ValueChange will be raised and can be trapped from POMMetaData.

public CreatePOMObjects (ByVal sClassName as String,   

Optional ByVal sMemberViewName as String = "",

Optional ByVal colConditions as CConditions = Nothing, 

Optional ByVal colSortOrder as Collection = Nothing)

as POMCollection

Returns a POMCollection object with detail objects corresponding to the object type passed. Additional criteria, a pre-defined view name, and sort order can also be specified.

public CreatePOMObjectList (ByVal sClassName as String,

ByVal bFetchAsync as Boolean,

Optional ByVal sMemberViewName as String = "",

Optional ByVal colConditions as CConditions = Nothing,

Optional ByVal colSortOrder as Collection = Nothing)

as POMList

Returns a POMList object with detail objects corresponding to the object type passed. Additional criteria, a pre-defined view name, and sort order can also be specified.

private Class_Initialize

Create the value collection and sets its parent equal to this object.

private Class_Terminate

Destroy the values collection.

public BeginTrans as Integer

BeginTrans starts a new transaction. It returns a Long variable indicating the nesting level of the transaction.

 

public CommitTrans as Integer

CommitTrans saves any changes and ends the current transaction.

 

public RollbackTrans as Integer

RollbackTrans cancels any changes made during the current transaction and ends the transaction.

Events

DirtyChange

Raised when the dirty flag of the object changes. Not raised each time a value is changed, only when IsDirty for entire object changes value.

This class also traps all events raised by POMMetaData and raises them on to business object clients.

COIDObject

Properties

Let/Get OID as Variant

Default property that holds value of an object instance's object ID.

Let/Get OIDType as OIDTypeEnum

Enum value of the type of the OID.

CValues

Properties

Let/Get Values as ADODB.Recordset

Recordset variable used to store the values for the object. Field names in the recordset correspond to each member's CodingName variable in the object Member collection. Get only friendly with POMList objects. All others must use ReturnProp method to access values.

Let/Get ParentObject as CPOMObject

A reference to the instance of the object that these values are being persisted for.

Let/Get Count as Long

A count of the number of member values stored in the recordset.

Methods

public ReturnProp (ByVal CodingName as String) as Variant

Default method that returns the mRecordset value from field named CodingName.

private Class_Initialize

Create new recordset object. Local recordset variable to internally store Values is declared with class scope using WithEvents keyword.

private Class_Terminate

Destroy recordset object.

This class will also raise trap the recordset events WillChangeFields and FieldChangeComplete.

Design Details

The recordset field names will correspond to member CodingNames. Use CodingName as link between member objects and fields in the values recordset.

When WillChangeField is raised, raise BeforeValueChange of the POMMetaData parent object for all members listed in Fields parameter passed to the event. If Cancel comes back from any of these events True, set the status of WillChangeField to adStatusCancel.

When FieldChangeComplete is raised, raise AfterValueChange for the POMMetaData parent for all members listed in Fields parameter passed to the event.

 

Design Details

CPOMObject.Update

Writes all persistent members out to the persistence device.

Calls the savePOMObject method of its POMMetaData reference, passing itself as a parameter. If the function returns true, the IsNewObject flag is set to false, otherwise the ErrorItems collection of this object's meta data reference is examined and the errors dealt with.

CPOMObject.Delete    

Removes object information from persistence device.

Calls POMMetaData.DeletePOMObject with this object's name and OID. If this call succeeds, IsDeleted flag is set to true.

CPOMObject.Refresh   

Reloads persistent data for object from persistent storage device. All changes to said data are lost on refresh.

Creates collection of coding names present. Calls POMMetaData.DB.retreiveObject to retrieve a row with values for said collection. Iterates through the row returned, assigning values from row to values, keying from coding name.

CPOMObject.CreateOMObjects (ByVal sClassName as String  ,

Optional ByVal sMemberViewName as String = "",  

Optional ByVal colConditions as CConditions = Nothing, 

Optional ByVal colSortOrder as Collection = Nothing)

as POMCollection

Returns a POMCollection object with detail objects corresponding to the object type passed. Additional criteria, a pre-defined view name, and sort order can also be specified.

Finds the CodingName of the request object's member where ParentObjectID is equal to this object's ID. Creates condition where that CodingName member of the requested object has a value equal to this object's particular instance OID. Appends that condition to the Condition collection. Sets Parent equal to Me. Passes everything along to ApolloPOM.CreatePOMObjects and returns the POMCollection it returns.

CPOMObject.CreatePOMObjectList (ByVal sClassName as String,

ByVal bFetchAsync as Boolean,

Optional ByVal sMemberViewName as String = "",

Optional ByVal colConditions as CConditions = Nothing,

Optional ByVal colSortOrder as Collection = Nothing) as POMList

Returns a POMList object with detail objects corresponding to the object type passed. Additional criteria, a pre-defined view name, and sort order can also be specified.

Finds the CodingName of the request object's member where ParentObjectID is equal to this object's ID. Creates condition where that CodingName member of the requested object has a value equal to this object's particular instance OID. Appends that condition to the Condition collection. Sets Parent equal to Me. Passes everything along to ApolloPOM.CreatePOMObjectList and returns the POMList it returns.

CPOMMetaData

Contains the complete meta-data description of a persistent object. Most of the services this class provides are used by CPOMObject to pass CRUD requests from the object layer on to the database layer.

Properties

get/let POMObjectID as Long

Stores the ID that identifies the POM object in the persistent meta-data. Persisted as POMObject.ObjectID.

get/let POMObjectName as String

The name of the peristent object definition. Persisted as POMObject.ObjectName.

get/let DB as IDatabase

A reference to an object that implements the IDatabase interface. Used for access to the persistent storage device.

get/let theMembers as Members

The object that manages the collection of member objects. Member objects store the attributes for any given object member.

get/let Errors as ErrorItems

A reference to an instance of the Apollo error handler, or logger, or what-not.

get/let IsWritable as Boolean

Boolean indicitive of whether or not this object can be modified.

get/let IsCreatable as Boolean

Boolean indicitive of whether or not new instances of this object can be created. Always false when IsWritable is false.

get/let ClassProgID as String

The ProgID of the class that contains an instance of CPOMObject for this persistent object. If no custom behaviors are needed for the persistent object, a default implementation is available.

Methods

public retrievePOMObject (ByVal objOID as OIDObject) 

as Object

This method retrieves persistent data for the POMMetaData object for the OID passed. It returns a fully instantiated and populated instance of the object. If OID is 0, creates new object, if allowed. Creates object with members in MemberViewName definition, if provided, or coding name collection if not empty. If neither is provided, builds collection of all object member's coding names.

public InitMetaData (ByVal objRst as ADODB.Recordset)

This method sets the meta data properties that have been passed to it in the current row of the recordset.

private Class_Initialize

Creates  its database object. Creates its Errors object. Creates new Members object and assigns it to property theMembers and sets its parent to the meta-data object (Me). Sets its database to Me.DB.

private Class_Terminate

Destroys Members object. Destroys database object. Destroys errors object.

public savePOMObject (ByVal objPOMObject as CPOMObject) as Boolean

Does validation of object by evaluating the values collection. If valid, passes the recordset object of the Values object onto database layer for update of persistent info.

public CopyPOMObject (ByVal objFromOID as OIDObject) as Object

Creates a copy of the object the meta-data describes. Must be writable and creatable. Returns a reference to the new object if successful, otherwise returns NOTHING and the ErrorItems collection must be examined to see what went wrong.

public DeletePOMObject (ByVal sClassName as String,ByVal objOID as OIDObject) as Boolean

Removes the object from persistent storage. Returns true if it succeeds, otherwise returns false and the error object must be examined to determine what went wrong.

public retrievePOMObjectList(Optional ByVal bOIDOnly as Boolean = FALSE,Optional ByVal colConditions as CConditions = Nothing,

Optional ByVal colSortOrder as Collection = Nothing) as ADODB.Recordset

Returns an ADO recordset with CodingName titled fields and a row for each object that met the criteria described by the Conditions parameter.

public RaiseBeforeValueChange (ByVal sCodingName as String,

ByVal vntNewVal as Variant,

ByRef bCancel as Boolean)

Raises ValueChange event with parameters passed. Called by value object in values collection when value is changed.

public RaiseAfterValueChange (ByVal sCodingName as String)

Raises ValueChange event with parameters passed. Called by value object in values collection when value is changed.

Events

BeforeCreate (ByRef bCancel as Boolean)

Raised by savePOMObject before a new object is committed to persistent storage. Creation is cancelled if event parameter returns as true.

AfterCreate (ByVal objOID as OIDObject)

Raised by savePOMObject after changes are committed to persistent storage. Useful for retrieving the OID for newly created objects.

BeforeUpdate (ByRef bCancel as Boolean)

Raised by savePOMObject before changes are committed to persistent storage. Save is cancelled if event parameter returns as true.

 

AfterUpdate (ByVal objOID as OIDObject)

Raised by savePOMObject after changes to an existing object are committed to persistent storage.

BeforeDelete (ByRef bCancel as Boolean)

Raised by deletePOMObject before an object is permanately removed from persistent storage. Can be used to cancel the delete.

AfterDelete

Raised after an object is removed from persistent storage. Handy for updating UI.

BeforeValueChange (ByVal sCodingName as String,

ByVal vntNewVal as Variant,

ByRef bCancel as Boolean)

Raised whenever a value in the Values class is about to be altered. Can be used to cancel edit.

AfterValueChange (ByVal sCodingName as String)

Raised whenever a change to a value has occurred in the Values class.

Design Details

CPOMMetaData.retrievePOMObject (ByVal objOID as OIDObject)

as Object

This method retrieves persistent data for the POMMetaData object for the OID passed. It returns a fully instantiated and populated instance of the object.

Creates local instance of  POMMetaData.ObjectProgID. Sets object POMMetaDataID to this object's POMObjectID. Sets POMMetaData object to this object ('Me'). Uses Members collection to build collection of CodingName string. Calls CPOMADOSQL.retrieveObject, which returns a singe row ADO recordset. If OID is nothing calls each Member's defaultValue method. Assigns this recordset to the Values property of the Values object. If IsCreatable is true in the POMMetaData properties, then CPOMADOSQL.CheckRequiredMembers is called, passing CodingName collection and FALSE for the AddMissing parameter. The IsCreatable property is set to the return value of this method. The method returns a reference to this object it has created.

CPOMMetaData.InitMetaData (ByVal objRst as ADODB.Recordset)

This method sets the meta data properties that have been passed to it in objRst.

Properties set include POMObjectID, POMObjectName, IsWritable, IsCreatable and ClassProgID.

 

CPOMMetaData.savePOMObject (ByRef objPOMObject as Object) as Boolean

Does validation of object by evaluating the values collection. If valid, passes recordset of values object onto database layer for update of persistent info.

Checks to be sure object is writable. Checks to be sure if object is new that it's creatable. Iterates through Values.mRst, making sure all required members are populated. Calls the IsValid method of each of the value's object member. If any errors occur during these checks, the method exits. Otherwise, if IsNew is true, BeforeCreate event is raised. Otherwise, BeforeUpdate is raised. If Cancel is false when the event returns, theObject.Values is passed to CPOMADOSQL.saveObject, along with the OID of this object. If no errors are raised by this method, then if IsNew is true, AfterCreate event is raised and theObject.OID is assigned the OID returned from the database. If IsNew isn't true the AfterUpdate event is raised. The IsNewObject flag is set to false, the IsDirty flags of the value objects in the values collection are set to false. The method returns true. If there was an error, the method returns false and the errors collection must be checked by the caller.

CPOMMetaData.retrievePOMObjectList (Optional ByVal sMemberViewName as String = "",

Optional ByVal colConditions as CConditions = Nothing,

Optional ByVal colSortOrder as Collection = Nothing)

as ADODB.Recordset

Calls CPOMADOSQL.retrieveObjectList, passing its own class name and the other parameters that have been passed to it, with the exception of MemberViewName, which it transforms into a collection of CodingName strings. Returns the recordset returned by retrieveObjectList.

CPOMMetaData.deletePOMObject (ByVal sClassName as String,

ByVal objOID as Object)

as Boolean

Removes persistent information about the object described in the parameters from persistent storage.

Raises the BeforeDelete event. If Canel is false, function then calls CPOMADOSQL.deleteObject and passes object name and OID along. If this function returns true, the AfterDelete event is raised. Returns a boolean indicitive of a successful delete.

CPOMMetaData.CopyPOMObject (ByVal objFromOID as OIDObject) as Object

CMembers

Properties

Let/Get DB as IDatabase

A reference to the object implementing IDatabase for persistence device access. Set by parent to parent's.

Let/Get Parent as POMMetaData

A reference to the POMMetaData object that this class is managing members for.

Get Count as Long

The number of members in the collection.

private m_colCollection as Collection

A private collection of objects that implement IObjectMember.

Get Item(vntIndexKey as Variant) as IObjectMember

Returns the member from index or key in mCollection.

Methods

publicretrieveObject (lPOMObjectID as Long, colCodingNames as Collection)

This method creates the members collection by populating a member object for each coding name in the collection.

publicAdd( vntItem as variant, sCodingName as String)

Adds variant Item to the collection using CodingName as the key value.

private Class_Initialize

Creates m_colCollection object

private Class_Terminate

Destroys m_col Collection object.

IObjectMember

Properties

Let/GetID as ObjectID

The unique OID of this persisted object member.

Let/Get ParentID as Long

The unique OID of the parent object that this is a member of.

Set/GetParentObject as POMMetaData

A reference to the parent object that this is a member of.

Let/Get Name as String

The descriptive name of this object member.

Let/GetUIDisplayID as Long

The ID used for lookups in string tables to display a caption for this member.

Let/Get CodingName as String

The coding name used to refer the member by developers.

Let/Get MemberTypeID as Integer

The ID of this member type from OBJECT_MEMBER_TYPE.

 

Let/Get IsRequiredas Boolean

Boolean indicitive of whether or not population of this member is required.

Let/GetIsVisible as Boolean

Boolean indicitive of whether this is a public member or if it's included only for internal processing.

Let/GetIsEditable as Boolean

If this is false then this member's value is read-only.

Let/GetToolID as Long

The ID of the row in OBJECT_TOOLS describing the tool to use to work with this row.

Let/GetValidationToolID as Long

The ID of the row in OBJECT_TOOLS describing the tool to use to validate this row's data.

Methods

public getDefaultValue as Value

Creates and returns a Value object populated with the default value for this member.

public getNullValue as Value

Creates and returns a Value object populated with the appropriate form of null for this member type.

public IsValid (ByRef Value as Variant) as Boolean

Runs validation on member for specific member type and parameters.

public InitMetaData (ByVal objRow as ADODB.Recordset)

This method copies the fieldsin the row object passed to it into the individual attributes of the member object itself.

Design Details

CMembers.retrieveObject (ByVal POMObjectID as Long, Optional ByVal colCodingNames as Collection = Nothing)

This method creates the members collection by populating a member object for each coding name passed in the collection.

A condition collection is created. A condition is added specifying object ID equal to POMObjectID. A loop through each item of the MemberList is setup. If MemberList is missing, a collection of all members is used. For the first item, a condition is added where CodingName is equal to the member name at the current iteration. The operator is set to AND, and BeginGrouping is set to true. For all subsequent iterations up to the last, the same condition is specified with the operator set to OR. The last is the same, with EndGrouping set to true. These conditions are sent to CPOMADOSQL.retrieveMetaObject with the name of the object member table passed as the name of the view pulling together object member and object member type information. A recordset is returned. A loop through this resultset is setup. On each iteration, an object of type rst("IMemberProgID") is created. This object implements IMember. This object's parent is set to the members collection (me). The InitMetaData method of the member object is then called, passing the current ADO row. The IMember object is added to the members collection.

IObjectMember.InitMetaData (ByVal objRow as ADODB.Recordset)

This method copies the field valuesof the row object passed to it into the individual attributes of the member object itself.

First the IMember implementation of InitMetaData is called. Attributes set include mID from ObjectMemberId, UIDisplayID from same, CodingName, IMemberProgID, MemberTypeID, IsRequired, IsVisible, IsEditable, ToolID, and ValidationToolID. Other attributes are set by individual member types, depending on the type. These can include Length, DefaultValue, LowerBound, UpperBound, Decimals, ListId, ChildObjectID, Units, and Mask.

POMCollection

The POMCollection object is a collection of a given type of POM object. It supports any class that contains an instance of CPOMObject.  It supports batch updating and deletes, and individual objects can be instantiated directly from it.

Properties

get Count as Long

The number of objects in the collection.

get/set ObjectMetaData as POMMetaData

A reference to the meta-data object, defining the object's structure with POM meta-data.

private mCollection as Collection

The private collection variable used to store the objects in the POMCollection.

get IsDirty as Boolean

Returns TRUE if any object in the collection has been modified, otherwise returns false.

get IsEditable as Boolean

Returns a boolean indicitive of whether or not the objects in the collection can be modified.

private mProgID as String

The ProgID of the class containing an instance of CPOMObject in this collection.

get Item (vntIndexKey as Variant) as Object

Returns a reference to the object at the position in the collection passed as an index or to the object corresponding to the collection index of IndexKey is an integer, otherwise returns object corresponding to the key value passed.

set/get Parent as CPOMObject

The parent object if this is a collection of child objects.

Methods

public Update

The Update method will write all changes to objects in the POMCollection back to the persistence device. Update occurs in a transaction, so if any object can't be saved, no changes are made.

public Refresh

The Refresh method will re-read all persistenct data from the database for the objects in the collection. Any changes made to objects in the collection that havn't been commited will be lost with the refresh.

public Delete

Removes all objects in the collection from the persistent storage device. Occurs in a transaction.

public Add (ByVal vntItem as Variant) as Long

Inserts an object into the collection. Can optionally be inserted before or after an ordinal position in the collection, or another key value in the collection. Default is to add it to the end of the collection. Returns an index to the new object in the collection.

public Remove (vntIndexKey as Variant)

Removes an object from the collection. Index passed can be either ordinal position in array, or reference to object key. Object is removed from collection, but not from persistent storage.

POMList

The POMList object is a descriptive list of persistent objects. The list is a 'shallow' list, containing read-only data about a given set of business objects. The list maintains its own cursor to the list.

Properties

private mRst as ADODB.Recordset

A recordset used internally by the object to store the list. Assigned to the value of CPOMObject.Values

get/set ObjectMetaData as POMMetaData

A reference to the meta-data object defining the meta-data for the business objects in the list.

get/set POMObject as Object

The object that this is a list of.

get Count as Integer

Returns the number of business objects that are in the list.

get EOF as Boolean

Returns a boolean value indicitive of whether or not the cursor is beyond the end of the list or not.

get BOF as Boolean

Returns a boolean value indicitive of whether or not the cursor is in front of the beginning of the list or not.

get AbsPos as Integer

Returns the absolute position of the cursor within the list.

get MemberCount as Integer

Returns the number of fields in each row for the list of persistent objects.

Methods

public MoveFirst

Moves the cursor to the first item in the list.

public MoveLast

Moves the cursor to the last item in the list.

public MoveNext

Moves the cursor forward one position in the list.

public MovePrev

Moves the cursor back one position in the list. Returns false if the cursor has moved before the beginning of the list, otherwise returns true.

public InitPOMList (Optional ByVal colConditions as CConditions = Nothing,Optional ByVal colSortOrder as Collection = Nothing)

Uses the parameters passed to initialize its internal recordset.

public InitASyncPOMList (ByVal objPOMList as POMList,

ByVal lCacheSize as Long,

Optional ByVal colConditions as CConditions = Nothing,

Optional ByVal colSortOrder as Collection = Nothing)

Uses the parameters passed to initialize its internal recordset asynchronously.

public ReturnProp (ByVal CodingName as String) as Variant

Default Method of object. Returns the value at the cursors position for the property passed as a parameter.

public MemberName (ByVal iIndx as Integer) as String

Returns the name of the field corresponding to the index passed. Indexes are zero-based.

public MemberType (ByVal iIndx as Integer) as TBD

Returns the type of the field corresponding to the index passed. Index is zero-based.

public FieldSize (ByVal iIndx as Integer) as Integer

Returns the size of the field corresponding to the index passed. Indexes are zero-based.

public CreatePOMObject as Object

Instantiates the object at the list's current cursor position and returns the business object.

public CreatePOMObjects (Optional ByVal colConditions as CConditions = Nothing,Optional ByVal colCodingName as Collection = Nothing) as POMCollection

Returns a POMCOllection object with the same business objects that are currently in the POMList. A subset of the items currently in the list can be returned by specifying a subset of the coding names currently in the list or passing additional criteria.

public CreateChildPOMObjects(ByVal sClassName as String,Optional ByVal sMemberViewName as String = "",Optional ByVal colConditions as CConditions = Nothing, Optional ByVal colSortOrder as Collection = Nothing) as POMCollection

Returns a POMCollection of objects that are child objects of the object the cursor is currently pointed to. Additional criteria can be passed in conditions, and properties and sorts can be specified.

public CreateChildPOMObjectList (ByVal sClassName as String,

Optional ByVal sMemberViewName as String = "",

Optional ByVal colConditions as CConditions= Nothing,

Optional ByVal colSortOrder as Collection = Nothing)

as POMList

Returns a POMList of objects that are child objects of the object the cursor is currently pointed to. Additional criteria can be passed in conditions, and properties and sorts can be specified.

public RaiseListProgress (TBD)

Raises said event.

public RaiseListFetchComplete (TBD)

Raises said event.

Events

ListProgress (TBD)

Raised after a call to retrieveASycnhObjectList as progress is made retrieving the rows.

ListFetchComplete (TBD)

Raised when all rows have been retrieved after a call to retrieveASycnhObjectList.

Design Details

POMList.InitPOMList (Optional ByVal colConditions as CConditions = Nothing,Optional ByVal colSortOrder as Collection  = Nothing)

Uses the parameters passed to initialize its internal recordset.

Creates CodingName collection from by iterating through member collection. Calls CPOMADOSQL.retrieveObjectList, passing coding name collection, conditions, and sort order. Assigns its POMObject reference's recordset property the recordset returned.

POMList.InitASyncPOMList (ByVal objPOMList as POMList, ByVal lCacheSize as Long,Optional ByVal colConditions as CConditions = Nothing,Optional ByVal colSortOrder as Collection  = Nothing)

Uses the parameters passed to initialize its internal recordset.

Creates CodingName collection from by iterating through member collection. Calls CPOMADOSQL. retrieveASyncObjectList, passing itself, coding name collection, conditions, cache size, and sort order. Assigns its POMObject.Values to the recordset returned. RaiseListProgress and RaiseListFetchComplete calls  will be made by CPOMADOSQL and these events will be raised to client.

POMList.CreatePOMObject () as Object

Instantiates the object at the list's current cursor position and returns the business object.

Creates local object variable. Creates collection of code names for the fields in its recordset. Calls the retrievePOMObject of its local POMMetaData reference, passing OID of current position of recordset. Returns the object returned by this call.

POMList.CreatePOMObjects (Optional ByVal sMemberViewName as String = "", Optional ByVal colConditions as CConditions=Nothing) as POMCollection

Fully instantiates the objects in the list, returning them in a POMCollection object.

Declares and creates a new POMCollection object.  Sets POMCollection's Class variable to the POMList's reference. Declares local object variable. Iterates through private recordset, calling POMMetaData.retrievePOMObject for each row, passing OID column of recordset. Adds the returned object to the collection using POMCollection.Add. Returns POMCollection. Restores position of recordset.

Lists, when opened with a batch lock, could be mutable. How this will be implemented awaits the results of our concerrency, cursor, connection, and locking inquiries.

CPOMADOSQL

Properties

Let/Get MetaDataServer as String

The name of the server where the POM meta-data lives.

Let/Get PersistentObjectServer as String

The name of the server where the persisted object data lives.

private mMetaDataConn as CDBConnection

The connection to the meta-data server that the ApolloPOM is using.

private mPOConn as CDBConnection

The connection to the persisted object server that the ApolloPOM is using.

Methods

publicretrieveMetaObject  (ByVal sPOMMetaObjectName as String, Optional ByVal colConditions as CConditions = Nothing) as ADODB.Recordset

This method returns an ADO recordset, corresponding to all columns and rows in the physical entity POMMetaObjectName with Conditions limiting the rows returned.

publicretrieveObject  (ByVal objOID as OIDObject, ByVal sPOMObjectName as String, ByVal colCodingNames as Collection)as ADODB.Recordset

This method returns a single row recordset, where field names correspond to member's CodingNames and the values corresond to the objOID instance of the object.

publicretrieveObjectList (ByVal sPOMObjectName as String, ByVal colCodingNames as Collection, Optional ByVal colConditions as CConditions = Nothing, Optional ByVal colSortOrder as Collection = Nothing) as ADODB.Recordset

This method returns an ADO recordset that contains the persistent data for the set of objects described by the parameters passed to it. The field names for the recordset will match the CodingName of the object member whose data it holds.

publicsaveObject (ByVal sPOMObjectName as String, ByVal objOID as OIDObject, ByVal objRow as ADODB.Recordset) as Boolean

This method writes the row in the recordset passed to it out to the persistence storage device.

private Class_Initialize

Create new CDBConnections.

private Class_Terminate

Destroys connection objects.

private GetEntityColInfo (ByVal sPOMObjectName as String, ByVal sCodingName as String) as POMSQLColumn

Looks up object member for CodingName and creates a SQL column object with appropriate table and column names.

privateBuildPOMSQLColumns (ByVal sPOMObjectName as String, ByVal colCodingNames as Collection) as POMSQLColumns

colCodingNames is a collection of CodingNames from an object's members. This method returns a POMSQLColumns collection based on this collection of CodingNames. Iterates through them, passing their values to GetEntityColInfo, and adding the returned POMSQLColumn to the POMSQLColumns collection, returning that collection when it's done.

private GenSelect (ByVal sPOMObjectName as String, Optional ByVal colCodingNames as Collection = Nothing, Optional ByVal colConditions as CConditions = Nothing, Optional ByVal colSortOrder as Collection = Nothing) as String

Creates three POMSQLColumns objects. One for SELECT portion, one for WHERE portion, and one for ORDER BY clause. Once the three collections are built, iterates through each of them to build the SQL statement. Returns the string once it's generated.

publicGetChildCodingName (ByVal objOID as OIDObject, ByVal sChildObjectName as String) as String

Returns member's coding name where ParentObjectID is equal to ObjectId and the same object's name is equal to the child object name.

publicCheckRequiredMembers (ByVal sPOMObjectName as String, ByRef colCodingNames as Collection, ByVal bAddMissing as Boolean) as Boolean

Function will check if all the required members for the object are included in the coding name collection. If they are all present method returns true. If they're not, and AddMissing is false, method returns false. If some are missing and AddMissing is true, the missing members are added to the collection with the CodingName as a key, and the method returns true.

public BeginTrans as Integer

BeginTrans starts a new transaction. It returns a Long variable indicating the nesting level of the transaction.

 

public CommitTrans as Integer

CommitTrans saves any changes and ends the current transaction.

 

public RollbackTrans as Integer

RollbackTrans cancels any changes made during the current transaction and ends the transaction.

Events

ListProgress (TBD)

Raised after a call to retrieveASycnhObjectList as progress is made retrieving the rows.

ListFetchComplete (TBD)

Raised when all rows have been retrieved after a call to retrieveASycnhObjectList.

POMSQLColumns

Properties

private mCollection as Collection

Collection of POMSQLColumn objects keyed on CodingName.

private mTables as Collection

Collection of table names keyed from coding names.

Get Table (sCodingName as String) as String

Returns the table name from the mCollection item that has the CodingName parameter as its key.

Get TableCount as Long

A count of the number of elements in mTables.

Get Item(ByVal vntIndexKey as Variant) as POMSQLColumn

Returns the SQL column from position IndexKey in mCollection if IndexKey is an integer, otherwise returns object with IndexKey key value.

Get Count  as  Long

The number of members in the collection.

Methods

publicAdd (ByVal objItem as POMSQLColumn)

Adds a POMSQLColumn item to the value collection. Uses CodingName from object as collection key. Also checks if TableName is already in mTables collection and adds it if it's not.

publicRemove (ByVal vntItemKey as Variant) as boolean

Removes value from collection. Uses index position if ItemKey is an integer, otherwise it uses collection key.

POMSQLColumn

Properties

Let/Get EntityName as String

The name of the physical table this object member perisists in.

Let/Get AttributeName as String

The name of the physical table column this object member persists in.

 

Let/Get CodingName as String

The CodingName property of this object member.

Let/Get SQLFormat as String

Either Name, Date, or Number, denoting proper format.

IPOMCondition

Abstract class used by the POM to construct WHERE clauses of SQL statements. How various implementations come up with their statements is up to them, they need only return a SQL snippet to the POM.

Methods

public SQLSnippet as String

Method that returns to the caller  the appropriate SQL statement based upon its implementation and current values.

CCondition Implements IPOMCondition

Properties

Let/GetName as String

A CodingName value from an object member. Name of member condition applies to.

Let/GetValue as Variant

The content of the criteria that's to be applied to the Named member.

Let/GetOperator as String

The operator to be used for comparison of name and value. Must be a valid opertator type for the Named member's type.

Let/Get LeadingOperator as String

Denotes what operator this condition uses to relate to the previous operator. Meaningless if condtition is first object in collection of conditions. In subsequent positions, is either an 'AND' or an 'OR', denoting the relationship to the previous condition.

Let/GetBeginGroupingCardinality as Boolean

Denotes number of leading parenthesis to place before this condition.

Let/GetEndGroupingCardinality as Boolean

Denotes number of closing parensthesis to place after this condition.

Let/Get Negative as Boolean

True indicates condition should be proceeded by a 'NOT'.

Design Details

CPOMADOSQL.retrieveObject  (ByVal objOID as OIDObject, ByVal sPOMObjectName as String, ByVal colCodingNames as Collection) as ADODB.Recordset

This method returns a single row recordset, each with a member's CodingName/Value pair. The collection is keyed on CodingName.

Builds a condition collection with a single condition, where ID is equal to the object ID passed as a parameter. If OID is nothing, creates condition where OID = 0. It then calls CPOMADOSQL.retrieveObjectList. The row returned in the ADO recordset is returned to the calling function. If OID is nothing, recordset will be empty. If this is the case, calls AddNew of recordset to create an empty row for a new object. If OID is not nothing and the recorset is empty, an error is raised.

CPOMADOSQL.retrieveObjectList  (ByVal sPOMObjectName as String, ByVal colCodingNames as Collection, Optional ByVal colConditions as CConditions = Nothing, Optional ByVal colSortOrder as Collection = Nothing) as ADODB.Recordset

This method returns an ADO recordset that contains the persistent data for the set of objects described by the parameters passed to it. The feild names for the recordset will match the CodingName of the object member whose data it holds.

Creates SQL statement by calling GenSelect and passing along all of its parameters.

This SQL statement is executed and the recordset is disconnected and returned.

CPOMADOSQL.retrieveASyncObjectList  (ByVal sPOMObjectName as String, ByVal colCodingNames as Collection, ByVal objPOMList as POMList,ByVal lCahceSize as Long,Optional ByVal colConditions as CConditions = Nothing, Optional ByVal colSortOrder as Collection = Nothing) as ADODB.Recordset

This method returns an ADO recordset that contains the persistent data for the set of objects described by the parameters passed to it. The field names for the recordset will match the CodingName of the object member whose data it holds.

Creates SQL statement by calling GenSelect and passing along all of its parameters. The cache size of the recordset is set to the parameter passed.

This SQL statement is executed with the adAsyncFetch option. The recordset is returned. The RaiseProgress and FetchComplete recordset events are trapped and raised to the oPOMList events. The FetchComplete disconnects the recordset.

CPOMADOSQL.genSelect  (ByVal sPOMObjectName as String, ByVal colCodingNames as Collection, Optional ByVal colConditions as CConditions = Nothing, Optional ByVal colSortOrder as Collection = Nothing) as ADODB.Recordset

Three instances of POMSQLColumns are created. Uses GetEntityColInfo method of object to add POMSQLColumn items to collection for each CodingName passed in coding name collection. After all names are added, OID is checked for. If it's not present it's added. After POMSQLColumns are created, POMSQLColumns will know how many entities are involved. The relationship between these entities must be determined. As these relationships are determined, criteria are added  to the Conditions to enforce these relationships in the resultset. If OUTER joins required, join syntax generated. Any criteria for entities is included. The SELECT portion of the SQL string is created by iterating through the POMSQLColumns collection. The FROM portion of the SQL string is created from the table list and the join syntax. The WHERE portion of the SQL string is created by iterating through the Conditions collection. The ORDER BY clause of the statement is created by iterating through the SortOrder collection.

CPOMADOSQL.retrieveMetaObject  (ByVal sPOMMetaObjectName as String, Optional ByVal colConditions as CConditions = Nothing) as ADODB.Recordset

This method returns an ADO recordset, corresponding to all columns and rows in the physical entity POMMetaObjectName with Conditions limiting the rows returned.

Builds a SQL statement selecting all rows from POMMetaObjectName and using conditions to construct a where clause. This statement is executed, the recordset is disconnected and returned.

CPOMADOSQL.saveObject (ByVal sPOMObjectName as String, ByVal objOID as OIDObject, ByVal objRst as ADODB.Recordset) as OIDObject

This method writes the values in the recordset passed to it out to the persistence storage device.

The recordset can be reconnected and Update called. There may be an option to create a new recordset and do the update with this. If this is the case the source of the recordset can be used to reopen it, and values assigned from the passed recordset to the new one. If OID is nothing, a new OID is generated with the UniqueID object. If there's more than one row in the recordset, UpdateBatch can be called and a new OID created for each row that's new. If all this works, the OID object is returned, otherwise NOTHING is returned.

CPOMADOSQL.deleteObject (sPOMObjectName as String, objOID as OIDObject) as Boolean

Removes object information from the database.

Builds collection of all coding names from object. Builds a POMSQLColumns collection. For each table in collection, builds and executes delete statement. Returns true if deletes are a success.

POM Meta-Data Persistence Schema

(With Development Connection String)