DataSet

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

Fires just before an item is added to the collection. If the result property
of this event is set to false the item will not be added to the collection.

Summary

Constructor

DataSet

Class properties

DefaultIterator : String
ItemId : String
KeysOnly : Number
All : Number

Instance properties

currentItem : Object
- Read-only; The current transfer object the default iterator is pointing to.
deltaPacket : DeltaPacket
- Contains all of the mutation operations that have been made to this
dataProvider : Object
- DataProvider interface for this dataset.
filtered : Boolean
- Indicates if the default iterator is filtered.
filterFunc : Function
- Method used to filter the default iterator's view of this collection's transfer objects.
items : Array
- Collection of transfer objects for this DataSet.
itemClassName : String
- Used to construct an instance of the specified class during a createItem() call.
length : Number
- Total number of transfer objects viewable within this collection based on the
logChanges : Boolean
- Indicates if changes should be tracked and recorded in the DeltaPacket.
properties : Object
- List of all of the exposed properties for any transfer object within this collection.
readOnly : Boolean
- Indicates if this collection is updatable.
schema : XML
- Schema in XML format for this DataSet.
selectedIndex : Number
- Indicates the selected index of the current iterator within the DataSet.
getField : Function
refreshFromSources : Function
_fldValObj : Object
_defValues : Object
_loading : Boolean
_srcSchema : Object
_allowReslv : Boolean
_eventDispatcher : Object
_itemIndexById : Array
_enableEvents : Number
_event : Object
_filtered : Boolean
_filterFunc : Function
_optDeltaItems : Array
_deltaItems : Array
_deltaPacket : DeltaPacket
_dpIndexByTransId : Array
_lastTransId : String
_dpTransIdCount : Number
_itemClass : Function
_hasDelta : Number
_iterators : Array
_invalidSchema : Boolean
_propCage : Object
_trapProperties : Boolean
_calcFields : Object
__itemClassName : String
_iterator : ValueListIterator
__schemaXML : XML
__items : Array
__toProperties : Object
__readOnly : Boolean
__curItem : Object
__logChanges : Boolean
__schema : Object
super_addBinding : Function
f : mx.data.encoders.DateToNumber

Instance methods

addBinding (aBinding:Binding) : Void
- Used to override the default event that the binding is listening for.
addEventListener (name:String, handler) : Void
- Adds the event listener specified to this DataSet.
addSort (name:String, propList:Array, options:Number) : Void
- Creates a new ascending or descending index for the default iterator (iterator) using
addItem (transferObj:Object) : Boolean
- Adds the specified transfer object to the collection for management.
addItemAt (index:Number, transferObj:Object) : Boolean
- Adds the specified transfer object to the collection for
applyUpdates : Void
- Dispatches the "deltaPacketChanged" event.
clear : Void
- Clears the transfer objects from this collection that are visible by the current iterator.
createItem (itemData:Object) : Object
- Creates a transfer object that is not associated with this collection.
disableEvents : Void
- Disables events for the dataset.
dispatchEvent (eventObj:Object) : Void
- Provides pass through for data binding's event mechanism which will call on the real
enableEvents : Void
- Enables events for the dataset after disableEvents() has been called.
find (values:Array) : Boolean
- This method will find a transfer object with the specified properties within the collection,
findFirst (values:Array) : Boolean
- This method will find the first transfer object with the specified properties within the collection,
findLast (values:Array) : Boolean
- This method will find the last transfer object with the specified properties within the collection,
first : Void
- Positions the default iterator on the first transfer object in the collection and assigns
getItemId (index:Number) : String
- Returns the identifier of the current transfer object within the collection.
getIterator : ValueListIterator
- Returns a new iterator (iterator) for this DataSet.
getLength : Number
- Total number of transfer objects viewable within this collection based on the
hasNext : Boolean
- Indicates whether or not the default iterator is at the end of the collection.
hasPrevious : Boolean
- Indicates whether or not the default iterator is at the beginning of the collection.
hasSort (name:String) : Boolean
- Returns true if the specified sort name is already in use.
isEmpty : Boolean
- Indicates if the dataset is empty i.e.
clearDelta (id:String) : Boolean
- Clears the specified delta item from the current list.
changesPending : Boolean
- Indicates if any modifications to this collection or any transfer object within the
locateById (id:String) : Boolean
- Moves the current iterator to the transfer object specified by the id.
last : Void
- Positions the default iterator on the last transfer object in the collection
loadFromSharedObj (objName:String, localPath:String) : Void
- Loads all of the relevant data needed to restore this DataSet collection
next : Void
- Positions the default iterator on the next item in the collection and assigns its
previous : Void
- Moves to the previous item in the collection and assigns its proxy to the DataSet.
propertyModified (propName:String, subProp:Boolean, typeInfo:Object) : Void
- Inidcates when a property has been modified on this DataSet via data binding.
removeAll : Void
- This method will clear all of the items in the collection regardless of what the
removeEventListener (name:String, handler) : Void
- Removes the event listener specified from this DataSet.
removeItem (item:Object) : Boolean
- Removes the specified transfer object from the collection.
removeItemAt (index:Number) : Boolean
- Removes the transfer object from the collection at the specified index.
removeRange : Void
- Removes the current range settings for the default iterator.
removeSort (name:String) : Void
- Removes the specified sort from this DataSet if it exists and is not reserved.
skip (offset:Number) : Object
- Moves the default iterator by the amount indicated by offset and assigns the
saveToSharedObj (objName:String, localPath:String) : Void
- Saves all of the relevant data needed to restore this DataSet collection from a
setIterator (newIterator:ValueListIterator) : Void
- Assigns the DataSet's current iterator to the specified value.
setRange (startValues:Array, endValues:Array) : Void
- Sets the end points for the default iterator.
useSort (sortName:String, options:Number) : Void
- Switches the index for the default iterator to the one specified, should it exist.
addProxy : Void
- Adds the proxy information to this DataSet allowing for mutations to be tracked
addSortInfo (fld:DataType, name:String, index:Number) : Void
- Hangs some sort information off of the field so that it can be used later to determine if an
applyResolvePacket (d:Delta, resPckt:Array, dpItems:Array) : Void
- Collects messages from the delta specified, applies updates to existing items if there are no messages
buildSchema : Void
- Creates the XML schema representation of the author-time schema information.
createDelta (td:Object) : Delta
- Creates and returns a new delta instance from the anonymous object specified.
checkReadOnly : Void
- Throws an exception if the DataSet is read-only.
checkSchema : Void
- Throws an exception if the DataSet has not had any schema defined.
createProperties : Void
- Creates the transfer object properties list exposed by the specified schema information currently found
convertToRaw (values:Object, option:Number) : Object
- Converts the specified values into their raw representation, i.e.
convertArrayToRaw (values) : Object
- Converts the specified values into their raw representation, i.e.
convertObjectToRaw (values, option:Number) : Object
- Converts the specified values into their raw representation, i.e.
decodeItem (item:Object) : Object
- Returns an anonymous object that has the properties of dataset schema
defaultSchema (obj:Object) : Void
- Attempts to create schema for this DataSet by introspection of the specified
decodeValue (fieldName:String, value)
- Decodes the specified value using the current schema and returns the decoded value
encodeValue (fieldName:String, value)
- Encodes the specified value using the current schema and returns the decoded value
findDelta (id:String) : Delta
internalDispatchEvent (type:String, params:Object) : Object
- Creates the specified event and dispatches it with the additional parameters specified attached
getDataProviderItem (item:Object, desiredTypes:Object) : Object
- Returns a new object instance that represents the specified item as it is to be viewed
getEditingData (fieldName:String, item:Object, desiredTypes:Object)
- Returns the editing data for the specified field, item, and desired types information.
getDisplayValue (propName:String, index:Number) : String
- Returns the display value of the specified field at the given index.
getCurrentItem : Object
- This method will resync the iterator to a point of getting an item from it
getInternalIndex (index:Number) : Number
- Returns a re-mapped index number based on the current index that points to the
getKeyInfo : Object
- This method returns the key information for a delta packet.
getModDeltaInfo (id:String) : Delta
- Looks for an existing delta with the specified id, or creates one, adds it and
getPropertyValue (name:String) : Object
- Returns the current value of the specified property.
getResolverFieldList : Object
- Returns a list of fields/properites of this DataSet that can be sent to the server, i.e.
getDPTransId : String
- Reutrn's an application wide unique delta packet transaction identifier.
getSchemaObject (xmlInfo:XMLNode) : Object
- Returns an object that represents the XML node specified.
getSchemaXML (nodeName:String, info:Object) : String
- Used to create XML string based on the nested object structure passed in.
hasInvalidSchema : Boolean
- Returns true if no custom schema has been specified for this DataSet.
initCollection : Void
- Clears the collection items and the delta packet
internalAddItem (item:Object, index:Number, rebuildIndx:Boolean, pipeData:Boolean) : String
- Adds the item to the collection, assigns an id to it, and returns the new id.
internalClearDeltaPacket (transId:String) : Void
- Clears all of the current updates for this collection with the specified transaction id.
internalGetId : String
- Returns a unique id within this collection.
internalFirst : Object
- Moves the current iterator to the first item and returns the first item
internalRemoveItem (item:Object) : Boolean
- Removes the specified item from this collection should it exist.
initIterators : Void
- Deletes all of the managed iterators and creates a new default iterator.
isValidElement (el:Object) : Boolean
- Returns is the specified element is valid and can be used.
logAddItem (item:Object, piped:Boolean, id:Object) : Void
- Logs an add for the item.
logRemoveItem (item:Object, piped:Boolean, id:Object) : Void
- Logs a remove for the item.
rebuildItemIndexById : Void
- Rebuilds the item index, based on the modified items list.
removeProxy : Void
- Removes all of the previous proxy information from this DataSet instance.
resyncIterators (info:Object) : Void
- Resync's all of the iterators so that they will reflect the latest changes
setFieldValue (fld:DataType, value, typeInf:Object) : Void
- Sets the value for the specified field using the setAsXXX method on the field as appropriate
setPropertyValue (name:String, value:Object) : Void
- Sets the specified property value for the current item in this DataSet.
removeSortInfo (fld:DataType, name:String) : Void
- Removes the associated sorting information for the sort name and field specified.
removeDelta (d:Delta) : Boolean
- Removes the specified item from the delta items and optimized detla items lists
__resolve (methodName:String) : Function
- Used to provide the marshalling of property and method access to the delta packet.
updateItem (d:Delta) : Void
- This method updates an item within this dataset based on the delta specified.

Constructor

DataSet

function DataSet (

)

Constructs a new empty DataSet.

Author:

Jason Williams

Throws:

mx.data.components.datasetclasses.DataSetError

Example:

var myDataSet: DataSet;
try {
myDataSet = new DataSet();
myDataSet.schema = new XML( "<properties><property name=\"test\" type=\"string\" size=\"35\"/></properties>" );
}
catch( dsError ) {
if( dsError instanceof DataSetError ) {
alert( dsError.messages[0] );
}
}

Class properties

All

static private All:Number = 1

(read)

DefaultIterator

static private DefaultIterator:String = "__default__"

(read)

ItemId

static private ItemId:String = "__ID__"

(read)

KeysOnly

static private KeysOnly:Number = 0

(read)

Instance properties

__curItem

private __curItem:Object

(read)

__itemClassName

private __itemClassName:String

(read)

__items

private __items:Array

(read)

__logChanges

private __logChanges:Boolean

(read)

__readOnly

private __readOnly:Boolean

(read)

__schema

private __schema:Object

(read)

__schemaXML

private __schemaXML:XML

(read)

__toProperties

private __toProperties:Object

(read)

_allowReslv

private _allowReslv:Boolean = false

(read)

_calcFields

private _calcFields:Object

(read)

_defValues

private _defValues:Object

(read)

_deltaItems

private _deltaItems:Array

(read)

_deltaPacket

private _deltaPacket:DeltaPacket

(read)

_dpIndexByTransId

private _dpIndexByTransId:Array

(read)

_dpTransIdCount

private _dpTransIdCount:Number

(read)

_enableEvents

private _enableEvents:Number

(read)

_event

private _event:Object

(read)

_eventDispatcher

private _eventDispatcher:Object

(read)

_filtered

private _filtered:Boolean

(read)

_filterFunc

private _filterFunc:Function

(read)

_fldValObj

private _fldValObj:Object

(read)

_hasDelta

private _hasDelta:Number

(read)

_invalidSchema

private _invalidSchema:Boolean

(read)

_itemClass

private _itemClass:Function

(read)

_itemIndexById

private _itemIndexById:Array

(read)

_iterator

private _iterator:ValueListIterator

(read)

_iterators

private _iterators:Array

(read)

_lastTransId

private _lastTransId:String

(read)

_loading

private _loading:Boolean

(read)

_optDeltaItems

private _optDeltaItems:Array

(read)

_propCage

private _propCage:Object

(read)

_srcSchema

private _srcSchema:Object

(read)

_trapProperties

private _trapProperties:Boolean

(read)

currentItem

currentItem:Object

(read)

Read-only; The current transfer object the default iterator is pointing to.

Example:

var emp:Employee = employees.currentItem;
employees.removeItem();
janitors.addItem( emp );

dataProvider

dataProvider:Object

(read,write)

DataProvider interface for this dataset. This property is added to support the
UI controls like the list and data grid.

Example:

// hookup the data grid
myGrid.dataProvider = myDataSet.dataProvider;

Component metadata:

Bindable	type: "DataProvider"

deltaPacket

deltaPacket:DeltaPacket

(read,write)

Contains all of the mutation operations that have been made to this
collection and its transfer objects. If no mutations have been made
this property will be null.

Example:

// convert the delta packet into XML
var delta:DeltaPacket = eventObj.deltaPacket;
var dpCursor:Iterator = delta.getIterator();
var item:Delta=dpCursor.next();
while( dpCursor.hasNext()) {
// ...
}

Component metadata:

Bindable
ChangeEvent	"deltaPacketChanged"

f

private f:mx.data.encoders.DateToNumber

(read)

filtered

filtered:Boolean

(read,write)

Indicates if the default iterator is filtered. i.e. some of the transfer objects will
not show up during iteration. This value is associated with the iterator, so an
assignment of an iterator may change the value of this property.

filterFunc

filterFunc:Function

(read,write)

Method used to filter the default iterator's view of this collection's transfer objects.
This method will get called for each item in the collection under the following conditions
when the filtered property is set to true:

The item has not been filtered previously

A property of an item has been modified

The filter method is associated with each iterator, so an assignment of an iterator may
change the value of this property.

getField

getField:Function

(read)

itemClassName

itemClassName:String

(read,write)

Used to construct an instance of the specified class during a createItem() call.
See addItem() and createItem() methods for more detail on how item creation works.

Component metadata:

Inspectable	defaultValue: ""

items

items:Array

(read,write)

Collection of transfer objects for this DataSet.

Example:

// Create a new collection of transfer objects with only two fields
myDataSet.schema = new XML( " var recData = new Array();
for( var i:Number=0; i<100; i++ )
recDat[i]= {id:i, name:String("name"+i)};
myDataSet.items = recData;

Component metadata:

Bindable

length

length:Number

(read)

Total number of transfer objects viewable within this collection based on the
current iterator.

Example:

// alert the user if there are not enough entries made
if( myDataSet.length < MIN_REQUIRED )
alert( "Not enough entries have been made. You need at least "+MIN_REQUIRED );

logChanges

logChanges:Boolean

(read,write)

Indicates if changes should be tracked and recorded in the DeltaPacket.

Example:

myDataSet.logChanges = false;
myDataSet.clear();
myDataSet.logChanges = true;

Component metadata:

Inspectable	defaultValue: "true"

properties

properties:Object

(read)

List of all of the exposed properties for any transfer object within this collection.
This property provides the for in loop discoverability of the defined properties (fields)
on this DataSet for each transfer object.

readOnly

readOnly:Boolean

(read,write)

Indicates if this collection is updatable. Setting this property to true will
prevent updates to this collection.

Example:

// don't allow updates to this collection
myDataSet.readOnly = true;
// the following code will throw an exception
myDataSet.price = 15;

Component metadata:

Inspectable	defaultValue: "false"

refreshFromSources

refreshFromSources:Function

(read)

schema

schema:XML

(read,write)

Schema in XML format for this DataSet. The schema can be setup using the
author time UI or this property at runtime. The schema has the following XML format:

&lt?xml version="1.0"?&gt;
  &lt;properties>
      &lt;property name="data"&gt;
          &lt;type name="Boolean" value="test" label="test2" uicontrol="it"&gt;
              &lt;encoder className="mx.data.encoders.Boolean"&gt;
                  &lt;settings falseStrings="false,no,non,nyet,f,n,0,nope" trueStrings="true,yes,oui,da,t,y,1,yup"/&gt;
              &lt;/encoder>
              &lt;formatter className="mx.data.formatters.NumberFormatter"&gt;
                  &lt;settings precision="2" /&gt;
              &lt;/formatter>
              &lt;kind className="mx.data.kinds.ForeignKey"&gt;
                  &lt;settings dataset="this" indexColumn="test" /&gt;
              &lt;/kind>
              &lt;validation className="mx.data.types.Num"&gt;
                  &lt;settings int="0" /&gt;
              &lt;/validation>
          &lt;/type>
      &lt;/property>
      &lt;proeprty> ... &lt;/property>
          ...
  &lt;/properties>

selectedIndex

selectedIndex:Number

(read,write)

Indicates the selected index of the current iterator within the DataSet.

Component metadata:

Bindable
ChangeEvent	"iteratorScrolled","modelChanged"

super_addBinding

private super_addBinding:Function

(read)

Instance methods

__resolve

private function __resolve (

methodName:String) : Function

Used to provide the marshalling of property and method access to the delta packet.

Parameters:

methodName:

String name of method being called

Returns:

Function that is to be called

addBinding

function addBinding (

aBinding:Binding) : Void

Used to override the default event that the binding is listening for.

Parameters:

aBinding:

Binding that is being associated with this component

addEventListener

function addEventListener (

name:String, handler) : Void

Adds the event listener specified to this DataSet.

Parameters:

name :

String containing the name of the event to listen for

handler:

Object/Function to fire when dispatching the event

addItem

function addItem (

transferObj:Object) : Boolean

Adds the specified transfer object to the collection for management. The location of the item depends
on whether an index has been specified or is in use for the default iterator. If no index is in use the
item specified will be added to the start of the collection.

Parameters:

[transferObj]:

Object transfer object to manage within this DataSet collection

Returns:

Boolean indicating if the item was added.

Example:

myDataSet.addItem( myDataSet.createItem());

addItemAt

function addItemAt (

index:Number, transferObj:Object) : Boolean

Adds the specified transfer object to the collection for
management at the specified location.

Parameters:

index :

Number contaning the desired position within the collection

transferObj:

Object transfer object to manage within this DataSet collection

Example:

myDataSet.addItemAt( 10, myDataSet.createItem());

addProxy

private function addProxy (

) : Void

Adds the proxy information to this DataSet allowing for mutations to be tracked
on the transfer objects stored within its collection.

addSort

function addSort (

name:String, propList:Array, options:Number) : Void

Creates a new ascending or descending index for the default iterator (iterator) using
the specified properties for a transfer object. The new index is automatically assigned
to the default iterator after it is created and stored in the indexes collection for
later retrieval.

Parameters:

name :

String containing the name of the index

propList :

Array containing a list of all of the property names to index

[options]:

Number integer value indicating what options are used for this index.
This value must be one of the following (multiple values can be or'ed together):

DataSetIterator.Descending

DataSetIterator.Unique

DataSetIterator.CaseInsensitive

tiptext Sorts the items in the collection
helpid 1522

Example:

myDataSet.addSort( "id", ["name", "id"], DataSetIterator.Unique );
// find the transfer object identified by "Bobby" and 105
if( myDataSet.find( [ "Bobby", 105 ] ))
bkmkTeachersPet = myDataSet.iterator.clone();
else
bkmkTeachersPet = null;
if( myDataSet.find( [ "Joey", 299 ] ))
bkmkClassClown = myDataSet.iterator.clone();
else
bkmkClassClown = null;
//Now go back to the Teacher's Pet transfer object
if( bkmkTeachersPet != null )
myDataSet.iterator = bkmkTeachersPet;

//Now dump the iterators since we don't need them
bkmkTeachersPet = null;
bkmkClassClown = null;
myDataSet.addSort( "rank", ["classRank"], DataSetIteratorIndex.Descending | DataSetIteratorIndex.Unique | DataSetIteratorIndex.CaseInsensitive );
myDataSet.removeSort( "id" );

addSortInfo

private function addSortInfo (

fld:DataType, name:String, index:Number) : Void

Hangs some sort information off of the field so that it can be used later to determine if an
iterator should be recalculated if this field is changed.

Parameters:

fld :

DataType field to add information to

name :

String containing the name of the associated iterator

index:

Number indicating the position within the iterator sort specification, 0 being
the primary position.

applyResolvePacket

private function applyResolvePacket (

d:Delta, resPckt:Array, dpItems:Array) : Void

Collects messages from the delta specified, applies updates to existing items if there are no messages
and updates the current deltapacket based on the current operation. For example
- Add and remove operations with errors will be added to the optimized delta packet, so they can
be resent to the server.
- Modifications to existing items with errors can be ignored since these will result in new mods
- Updates existing items that do not have errors, in the case where key values have been updated
from the server.

Parameters:

d :

Delta item within the packet that is currently being resolved

resPckt:

Array of message objects

transId:

String associated transaction id

applyUpdates

function applyUpdates (

) : Void

Dispatches the "deltaPacketChanged" event. The purpose of this method is to notify listeners
that they should pickup the latest delta packet from this DataSet.
NOTE: if events are disable via disableEvents() this method does nothing

buildSchema

private function buildSchema (

) : Void

Creates the XML schema representation of the author-time schema information.

changesPending

function changesPending (

) : Boolean

Indicates if any modifications to this collection or any transfer object within the
collection has changes pending that have not been collected by an access to the
deltaPacket property.

Returns:

Boolean true if the dataset is currently in edit or insert mode.

Example:

save_btn.setEnabled( myDataSet.changesPending());

checkReadOnly

private function checkReadOnly (

) : Void

Throws an exception if the DataSet is read-only.

checkSchema

private function checkSchema (

) : Void

Throws an exception if the DataSet has not had any schema defined.

clear

function clear (

) : Void

Clears the transfer objects from this collection that are visible by the current iterator. If logChanges
is true then this operation will create remove entries in the delta packet for each item within the
collection that is removed.

Example:

// delete all the transfer objects within this collection
myDataSet.logChanges= true;
myDataSet.clear();

clearDelta

function clearDelta (

id:String) : Boolean

Clears the specified delta item from the current list. This method is for use with the reconcile updates
event and allows the developer to remove a pending change should that change need to be discarded.

Parameters:

id:

String containing the id of the delta to remove

Returns:

Boolean indicating if the specified item could be removed.

convertArrayToRaw

private function convertArrayToRaw (

values) : Object

Converts the specified values into their raw representation, i.e. values that can be
compared against property values on transfer objects within this collection.

Parameters:

values:

Array of values to use for conversion

option:

Number indicating what to convert, valid values are KeysOnly and All

Returns:

Object of the specified values converted

convertObjectToRaw

private function convertObjectToRaw (

values, option:Number) : Object

Converts the specified values into their raw representation, i.e. values that can be
compared against property values on transfer objects within this collection.

Parameters:

values:

Object of values to use for conversion

option:

Number indicating what to convert, valid values are KeysOnly and All

Returns:

Object of the specified values converted

convertToRaw

private function convertToRaw (

values:Object, option:Number) : Object

Converts the specified values into their raw representation, i.e. values that can be
compared against property values on transfer objects within this collection.

Parameters:

values:

Object/Array of values to use for conversion

option:

Number indicating what to convert, valid values are KeysOnly and All

Returns:

Object of the specified values converted

createDelta

private function createDelta (

td:Object) : Delta

Creates and returns a new delta instance from the anonymous object specified.

Parameters:

td:

Object containing the relevant properties for construction of a new Delta

Returns:

new delta instance

createItem

function createItem (

itemData:Object) : Object

Creates a transfer object that is not associated with this collection. If there are listeners
for the newItem event this method will defer creation of a transfer object to those listeners,
otherwise this method will create a new instance of a transfer object based on the class name
specified in the itemClass property.

Parameters:

itemData:

Object [optional] data associated with the transfer object

Returns:

Object newly constructed transfer object

Example:

myDataSet.createItem( new XML( "<customer>..." ));

createProperties

private function createProperties (

) : Void

Creates the transfer object properties list exposed by the specified schema information currently found
in the __schema property. If bindings currently exist this method should try to map the new properties to
any existing bindings that will support them.

decodeItem

private function decodeItem (

item:Object) : Object

Returns an anonymous object that has the properties of dataset schema
as run through the data binding pipeline.

Parameters:

item:

Object containing the properties that need to be piped

Returns:

Object containing the properties on the DataSet

decodeValue

private function decodeValue (

fieldName:String, value)

Decodes the specified value using the current schema and returns the decoded value

Parameters:

fieldName:

String containing the name of the property on the DataSet that has the
appropriate pipeline for decoding the value specified

value :

new value to decode

Returns:

newly decoded value

defaultSchema

private function defaultSchema (

obj:Object) : Void

Attempts to create schema for this DataSet by introspection of the specified
object's properties.

Parameters:

obj:

Object to derive the schema from

Author:

Jason Williams

disableEvents

function disableEvents (

) : Void

Disables events for the dataset. After this method has been called, no events will be dispatched.
Events can be re-enabled by calling the enableEvents() method. This method may be called multiple
times, and enableEvents() must be called an equal number of times to re-enable the dispatching of
events.

Example:

if( !myDataSet.readOnly) {
//Disable events so the dataset won't try to refresh controls and
//slow everything down
myDataSet.disableEvents();
myDataSet.last();
while( myDataSet.hasPrevious()) {
var price = myDataSet.price;
price = price * 0.5; //Everythings 50% off!
myDataSet.price = price;
myDataSet.previous();
}
//Tell the dataset it's time to update the controls now
myDataSet.enableEvents();
}

dispatchEvent

function dispatchEvent (

eventObj:Object) : Void

Provides pass through for data binding's event mechanism which will call on the real
internalDispatch method.

Parameters:

eventObj:

Object event to dispatch.

enableEvents

function enableEvents (

) : Void

Enables events for the dataset after disableEvents() has been called. While events are disabled,
no events will be fired and no controls will be updated when changes are made or the dataset is
scrolled to another record. enableEvents() must be called an equal or greater number of times than
disableEvents() was called to re-enable events for the dataset.

Example:

if( !myDataSet.readOnly) {
//Disable events so the dataset won't try to refresh controls and
//slow everything down
myDataSet.disableEvents();
myDataSet.last();
while( myDataSet.hasPrevious()) {
var price = myDataSet.price;
price = price * 0.5; //Everythings 50% off!
myDataSet.price = price;
myDataSet.previous();
}
//Tell the dataset it's time to update the controls now
myDataSet.enableEvents();
}

encodeValue

private function encodeValue (

fieldName:String, value)

Encodes the specified value using the current schema and returns the decoded value

Parameters:

fieldName:

String containing the name of the property on the DataSet that has the
appropriate pipeline for decoding the value specified

value :

new value to encode

Returns:

newly Encoded value

find

function find (

values:Array) : Boolean

This method will find a transfer object with the specified properties within the collection,
assign its proxy to the DataSet and return true. If the item can not be found no change to the
DataSet proxy will be made and the method will return false.
If the current index is not unique then the transfer object found is non deterministic. If it is
important to find the first or last occurrance of a tranfer object in a non-unique index use the
findFirst() or findLast().
The values specified must be in the same order as the fields of the current index field list. e.g.
If fields 2, 4, and 5 are the fields in the current index, the values specified should be ordered
such that the first value in the array will be compared against the first field in the index's
fields list (field2) and so on. Conversion of the data specified will be performed based on the
underlying field's type and that specified in the array. e.g. If the value specified is ["05-02-02"],
the underlying date field will be used to convert the value using the date's setAsString() method. If
the actual value specified was [new Date().getTime()], then the date's setAsNumber() method would
be used.

Parameters:

values:

Array of one or more field values that should be found within the current index.

Returns:

Boolean true if found false if not

Example:

var bkmkTeachersPet:DataSetIterator = null;
var bkmkClassClown:DataSetIterator = null;
myDataSet.addSort( "id", ["name", "id"] );
// find the transfer object identified by "Bobby" and 105
if( myDataSet.findFirst( [ "Bobby", 105 ] ))
bkmkTeachersPet = myDataSet.iterator.clone( "teachersPet" );

if( myDataSet.findFirst( [ "Joey", 299 ] ))
bkmkClassClown = myDataSet.iterator.clone( "classClown" );
//Now go back to the Teacher's Pet transfer object
if( bkmkTeachersPet != null )
myDataSet.iterator = bkmkTeachersPet;

//Now dump the iterators since we don't need them
bkmkTeachersPet = null;
bkmkClassClown = null;
myDataSet.addSort( "rank", ["classRank"], DataSetIteratorIndex.Descending | DataSetIteratorIndex.Unique | DataSetIteratorIndex.CaseInsensitive );
myDataSet.removeSort( "id" );

findDelta

private function findDelta (

id:String) : Delta

findFirst

function findFirst (

values:Array) : Boolean

This method will find the first transfer object with the specified properties within the collection,
assign its transfer object proxy to the DataSet and return true. If the transfer object can not be
found no change will be made to the DataSet and false will be returned.
The values specified must be in the same order as the fields of the current index field list. e.g.
If fields 2, 4, and 5 are the fields in the current index, the values specified should be ordered
such that the first value in the array will be compared against the first field in the index's fields
list (field2) and so on. Conversion of the data specified will be performed based on the underlying
field's type and that specified in the array. e.g. If the value specified is ["05-02-02"], the
underlying date field will be used to convert the value using the date's setAsString() method. If
the actual value specified was [new Date().getTime()], then the date's setAsNumber() method would
be used.

Parameters:

values:

Array of one or more field values that should be found within the current index.

Returns:

Boolean true if found or false if not

Example:

var bkmkTeachersPet:DataSetIterator = null;
var bkmkClassClown:DataSetIterator = null;
myDataSet.addSort( "id", ["name", "id"] );
// find the transfer object identified by "Bobby" and 105
if( myDataSet.findFirst( [ "Bobby", 105 ] ))
bkmkTeachersPet = myDataSet.getItemID();

if( myDataSet.findFirst( [ "Joey", 299 ] ))
bkmkClassClown = myDataSet.iterator.clone();
//Now go back to the Teacher's Pet transfer object
if( bkmkTeachersPet != null )
myDataSet.iterator = bkmkTeachersPet;

//Now dump the iterators since we don't need them
bkmkTeachersPet = null;
bkmkClassClown = null;
myDataSet.addSort( "rank", ["classRank"], DataSetIteratorIndex.Descending | DataSetIteratorIndex.Unique | DataSetIteratorIndex.CaseInsensitive );
myDataSet.removeSort( "id" );

findLast

function findLast (

values:Array) : Boolean

This method will find the last transfer object with the specified properties within the collection,
assign its transfer object proxy to the DataSet and return true. If the transfer object can not be
found false will be returned and no change to the DataSet will be made.
The values specified must be in the same order as the fields of the current index field list. e.g.
If fields 2, 4, and 5 are the fields in the current index, the values specified should be ordered
such that the first value in the array will be compared against the first field in the index's
fields list (field2) and so on. Conversion of the data specified will be performed based on the
underlying field's type and that specified in the array. e.g. If the value specified is ["05-02-02"],
the underlying date field will be used to convert the value using the date's setAsString() method.
If the actual value specified was [new Date().getTime()], then the date's setAsNumber() method would
be used.

Parameters:

values:

Array of one or more field values that should be found within the current index.

Returns:

Boolean true if found or false if not

Example:

var bkmkTeachersPet:DataSetIterator = null;
var bkmkClassClown:DataSetIterator = null;
myDataSet.addSort( "id", ["name", "id"] );
// find the transfer object identified by "Bobby" and 105
if( myDataSet.findFirst( [ "Bobby", 105 ] ))
bkmkTeachersPet = myDataSet.getIterator();

if( myDataSet.findFirst( [ "Joey", 299 ] ))
bkmkClassClown = myDataSet.getIterator();
//Now go back to the Teacher's Pet transfer object
if( bkmkTeachersPet != null )
myDataSet.iterator = bkmkTeachersPet;

//Now dump the iterators since we don't need them
bkmkTeachersPet = null;
bkmkClassClown = null;
myDataSet.addSort( "rank", ["classRank"], DataSetIteratorIndex.Descending | DataSetIteratorIndex.Unique | DataSetIteratorIndex.CaseInsensitive );
myDataSet.removeSort( "id" );

first

function first (

) : Void

Positions the default iterator on the first transfer object in the collection and assigns
its proxy to the DataSet.

Example:

if( !myDataSet.readOnly ) {
//Disable events so the dataset won't try to refresh controls and
//slow everything down
myDataSet.disableEvents();
myDataSet.first();
while( myDataSet.hasNext()) {
var price = myDataSet.price;
price = price * 0.5; //Everythings 50% off!
myDataSet.price = price;
myDataSet.next();
}
//Tell the dataset it's time to update the controls now
myDataSet.enableEvents();
}

getCurrentItem

private function getCurrentItem (

) : Object

This method will resync the iterator to a point of getting an item from it

Returns:

Object transfer object potentially null, however all attempts are
made to avoid this.

getDataProviderItem

private function getDataProviderItem (

item:Object, desiredTypes:Object) : Object

Returns a new object instance that represents the specified item as it is to be viewed
by the outside world.

Parameters:

item :

Object current transfer object

desiredTypes:

Object of strings specifying what type is required for a column

Returns:

Object containing the properties as they should appear to the outside world.

getDisplayValue

private function getDisplayValue (

propName:String, index:Number) : String

Returns the display value of the specified field at the given index. This method
is used by the Data Provider API.

Parameters:

propName:

String containing the name of the property to access

index :

Number index of the desired transfer object

Returns:

String containing the formatted display value

getDPTransId

private function getDPTransId (

) : String

Reutrn's an application wide unique delta packet transaction identifier.
This id is used with DeltaPackets to determine if a packet is a server
response and change the handling accordingly.

Returns:

String containing a unique id which includes the date and time and
has the following format 47126228642:Thu Jun 19 23:43:25 GMT-0700 2003

getEditingData

private function getEditingData (

fieldName:String, item:Object, desiredTypes:Object)

Returns the editing data for the specified field, item, and desired types information.

Parameters:

fieldName :

String containing the field to extract the editing data for

item :

Object transfer object to get the field data from

desireTypes:

Object containing the desired types of editing data

Returns:

the editing data value

getInternalIndex

private function getInternalIndex (

index:Number) : Number

Returns a re-mapped index number based on the current index that points to the
actual transfer object index within this dataset.

Parameters:

index:

Number externally visible index to be re-mapped into the current index

Returns:

Number containing the index within the DataSet's collection

getItemId

function getItemId (

index:Number) : String

Returns the identifier of the current transfer object within the collection.

Parameters:

index:

Number [optional] specifing the index of the item we want the ID for,
if not specified gets the id for the current item.

Returns:

String unique identifier for this item within this collection

Example:

var itemNo:Number = myDataSet.getItemID();
displayStatusBarMsg( "Employee id("+ itemNo+ ")");

getIterator

function getIterator (

) : ValueListIterator

Returns a new iterator (iterator) for this DataSet. The new iterator will be
a clone of the current iterator/iterator.

Returns:

ValueListIterator clone of the current iterator

Example:

myCursor:ValueListIterator = myDataSet.getIterator();
while( myCursor.hasNext()) {
myCursor.next();
//..
}

getKeyInfo

private function getKeyInfo (

) : Object

This method returns the key information for a delta packet. This method will be called to
provide appropriate key information for the items contained within the delta packet being
created. It will attempt to find a unique sorting, if an iterator with a unique sort is not found
it will use all properties as keys in the hopes that they will provide a unique way of identifing an item.

Returns:

Object containing the keylist and options.

getLength

function getLength (

) : Number

Total number of transfer objects viewable within this collection based on the
current iterator.

Example:

// alert the user if there are not enough entries made
if( myDataSet.getLength() < MIN_REQUIRED )
alert( "Not enough entries have been made. You need at least "+MIN_REQUIRED );

getModDeltaInfo

private function getModDeltaInfo (

id:String) : Delta

Looks for an existing delta with the specified id, or creates one, adds it and
returns the delta along with the cloned source should one have been created.

Parameters:

id:

String containing the id of the transfer object

Returns:

Delta requested

getPropertyValue

private function getPropertyValue (

name:String) : Object

Returns the current value of the specified property.

Parameters:

name:

String containing the name of the desired property

Returns:

Value of the property specified.

getResolverFieldList

private function getResolverFieldList (

) : Object

Returns a list of fields/properites of this DataSet that can be sent to the server, i.e.
it excludes fields that are calculated or virtual.

Returns:

Object containing properties with the field information.

getSchemaObject

private function getSchemaObject (

xmlInfo:XMLNode) : Object

Returns an object that represents the XML node specified. Each node in the XML is converted to
an object with properties, where the value of the property is either the attribute value or an
object which represnts a sub node in the XML tree.

Parameters:

xmlInfo:

XMLNode containing the XML data to convert to an object

Returns:

Object representing the given XML data.

getSchemaXML

private function getSchemaXML (

nodeName:String, info:Object) : String

Used to create XML string based on the nested object structure passed in. Scalar properties on objects become
attributes and objects become sub nodes.

Parameters:

nodeName:

String containing the name of the node

info :

Object sub object to explode into XML

Returns:

String containing an XML representation of the specified object structure.

hasInvalidSchema

private function hasInvalidSchema (

) : Boolean

Returns true if no custom schema has been specified for this DataSet.

Returns:

Boolean indicating if the schema has been setup at runtime.

hasNext

function hasNext (

) : Boolean

Indicates whether or not the default iterator is at the end of the collection.

Returns:

Boolean true if the default iterator is at the end of the collection

Example:

if( !myDataSet.readOnly) {
//Disable events so the dataset won't try to refresh controls and
//slow everything down
myDataSet.disableEvents();
myDataSet.first();
while( myDataSet.hasNext()) {
var price = myDataSet.price;
price = price * 0.5; //Everythings 50% off!
myDataSet.price = price;
myDataSet.next();
}
//Tell the dataset it's time to update the controls now
myDataSet.enableEvents();
}

hasPrevious

function hasPrevious (

) : Boolean

Indicates whether or not the default iterator is at the beginning of the collection.

Returns:

Boolean true if the default iterator is at the beginning of the collection

Example:

if( !myDataSet.readOnly ) {
//Disable events so the dataset won't try to refresh controls and
//slow everything down
myDataSet.disableEvents();
myDataSet.first();
while( myDataSet.hasNext()) {
var price = myDataSet.price;
price = price * 0.5; //Everythings 50% off!
myDataSet.price = price;
myDataSet.next();
}
//Tell the dataset it's time to update the controls now
myDataSet.enableEvents();
}

hasSort

function hasSort (

name:String) : Boolean

Returns true if the specified sort name is already in use.

Parameters:

name:

String containing the sort name to check for

Returns:

Boolean indicating if the sort name specified exists

initCollection

private function initCollection (

) : Void

Clears the collection items and the delta packet

initIterators

private function initIterators (

) : Void

Deletes all of the managed iterators and creates a new default iterator.

internalAddItem

private function internalAddItem (

item:Object, index:Number, rebuildIndx:Boolean, pipeData:Boolean) : String

Adds the item to the collection, assigns an id to it, and returns the new id.

Parameters:

item :

Object transfer object to add to the collection

index :

Number containing the location of the item within
the collection.

rebuildIndx:

Boolean indicating if the index by id should be rebuilt, if
many items are being added this improves performance.

pipeData :

Boolean indicating if the values in item should be run through the data binding pipeline
and the resulting object should be stored

Returns:

String containing the new id or empty string if not added

internalClearDeltaPacket

private function internalClearDeltaPacket (

transId:String) : Void

Clears all of the current updates for this collection with the specified transaction id.

Parameters:

transId:

[optional] String containing the packet's transaction id to clear, if none is specified this
will clear all delta.

internalDispatchEvent

private function internalDispatchEvent (

type:String, params:Object) : Object

Creates the specified event and dispatches it with the additional parameters specified attached
to the event as properties. If events have been disabled via disableEvent() this method will
return null, otherwise it will return the event after it has been dispatched.

Parameters:

type :

String containing the event type

params:

Object containing the additional properties to attach to the event

Returns:

Object event as dispatched or null if not dispatched.

internalFirst

private function internalFirst (

) : Object

Moves the current iterator to the first item and returns the first item

Returns:

Object first transfer object

internalGetId

private function internalGetId (

) : String

Returns a unique id within this collection.

Returns:

String unique id for this item within this collection

internalRemoveItem

private function internalRemoveItem (

item:Object) : Boolean

Removes the specified item from this collection should it exist. If the specified item
exists within the collection this method will ask listeners of "removeItem" to verify that
the item can be removed, if so it will then remove it, log the change (if needed) and notify
listeners of the removal.

Parameters:

item:

transfer object to remove from the collection

Returns:

Boolean true if item was removed, false otherwise

isEmpty

function isEmpty (

) : Boolean

Indicates if the dataset is empty i.e. length == 0.

Returns: