Property :: open - Create property handle

... fragment ( ObjectSpace &os, String extname ) {

Property ph;

ph.open(extname,Read); // does not throw an exception for invalid name

if ( ph.check(true) )

Error();

}

Return value: Property reference ( odaba::Property & )

A property handle refers to a (usually) opened property. Invalid properties may cause an exception.

Implementation overview

Create subordinated property handle
Property :: open ( cProperty, vAccessPath )
Create property handle for transient collection
Property :: open ( cObjectSpace, sExtentName, sKeyName )
Create copy property handle
Property :: open ( cProperty )
Open extent property handle
Property :: open ( cObjectSpace, vExtentPath, eAccessMode )
Create transient instance property
Property :: open ( cObjectSpace, sTypeName )
Create property handle for temporary or transient extent
Property :: open ( cObjectSpace, sTypeName, sKeyName, vBaseExtent, bWeakTyped, bOwner, bTransient )

Implementation details

Create subordinated property handle
odaba::Property & Property  :: open ( odaba::Property &cProperty, odaba::String &vAccessPath )

The function creates a subordinated property handle for the property handle passed in cProperty . The function behaves similar to property handles provided directly by calling property() , i.e. the property handle shares cursor and access mode with other property handles opened the same way.

In order to open a subordinated property handle, the parent property handle passed in cProperty must be opened and the access path in vAccessPath has to be a valid access or operation path.

For untyped or weak-typed parent property handles, the property handle returned depends on the current selection in the parent property handle, i.e. it may change, when another instance is selected in the parent property handle. In this case, the system automatically reopens the property handle.

As long as the access mode has not been changed for the child property it is opened with the access mode set for the parent property. The access mode can be changed later on by setting the accessMode() property, which implicitly changes teh access mode for all sharing property handles.

When the parent property is not valid or an invalid access path has been passed, the function throws an exception.

// fragment: Property person;

Property   children;

children.open(person,"children");           // use internal shared cursor

children = person.property("children");     // use internal shared cursor

children.open(person.property("children")); // create private cursor copy

Notes:
The constructor provides the default cursor, which is part if the parent's instance. This cursor will be shared with other property handles created by calling property() or this constructor. Changes made on shared cursor will affect all property handles referring to this cursor. This also includes changing e.g. the property handle access mode. In order to get a 'private' cursor, a copy handle may be created by calling cursorCopy() , which provides a cursor copy that is used exclusively.
- cProperty - Property reference
  A property handle refers to a (usually) opened property. Invalid properties may cause an exception.
- vAccessPath - Access path
  An access path may simply refer to an extent or property, but also to a calculated result. Thus, an access path may contain just a name, but also a sequence of path elements separated by '.' in order to refer to far properties or complex operations.
  
  The access path may start with two dots (.), which indicates, that the path starts in an upper property handle. One dot indicates, that the path starts in the current property handle. This distinction becomes necessary, when a property has the same name as an extent. To access a property in this case, one dot must precede the property name. The first dot can be omitted, when the property name is not an extent name.
  
  Forcing to a path to start in a parent property handle requires two dots (..), the parents parent three and so on.
  
  In order to pass no access path, an empty string ( String() ) has to be passed.
  
  address.street      // property path
  
  .address.street     // property path
  
  ..address.street    // address in parent property instance
  
  children(0).Age()   // operation path
  
  Person().children() // path property
  
  children('Anton')   // path property

to list

Create property handle for transient collection
odaba::Property & Property :: open ( odaba::ObjectSpace &cObjectSpace, odaba::String &sExtentName, odaba::String &sKeyName )

The function creates a property handle for an application transient property, which is based on a extent definition passed in sExtentName . The extent name may contain symbolic references to option variables (e.g. %EXT_PREF%Pers ), which are replaced before evaluating the extent name by current settings of corresponding options.

The extent will be created as transient collection, which stores instances in memory.

A key name may be passed in sKeyName in order to select an access key. When passing an empty key name, the access key is set to the main key of the extent definition.
- cObjectSpace - Object space reference
  The reference refers to an opened or not opened object space handle.
- sExtentName - Extent name
- sKeyName - Key name
  The key name must be the name of a key defined for the given structure. The key name is passed as string with maximum 40 characters.
  
  In order to pass no key name, an empty string ( String() ) has to be passed.

to list

Create copy property handle
odaba::Property & Property :: open ( odaba::Property &cProperty )

The function creates a copy of the property handle passed in cProperty . Both, the copy and the origin, share the cursor, access key selection, filter settings and event handlers, i.e. changing the instance selection in one of the property handles will automatically change the instance selection in the other.

In order to create a property referring to a separate cursor one may call cursorCopy () .

When the property handle passed is not valid, the function throws an exception.
- cProperty - Property reference
  A property handle refers to a (usually) opened property. Invalid properties may cause an exception.

to list

Open extent property handle
odaba::Property & Property :: open ( odaba::ObjectSpace &cObjectSpace, odaba::String &vExtentPath, odaba::AccessModes eAccessMode )

The function opens a property handle for the extent or extent based operation path passed in vExtentPath . The operation path may contain symbolic references to option variables (e.g. %EXT_PREF%Pers ), which are replaced before evaluating the access path by current settings of corresponding options.

As operation path, a simple property name (extent name), a property path or a path property might be passed as well in vExtentPath .

The extent property is opened with the access mode passed in eAccessMode . The access mode can be changed later on by setting the accessMode() property.

When the extent name (e.g. ImportPersons ) refers to an external file (CSV, Directory, XML etc.), an option variable with the extent name has to be defined in the ini-file, database options or application, which refers to the file location (like ImportPersons=~/data/impost/persons.csv ).
- cObjectSpace - Object space reference
  The reference refers to an opened or not opened object space handle.
- vExtentPath - Extent path
  An extent path may simply refer to an extent, but also to a local collection in the database (property path). Thus, an extent path may contain just a name, but also a sequence of path elements separated by '.' in order to refer to far properties.
  
  In order to pass no extent path, an empty string ( String() ) has to be passed.
- eAccessMode - Access mode
  Access mode for a property handle or database.

to list

Create transient instance property
odaba::Property & Property :: open ( odaba::ObjectSpace &cObjectSpace, odaba::String &sTypeName )

The function creates a transient property of the complex data type passed in sTypeName . When the object space passed in cObjectSpace is not a dictionary, the type is searched in the dictionary of the object space.
- cObjectSpace - Object space reference
  The reference refers to an opened or not opened object space handle.
- sTypeName - Type name
  The type name is the name of a data type (usually) defined in the database. The type name might be passed as simple identifier or as scoped name with preceding namespace names separated by double colon '::'.
  
  In order to pass no type name, an empty string ( String() ) may be passed.

to list

Create property handle for temporary or transient extent
odaba::Property & Property :: open ( odaba::ObjectSpace &cObjectSpace, odaba::String &sTypeName, odaba::String &sKeyName, odaba::String &vBaseExtent, bool bWeakTyped, bool bOwner, bool bTransient )

The function creates a property handle for an temporary or transient extent, which is based on a complex data type definition passed in sTypeName . The extent name is a unique name created by the system.

A key name can be passed in sKeyName in order to select an access key. When passing an empty key name, the access key is set to the primary key.

The extent will be created as temporary extent storing data in a temporary database. In order to store data in memory (transient extent), true has to be passed in bTransient .

When the collection owns the instances it is referring to ( bOwner = true ), not only the collection but also instances are created as transient or temporary instances in memory or in a temporary database (depending on bTransient ). When not owning instances, a base extent can be passed in vBaseExtent .

In order to store instances of different types in the collection, true has to be passed in bWeakTyped .
- cObjectSpace - Object space reference
  The reference refers to an opened or not opened object space handle.
- sTypeName - Type name
  The type name is the name of a data type (usually) defined in the database. The type name might be passed as simple identifier or as scoped name with preceding namespace names separated by double colon '::'.
  
  In order to pass no type name, an empty string ( String() ) may be passed.
- sKeyName - Key name
  The key name must be the name of a key defined for the given structure. The key name is passed as string with maximum 40 characters.
  
  In order to pass no key name, an empty string ( String() ) has to be passed.
- vBaseExtent - Base extent name
  A base extent or base collection can be passed as access path that defines a super set for a collection. The extent name might be passed as scoped name with preceding namespace names separated by double colon '::'.
  
  Passing an empty value or "" as extent name indicates no extent name.
- bWeakTyped - Weak-typed option
  This option must be true when a collection may refer to instances of different types, which are based on the same base type.
- bOwner - Owning collection
  This option must be set to true when the collection owns the instances. In this case the collection may not refer to instances from other collections. Removing instances from an owning collection will result in deleting instances completely.
- bTransient - Transient option
  To create transient property handles, true has to be passed. In this case the property handle instances and indexes are stored in main storage, only.

to list

to top Comment