Remarks

This method tries to instantiate an object instance and returns the object pointer if successful, or the .Null. value instead.

For not persistent or mapped classes, this method behaves exactly like the CreateObject() native Visual FoxPro Function.

For persistent classes this method enhance the native CreateObject() function by performing additional steps like:

• If the first attempt to create an object instance fails, the persistence engine tries to locate the class definition record on the active mapping schema, tries to open the class library file indicated in the mapping schema and retries the object instantiation process.

• The object instance is then labeled, it is: an Object_ID string is assigned and a small structure is attached to the object for persistence tracking.

• The OnCreate event procedure (if coded on the class), is triggered, allowing the object to execute custom  pre-initialization code.

• Then, the persistence engine initializes references and collections on the object according to the mapping information.

  • For single references, the persistence engine will create and initialize the referenced objects for those single references marked as mandatory (for a complete explanation on mandatory references please check the documentation and the Schema Manager Mapping Tool Guide)

  • For collection references, if needed, the persistence engine will create the proper collection object according to the collection class indicated in the mapping schema.

• The AfterCreated event procedure (if coded on the class), is triggered, allowing the object to execute custom post-initialization code.

The use of the Session.CreateObject method instead of the native CreateObject() function is encouraged  because your business objects are labeled and linked to the Session object right after they are created, allowing them to access all the persistence services at any time.  Moreover, using class events like OnCreate, AfterCreated, OnRetrieve, AfterRetrieved, etc. on your business classes, simplifies all your class code whenever your business objects are created or retrieved from the database providing a powerful and robust "framework" for your business classes.

For a complete reference on persistent class events, please see this reference index.

See Also