RDBMSResolver

Kind of class:	class
Inherits from:	MovieClip
Classpath:	mx.data.components.RDBMSResolver
File last modified:	Tuesday, 18 December 2007, 15:44:38

The Firefly resolver components provide developers with an easy and flexible method
of saving data back to any supported data source, including XML, Remoting recordsets,
and SQL Server. The resolver components offer a significant advantage over similar
technologies by creating a level of abstraction between the developer and the data
source. Using this architecture, you can easily add new functionality to your existing
applications by simply swapping one resolver for another without having to rewrite any
ActionScript code. The resolver is bound to a dataset's DeltaPacket property, and each
different type of resolver translates it from the generic DeltaPacket format into a
specific format (DiffGrams, UpdateGrams, XUpdate, etc.)

Component metadata:

Event	"beforeApplyUpdates"

Summary

Constructor

RDBMSResolver

Class properties

umUsingKey : String
umUsingModified : String
umUsingAll : String

Instance properties

tableName : String
- The tableName property stores the table name that is placed into the updatePacket so that
updateMode : String
- The updateMode property helps to determine which fields in the updatePacket are marked as key fields.
nullValue : String
- The nullValue property lets the user set a string which will be put into the updatePacket to signify when a field's value is null.
fieldInfo : Collection
- A collection property that allows the programmer to specify which fields are key fields and which fields should not be included
deltaPacket : DeltaPacket
- Property that receives a deltaPacket it can be translated into an updatePacket, and gets the deltaPacket from the updateResults
updatePacket : XML
- Property that is set with an updatePacket created by this component so that it can be transmitted out to a server.
updateResults : XML
- Property that receives a results packet from the server so that it can be translated to a deltaPacket
unresolvedPackets : Array
- This array property holds a list of all updatePackets which have been sent back but for which
__fieldInfo : Collection
__nullValue : String
__tableName : String
__updateMode : String
__schema : Object
__deltaPacket : DeltaPacket
__updatePacket : XML
__updateResults : XML
__unresolvedPackets : Array
__unresolvedDeltas : Array
_opNumber : Array
_fieldValueObj : Object
collClass : mx.utils.CollectionImpl
collItem : mx.data.components.resclasses.FieldInfoItem
dispatchEvent : Function
addEventListener : Function
removeEventListener : Function

Instance methods

addFieldInfo (fieldName:String, ownerName:String, isKey:Boolean) : Void
- Adds a new item to the fieldInfo collection.
resendPacket (transID:String) : Boolean
- Causes the specified packet in the unresolvedPackets list to be resent thru the updatePacket property.
buildFieldTag (deltaObj:Delta, field:Object, isKey:Boolean) : String
- Returns a string containing the XML for the field being passed in
createUpdatePacketFromDelta
decodeFieldValue (fieldName:String, value:String) : Object
- Decode the field value from a string representation into the native datatype we are using to store it.
encodeFieldValue (fieldName:String, value:Object) : String
- Encode the field value from it's internal representation to a string representation .
getDeltaAsXML (deltaPacket:DeltaPacket) : XML
- Creates an XML packet to be assigned to the UpdatePacket property.
getFieldInfo (fieldName:String) : FieldInfoItem
- Finds and returns the field info collection item that matches the field name passed in.
getFieldList (deltaObj:Delta, keyFieldMode:String, listModified:Boolean) : String
- Creates an the field portion of the XML packet.
includeField (deltaObj:Delta, fld:Object, keyFieldMode:String, includeModified:Boolean) : Boolean
- Determines whether a field should be included in the list of fields for a delta.
isKey (fld:Object, chgItem:DeltaItem, keyFieldMode:String) : Boolean
- Return a boolean indicating whether the field passed in should be marked as a key field.
removeUnresolvedPacket (transID:String) : Void
- Removes the specified packet from the unresolvedPackets list.
updateResultsToDataset : Void
- This method gets called when results come back to this component.
updateResultNodeToDelta (transID:String, node:XMLNode) : Delta
- This method translates an individual result node into an instance of the DeltaImpl class
getDeltaSource (transID:String, opID:String) : Object
getLocalSchema (extSch:Object) : Object
- This method will return a local schema object that includes any overrides that have been made on
updateResultsAddDeltaItems (node:XMLNode, delta:Delta) : Void
- This method iterates thru the field nodes for an operation result or change node and adds them as DeltaItems
updateResultGetSourceObject (node:XMLNode, isInsert:Boolean) : Object
- This method returns the "source" object which is used by the Delta object.

Constructor

RDBMSResolver

function RDBMSResolver (

)

Class constructor

Class properties

umUsingAll

static umUsingAll:String = "umUsingAll"

(read)

umUsingKey

static umUsingKey:String = "umUsingKey"

(read)

umUsingModified

static umUsingModified:String = "umUsingModified"

(read)

Instance properties

__deltaPacket

private __deltaPacket:DeltaPacket

(read)

__fieldInfo

private __fieldInfo:Collection

(read)

__nullValue

private __nullValue:String

(read)

__schema

private __schema:Object

(read)

__tableName

private __tableName:String

(read)

__unresolvedDeltas

private __unresolvedDeltas:Array

(read)

__unresolvedPackets

private __unresolvedPackets:Array

(read)

__updateMode

private __updateMode:String

(read)

__updatePacket

private __updatePacket:XML

(read)

__updateResults

private __updateResults:XML

(read)

_fieldValueObj

private _fieldValueObj:Object

(read)

_opNumber

private _opNumber:Array

(read)

addEventListener

addEventListener:Function

(read)

collClass

private collClass:mx.utils.CollectionImpl

(read)

collItem

private collItem:mx.data.components.resclasses.FieldInfoItem

(read)

deltaPacket

deltaPacket:DeltaPacket

(read,write)

Property that receives a deltaPacket it can be translated into an updatePacket, and gets the deltaPacket from the updateResults
so it can be sent back to the dataset.
@property deltaPacket

Author:

Mark Rausch

Component metadata:

Bindable	type: "DeltaPacket"
ChangeEvent	"deltaPacketChanged"

dispatchEvent

dispatchEvent:Function

(read)

fieldInfo

fieldInfo:Collection

(read)

A collection property that allows the programmer to specify which fields are key fields and which fields should not be included
in the update packet.
@property fieldInfo

Author:

Mark Rausch

Component metadata:

Collection	collectionClass: "mx.utils.CollectionImpl", collectionItem: "mx.data.components.resclasses.FieldInfoItem", identifier: "fieldName" name: "fieldInfo", variable: "__fieldInfo",

nullValue

nullValue:String

(read,write)

The nullValue property lets the user set a string which will be put into the updatePacket to signify when a field's value is null.
@property nullValue

Author:

Mark Rausch

Component metadata:

Inspectable	defaultValue: "

removeEventListener

removeEventListener:Function

(read)

tableName

tableName:String

(read,write)

The tableName property stores the table name that is placed into the updatePacket so that
the server can tell which table should be updated.
@property tableName

Author:

Mark Rausch

Component metadata:

Inspectable	defaultValue: ""

unresolvedPackets

unresolvedPackets:Array

(read)

This array property holds a list of all updatePackets which have been sent back but for which
no updateResults have been received. When updateResults are received back, the corresponding
updatePacket is immediately removed from this list.

This allows the user to determine which updatePackets have perhaps been lost. Any of them can
be resent by using the resendPacket() function.

tiptext List of packets for which results have not been returned

updateMode

updateMode:String

(read,write)

The updateMode property helps to determine which fields in the updatePacket are marked as key fields. Setting this mode allows the programmer
to determine how to handle conflicts when updating records that have also been modified by other users.
@property updateMode

Author:

Mark Rausch

Component metadata:

Inspectable	defaultValue: "umUsingKey" enumeration: "umUsingKey,umUsingModified,umUsingAll",

updatePacket

updatePacket:XML

(read)

Property that is set with an updatePacket created by this component so that it can be transmitted out to a server.
@property updatePacket

Author:

Mark Rausch

Component metadata:

Bindable
ChangeEvent	"updatePacketChanged"

updateResults

updateResults:XML

(read,write)

Property that receives a results packet from the server so that it can be translated to a deltaPacket
@property updateResults

Author:

Mark Rausch

Component metadata:

Bindable
ChangeEvent	"updateResultsChanged"

Instance methods

addFieldInfo

function addFieldInfo (

fieldName:String, ownerName:String, isKey:Boolean) : Void

Adds a new item to the fieldInfo collection. This method can be used by programmers who need to set
up a resolver dynamically at runtime, rather than via the component inspector in the authoring environment.
@function addFieldInfo

Parameters:

fieldName:

String value containing the name of the field this info object describes

ownerName:

String value containing the name of the table this field is "owned" by. May be left blank
if it is the same as the resolver instance's tablename property.

isKey :

Boolean value indicating whether this field is a key field

Author:

Mark Rausch

Example:

var myResolver:RDBMSResolver = new RDBMSResolver();
myResolver.tableName = "Customers";
//Set up the id field as a key field and the personTypeName field so it won't be updated.
myResolver.addFieldInfo("id", "", true);
myResolver.addFieldInfo("personTypeName", "JoinedField", false);
//Now set up the data bindings
//...

buildFieldTag

private function buildFieldTag (

deltaObj:Delta, field:Object, isKey:Boolean) : String

Returns a string containing the XML for the field being passed in

Parameters:

field :

Pointer to the field object (for the name and data type)

chgItem:

DeltaItem object that describe the changes that were made to this field (may be null)

isKey :

Boolean value that determines whether or not this field's key attribute should be true or false.

Author:

Mark Rausch

Example:

The general format for the returned string is as follows:

createUpdatePacketFromDelta

private function createUpdatePacketFromDelta (

)

This method gets fired when a new delta packet gets assigned to this component. It translates the delta packet into
XML, fires an event to allow the user a chance to view/modify the XML, assigns it to the UpdatePacket, and fires the event
that triggers the databinding mechanism.

Author:

Mark Rausch

decodeFieldValue

function decodeFieldValue (

fieldName:String, value:String) : Object

Decode the field value from a string representation into the native datatype we are using to store it. Use the data pipeline to
do the translation.

encodeFieldValue

function encodeFieldValue (

fieldName:String, value:Object) : String

Encode the field value from it's internal representation to a string representation . Use the data pipeline to
do the translation.

getDeltaAsXML

private function getDeltaAsXML (

deltaPacket:DeltaPacket) : XML

Creates an XML packet to be assigned to the UpdatePacket property.

Parameters:

deltaPacket:

reference to an instance of an IDeltaPacket interface that contains a list of all changed
rows and which fields were changed in them.

Returns:

reference to a new XML object containing the translation of the deltapacket to our XML format

Author:

Jason Williams & Mark Rausch

Example:

The general format for the XML is as follows:

getDeltaSource

private function getDeltaSource (

transID:String, opID:String) : Object

getFieldInfo

private function getFieldInfo (

fieldName:String) : FieldInfoItem

Finds and returns the field info collection item that matches the field name passed in.

Author:

Jason Williams & Mark Rausch

getFieldList

private function getFieldList (

deltaObj:Delta, keyFieldMode:String, listModified:Boolean) : String

Creates an the field portion of the XML packet.

Parameters:

deltaObj :

reference to an Delta object which contains a description of changes made to a single row.

keyFieldMode:

Numeric representation of the 3 updateMode values (umUsingKey, umUsingModified, and umUsingAll)
that specifies which fields should be included and marked as key fields for the Delta object which was
passed in.
Note that this may not be the same as this component's UpdateMode parameter. E.g. For an inserted
record, it is not necessary to mark any fields as keys except key fields, regardless of the __updateMode
setting for this component

Returns:

String containing the XML formatted field list. The fields will include all "key" fields and all
modified fields.

Author:

Jason Williams & Mark Rausch

Example:

The general format for the returned string is as follows:

...

getLocalSchema

private function getLocalSchema (

extSch:Object) : Object

This method will return a local schema object that includes any overrides that have been made on
this resolver to the associated connector schema, that is passed through the delta packet.

Parameters:

extSch:

Object containing the schema from the external source, provided via the deltapacket

Returns:

Object containing either the same schema or one that has been modified to include any overriden
values.

includeField

private function includeField (

deltaObj:Delta, fld:Object, keyFieldMode:String, includeModified:Boolean) : Boolean

Determines whether a field should be included in the list of fields for a delta. This determination is based on
the fieldinfo, the updatemode, and whether or not the field was modified.

Parameters:

fld :

The dataset's field object for the field being asked about

chgItem :

The deltapacket's DeltaItem for the row/field being asked about

keyFieldMode :

Numeric representation of the 3 updateMode values (umUsingKey, umUsingModified, and umUsingAll)

includeModified:

Boolean. True if this method should return modified fields as included

Returns:

Boolean indicating if the field should be included or not

Author:

Jason Williams & Mark Rausch

isKey

private function isKey (

fld:Object, chgItem:DeltaItem, keyFieldMode:String) : Boolean

Return a boolean indicating whether the field passed in should be marked as a key field. The field does not have to be
listed as a key field in the component parameters for this method to return true. True will be returned depending on the
keyFieldMode parameter passed in:
If using all fields as keys,
or if using modified fields as keys,
or if it has been marked as a key field, return true

Parameters:

deltaItem :

reference to an Delta object which contains a description of changes made to a single row.

keyFieldMode:

Returns:

String containing the XML formatted field list. The fields will include all "key" fields and all
modified fields.

Author:

Jason Williams & Mark Rausch

removeUnresolvedPacket

private function removeUnresolvedPacket (

transID:String) : Void

Removes the specified packet from the unresolvedPackets list.
@function removeUnresolvedPacket

Parameters:

transID:

The transaction ID for the updatePacket which should be removed

Author:

Mark Rausch

resendPacket

function resendPacket (

transID:String) : Boolean

Causes the specified packet in the unresolvedPackets list to be resent thru the updatePacket property. This
can be used when packets have been sent but no response received back from the server, indicating that the
server did not receive it. If the specified packet does not exist, this function returns false, otherwise it
returns true.

NOTE: The "at" helpid symbol has been removed so that this method will not appear in the environment for the time being

function resendPacket
param transID The transaction ID for the updatePacket which should be resent
author Mark Rausch
tiptext Resends an unresolvedPacket
example
//Resend all unresolvedPackets
for (var transID in res.unresolvedPackets) {;
resendPacket(transID);
}

updateResultGetSourceObject

private function updateResultGetSourceObject (

node:XMLNode, isInsert:Boolean) : Object

This method returns the "source" object which is used by the Delta object. The source object is used to locate the record
to be updated or deleted, or for an insert it contains all the field values for the insert operation. It's properties
get set from the field nodes for an operation result or change node.

Parameters:

node :

The operation result or change node under which to look for field nodes

isInsert:

A boolean value that determines if all fields or only key fields will be used, and whether to use newValue or oldValue

Returns:

An anonymous object with properties named by field and whose value is set from either the old or new value attributes

Author:

Mark Rausch

Example:

The some examples of the field nodes are as follows:

updateResultNodeToDelta

private function updateResultNodeToDelta (

transID:String, node:XMLNode) : Delta

This method translates an individual result node into an instance of the DeltaImpl class

Returns:

reference to a new Delta instance

Author:

Mark Rausch

Example:

The general format for the XML in the results packet is as follows:

updateResultsAddDeltaItems

private function updateResultsAddDeltaItems (

node:XMLNode, delta:Delta) : Void

This method iterates thru the field nodes for an operation result or change node and adds them as DeltaItems
to the Delta which is passed in.

Parameters:

node :

The operation result or change node under which to look for field nodes

delta:

The Delta object which will hold the DeltaItems

Author:

Mark Rausch

Example:

The some examples of the field nodes are as follows:

updateResultsToDataset

private function updateResultsToDataset (

) : Void

This method gets called when results come back to this component. It translates the results, fires
an event to allow the user a chance to view/modify the it, assigns it to the DeltaPacket property,
and then fires the event that triggers the databinding mechanism.

Author:

Mark Rausch

Example:

The general format for the XML in the results packet is as follows: