gnue.forms Private API - GNU Enterprise

Package gnue :: Package common :: Package datasources :: Module GDataSource :: Class GDataSource

[show private | hide private]

Type GDataSource

GTriggerCore --+    
               |    
  object --+   |    
           |   |    
   ParserObj --+    
               |    
            GObj --+
                   |
                  GDataSource

Known Subclasses:: GFDataSource

Class that handles DataSources. This is a subclass of GObj, which means this class can be created from XML markup and stored in an Object tree (e.g., a Forms tree).

Each GDataSource object maintains its own event controller and issues the following events:

dsResultSetActivated (parameters: resultSet) whenever the current ResultSet of this datasource changes; this happens when a query is executed or when the master of this datasource moves to another record.
dsResultSetChanged (parameters: resultSet) whenever the current ResultSet has been reloaded from the backend; this happens after each commit if the "requery" option of this datasource is in use.
dsCursorMoved (parameters: none) whenever the cursor in the current ResultSet is moved, i.e. a different record becomes the current record.
dsRecordLoaded whenever a record has been loaded from the backend.
dsRecordTouchend whenever a record is modified for the first time since it was loaded from the backend or last saved.
dsCommitInsert whenever a record is about to be inserted in the backend due to a commit operation. The record in question will be the current record of the datasource at the time this trigger is run.
dsCommitUpdate whenever a record is about to be updated in the backend due to a commit operation. The record in question will be the current record of the datasource at the time this trigger is run.
dsCommitDelete whenever a record is about to be deleted in the backend due to a commit operation. The record in question will be the current record of the datasource at the time this trigger is run.

Method Summary
	`__init__(self, parent, type)`
	`createEmptyResultSet(self, masterRecord)` Create an empty result set.
	`createResultSet(self, conditions, readOnly, masterRecord)` Execute a query on the backend and create a result set.
	`getCondition(self)` Returns the static condition for this datasource, as set in setCondition or as defined in XML.
	`getMaster(self)` Return the master datasource of this datasource.
	`hasMaster(self)` Return True if this datasource is a detail of another datasource.
	`postAll(self)` Post all changes to the backend.
	`referenceField(self, field, defaultValue)` Reference a bound field (i.e.
	`referenceFields(self, fields)` Reference several bound fields at once (i.e.
	`referenceUnboundField(self, field, defaultValue)` Reference an unbound field.
	`requeryAll(self, commit)` Requery data from the backend.
	`setCondition(self, mycondition)` Set the static condition for this datasource.
	`setConnectionManager(self, connectionManager)` Set the connection manager (`GConnections.GConnections` instance for this datasource.
	`__convertOrderBy(self, order_by)` This function transforms an order_by rule into a proper 'sorting' sequence, made of dictionaries with the keys 'name', 'descending' and 'ignorecase'.
	`__createResultSet(self, conditions, readOnly, masterRecord)`
	`__get_fields(self, readOnly)`
	`__newResultSet(self, readOnly, masterRecord)`
	`__primaryInit(self)`
	`__secondaryInit(self)`
	`__tertiaryInit(self)`
	`__trigger_call(self, name, params)`
	`__trigger_createResultSet(self, conditions, readOnly, query)`
	`__trigger_delete(self)`
	`__trigger_get_extensions(self)`
	`__trigger_get_order_by(self)`
	`__trigger_get_recordCount(self)`
	`__trigger_set_order_by(self, value)`
	`__trigger_simpleQuery(self, maskDict)`
	`__trigger_update(self)`
	`_activateResultSet(self, resultSet)` Make the given result set the active result set for this datasource.
	`_addDetail(self, dataSource, pkFields, fkFields)` Add a detail datasource where this datasource is the master.
	`_buildObject(self)` This function is called after the parsers have completely constructed.
	`_requeryResultSet(self, masterRecord, resultSet)` Requery data for an existing result set from the backend.
Inherited from GObj
	`__getitem__(self, key)`
	`__setitem__(self, key, value)`
	`_dumpXML_(self, lookupDict, treeDump, gap, xmlnamespaces, textEncoding, stripPrefixes, escape)` Dumps an XML representation of the object
	`buildAndInitObject(self, **params)` This is a convenience function for applications NOT using GParser to load an object tree.
	`buildObject(self, **params)` A convenience function for applications NOT using GParser to load an object tree.
string	`getXmlTag(self, stripPrefixes)` Returns the xml tag to be used to represent the object.
	`iterator(self, test, types, includeSelf)` Return a python iterator of child objects.
	`maxInits(self)` maxInits returns the maximum size of all the _inits list from this object or it's children
	`phaseInit(self, iterations)` Starts GNUe's phased initialization system from this object down.
	`showTree(self, indent)` A recusive function to print an indented text representation of the GObj tree from this object down.
	`walk(self, function, args, *parms)` Function that recursively walks down through a tree of `ParserObj` instances and applies a function to them.
	`_phaseInit(self, phase)` Used internally by phaseInit to walk through the object tree initializing objects.
	`_setItemHook(self, key, value)` This bit of nastiness is here to let GNUe Designer capture the setting of GObject properties.
Inherited from GTriggerCore
	`__repr__(self)`
	`create_namespace_object(self, global_namespace, namespace_name)` Construct a namespace object tree from an XML (`definitions.GObjects.GObj`) object tree.
	`get_namespace_object(self)` Return the namespace object that mirrors this object in the action/trigger namespace.
Inherited from ParserObj
	`_diffActionWalker_(self, obj, action)` Set the action attribute of a given object to the specified action.
	`_getAsContents_(self)` Get the contents of this object.
	`_id_(self, maxIdLength)` Return a compareable and identifying id of an object within a tree.
	`_set_initial_attributes_(self, attributes)` Set attributes loaded by GParser.
	`addChild(self, child)` Add an object to the list of children
	`assign(self, source, recursive)` Assign all attributes from a given object to this one.
	`diff(self, goal, maxIdLength)` Build an object tree representing the difference between two object trees.
	`dumpXML(self, lookupDict, treeDump, gap, xmlnamespaces, textEncoding, stripPrefixes, escape)` Return a XML representation of the object.
	`findChildNamed(self, name, childType)` Moves downward though the children of an object till it finds the child with the specified name.
	`findChildOfType(self, childType, includeSelf, allowAllChildren)` Moves downward through the children of an object till it finds the child of the specified type.
	`findChildrenOfType(self, childType, includeSelf, allowAllChildren)` Find all children of a specific type.
	`findParentOfType(self, parentType, includeSelf)` Moves upward though the parents of an object till it finds the parent of the specified type.
	`getChildrenAsContent(self)` Returns the content of any GContent objects that are children of this object.
	`getDescription(self)` Return a useful description of the object.
any	`getParent(self)` Returns the immediate parent of an object instance in a GObj tree.
	`merge(self, other, maxIdLength, overwrite)` Merge another object tree into this tree.
	`setParent(self, newParent)` Set the immediate parent of an object instance in a GObj tree
Inherited from object
	`__delattr__(...)` x.__delattr__('name') <==> del x.name
	`__getattribute__(...)` x.__getattribute__('name') <==> x.name
	`__hash__(x)` Return hash(x)...
	`__new__(T, S, ...)` Return a new object with type S, a subtype of T...
	`__reduce__(...)` helper for pickle
	`__reduce_ex__(...)` helper for pickle
	`__setattr__(...)` x.__setattr__('name', value) <==> x.name = value
	`__str__(x)` Return str(x)...

Instance Variable Summary
Inherited from GTriggerCore
	`_triggerFunctions`: Dictionary defining the functions this object should present in action/trigger code.
	`_triggerGet`: Can be set to a method that returns the string value of the object.
	`_triggerGlobal`: If set to True, this object is added to the global namespace.
	`_triggerProperties`: Dictionary defining the properties this object should present in action/trigger code.
	`_triggerSet`: Can be set to a method that sets the value of this object.

Method Details

init(self, parent=None, type='GDataSource')
(Constructor)

Overrides:: gnue.common.definitions.GObjects.GObj.__init__

createEmptyResultSet(self, masterRecord=None)

Create an empty result set.

The result set generated will become the active result set of this datasource.

Parameters:: masterRecord - Master RecordSet object for the ResultSet to be generated if the datasource is a detail datasource (this will become important once new records are inserted in this result set).

Returns:: The new active (empty) ResultSet object.

createResultSet(self, conditions={}, readOnly=False, masterRecord=None)

Execute a query on the backend and create a result set.

The result set generated by the query will become the active result set of this datasource.

Parameters:: conditions - Conditions to be applied additionally to the static condition of the datasource (defined with setCondition or with <conditions> XML tags).; readOnly - True if the result set should be read only, which means any attempt to change the result set will raise an exception.; masterRecord - Master RecordSet object for the ResultSet to be generated if the datasource is a detail datasource.

Returns:: The new active ResultSet object.

getCondition(self)

Returns the static condition for this datasource, as set in setCondition or as defined in XML.

getMaster(self)

Return the master datasource of this datasource.

hasMaster(self)

Return True if this datasource is a detail of another datasource.

postAll(self)

Post all changes to the backend.

This function posts the top level master datasource of this datasource and all of that datasource's children.

After calling postAll, requeryAll must be called.

referenceField(self, field, defaultValue=None)

Reference a bound field (i.e. bind it to a database column with the same name).

Parameters:: field - Field name.; defaultValue - optional default value for newly inserted records.

referenceFields(self, fields)

Reference several bound fields at once (i.e. bind them to database columns with the same names).

Parameters:: fields - List of field names.

referenceUnboundField(self, field, defaultValue=None)

Reference an unbound field.

Unbound fields are not bound to a database column. Values stored in unbound fields are not persistent.

It is only necessary to explicitly reference an unbound field if a default value should be set.

Parameters:: field - Field name.; defaultValue - optional default value for newly inserted records.

requeryAll(self, commit)

Requery data from the backend.

This must be called after postAll to synchronize the datasource with changes that happened in the backend (through backend triggers). It requeries the top level master datasource of this datasource and all of that datasource's children.

Note that this method also updates the record status for all added, modified and deleted records, so it has to be called even if the requery feature of the datasource is not used.

Parameters:: commit - indicate whether a commit was done since the call to postAll.

setCondition(self, mycondition)

Set the static condition for this datasource. This condition is used in any query, additionally to the condition given in createResultSet.

Parameters:: mycondition - condition in prefix notation, dictionary notation or as a GConditions object tree.

setConnectionManager(self, connectionManager)

Set the connection manager (GConnections.GConnections instance for this datasource.

Parameters:: connectionManager - the connection manager instance.

__convertOrderBy(self, order_by)

This function transforms an order_by rule into a proper 'sorting' sequence, made of dictionaries with the keys 'name', 'descending' and 'ignorecase'.

Parameters:: order_by - string, unicode-string, sequence with sort-order

Returns:: sequence of dictionaries (name, descending, ignorecase)

__createResultSet(self, conditions={}, readOnly=False, masterRecord=None)

__get_fields(self, readOnly)

__newResultSet(self, readOnly, masterRecord)

__primaryInit(self)

__secondaryInit(self)

__tertiaryInit(self)

__trigger_call(self, name, params)

__trigger_createResultSet(self, conditions={}, readOnly=False, query=False)

__trigger_delete(self)

__trigger_get_extensions(self)

__trigger_get_order_by(self)

__trigger_get_recordCount(self)

__trigger_set_order_by(self, value)

__trigger_simpleQuery(self, maskDict)

__trigger_update(self)

_activateResultSet(self, resultSet)

Make the given result set the active result set for this datasource.

The master calls this to activate the correct detail result sets for its detail datasources.

_addDetail(self, dataSource, pkFields, fkFields)

Add a detail datasource where this datasource is the master.

This method is called by the detail datasource to register itself at the master.

Parameters:: dataSource - detail datasource.; pkFields - list of field names of the primary key fields in the detail datasource.; fkFields - list of field names of the foreign kei fields in the master datasource (i.e. in this datasource).

_buildObject(self)

This function is called after the parsers have completely constructed. All children should be in place and attributes and content should be set at this point. Return the number of phaseInit iterations your object will need.

NOTE: Do not initialize datasources, etc at this point. This is only so content can be set, etc, after loading from XML.

Returns:: number of the phaseInit iterations needed by this object

Overrides:: gnue.common.definitions.GObjects.GObj._buildObject (inherited documentation)

_requeryResultSet(self, masterRecord, resultSet)

Requery data for an existing result set from the backend.

This function queries the data for an existing result set again from the backend and merges everything that has changed meanwhile into the existing result set.

The RecordSet object uses this function to update all it's detail result sets after its changes have been posted to the database.

The resultSet is passed as a parameter and need not be the current result set of the datasource.

Parameters:: masterRecord - The master record for which the detail should be requeried.; resultSet - The existing result set into which the changes should be merged.

Type GDataSource

init(self, parent=None, type='GDataSource')
(Constructor)

createEmptyResultSet(self, masterRecord=None)

createResultSet(self, conditions={}, readOnly=False, masterRecord=None)

getCondition(self)

getMaster(self)

hasMaster(self)

postAll(self)

referenceField(self, field, defaultValue=None)

referenceFields(self, fields)

referenceUnboundField(self, field, defaultValue=None)

requeryAll(self, commit)

setCondition(self, mycondition)

setConnectionManager(self, connectionManager)

__convertOrderBy(self, order_by)

__createResultSet(self, conditions={}, readOnly=False, masterRecord=None)

__get_fields(self, readOnly)

__newResultSet(self, readOnly, masterRecord)

__primaryInit(self)

__secondaryInit(self)

__tertiaryInit(self)

__trigger_call(self, name, params)

__trigger_createResultSet(self, conditions={}, readOnly=False, query=False)

__trigger_delete(self)

__trigger_get_extensions(self)

__trigger_get_order_by(self)

__trigger_get_recordCount(self)

__trigger_set_order_by(self, value)

__trigger_simpleQuery(self, maskDict)

__trigger_update(self)

_activateResultSet(self, resultSet)

_addDetail(self, dataSource, pkFields, fkFields)

_buildObject(self)

_requeryResultSet(self, masterRecord, resultSet)

GNUe Home

Private API

Developer's Corner

Type GDataSource

__init__(self, parent=None, type='GDataSource') (Constructor)

createEmptyResultSet(self, masterRecord=None)

createResultSet(self, conditions={}, readOnly=False, masterRecord=None)

getCondition(self)

getMaster(self)

hasMaster(self)

postAll(self)

referenceField(self, field, defaultValue=None)

referenceFields(self, fields)

referenceUnboundField(self, field, defaultValue=None)

requeryAll(self, commit)

setCondition(self, mycondition)

setConnectionManager(self, connectionManager)

__convertOrderBy(self, order_by)

__createResultSet(self, conditions={}, readOnly=False, masterRecord=None)

__get_fields(self, readOnly)

__newResultSet(self, readOnly, masterRecord)

__primaryInit(self)

__secondaryInit(self)

__tertiaryInit(self)

__trigger_call(self, name, params)

__trigger_createResultSet(self, conditions={}, readOnly=False, query=False)

__trigger_delete(self)

__trigger_get_extensions(self)

__trigger_get_order_by(self)

__trigger_get_recordCount(self)

__trigger_set_order_by(self, value)

__trigger_simpleQuery(self, maskDict)

__trigger_update(self)

_activateResultSet(self, resultSet)

_addDetail(self, dataSource, pkFields, fkFields)

_buildObject(self)

_requeryResultSet(self, masterRecord, resultSet)

GNUe Home

Private API

Developer's Corner

init(self, parent=None, type='GDataSource')
(Constructor)