Adobe® Flex® 4 Language Reference
Hide Packages and Classes List |  Packages  |  Classes  |  Index  |  Appendixes
mx.data.messages 
DataMessage 
Packagemx.data.messages
Classpublic class DataMessage
InheritanceDataMessage Inheritance AsyncMessage Inheritance AbstractMessage Inheritance Object
Subclasses UpdateCollectionMessage

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

This message is used to transport an operation that occurred on a managed object or collection. This class of message is transmitted between clients subscribed to a remote destination as well as between server nodes within a cluster. The payload of this message describes all of the relevant details of the operation. This information is used to replicate updates and detect conflicts. The body of the message will contain different data based on the operation setting.



Public Properties
 PropertyDefined By
 Inheritedbody : Object
The body of a message contains the specific data that needs to be delivered to the remote destination.
AbstractMessage
 InheritedclientId : String
The clientId indicates which MessageAgent sent the message.
AbstractMessage
 Inheritedconstructor : Object
A reference to the class object or constructor function for a given object instance.
Object
 InheritedcorrelationId : String
Provides access to the correlation id of the message.
AsyncMessage
 Inheriteddestination : String
The message destination.
AbstractMessage
 Inheritedheaders : Object
The headers of a message are an associative array where the key is the header name and the value is the header value.
AbstractMessage
  identity : Object
Provides access to the identity map which defines the unique identity of the item affected by this DataMessage (relevant for create/update/delete but not fill operations).
DataMessage
 InheritedmessageId : String
The unique id for the message.
AbstractMessage
  operation : uint
Provides access to the operation/command of this DataMessage.
DataMessage
 Inheritedprototype : Object
[static] A reference to the prototype object of a class or function object.
Object
 Inheritedtimestamp : Number
Provides access to the time stamp for the message.
AbstractMessage
 InheritedtimeToLive : Number
The time to live value of a message indicates how long the message should be considered valid and deliverable.
AbstractMessage
Public Methods
 MethodDefined By
  
Constructor.
DataMessage
  
[static] Provides a description of the operation specified.
DataMessage
 Inherited
Indicates whether an object has a specified property defined.
Object
  
Returns true if this is a create operation.
DataMessage
  
Returns true if this message is both an update and its list of property names has a length of zero.
DataMessage
 Inherited
Indicates whether an instance of the Object class is in the prototype chain of the object specified as the parameter.
Object
 Inherited
Indicates whether the specified property exists and is enumerable.
Object
 Inherited
Sets the availability of a dynamic property for loop operations.
Object
 Inherited
Returns the string representation of this object, formatted according to locale-specific conventions.
Object
 Inherited
Returns a string representation of the message.
AbstractMessage
 Inherited
Returns the primitive value of the specified object.
Object
Public Constants
 ConstantDefined By
  BATCHED_OPERATION : uint = 5
[static] This operation represents a set of batched operations to be performed as a single unit.
DataMessage
  COUNT_OPERATION : uint = 9
[static] This operation requests that a configured <count-method> be invoked on a remote destination.
DataMessage
  CREATE_AND_SEQUENCE_OPERATION : uint = 11
[static] This operation requests a create of the specified item from a remote destination.
DataMessage
  CREATE_OPERATION : uint = 0
[static] Indicates a create operation.
DataMessage
  DELETE_OPERATION : uint = 4
[static] This operation indicates that the specified item should be removed.
DataMessage
 InheritedDESTINATION_CLIENT_ID_HEADER : String = "DSDstClientId"
[static] Messages pushed from the server may arrive in a batch, with messages in the batch potentially targeted to different Consumer instances.
AbstractMessage
 InheritedENDPOINT_HEADER : String = "DSEndpoint"
[static] Messages are tagged with the endpoint id for the Channel they are sent over.
AbstractMessage
  FILL_OPERATION : uint = 1
[static] This operation requests that the remote destination create a sequence using the remote destination's adapter.
DataMessage
  FIND_ITEM_OPERATION : uint = 21
[static] Like the FILL_OPERATION but ensures only a single item is returned in the response array.
DataMessage
 InheritedFLEX_CLIENT_ID_HEADER : String = "DSId"
[static] This header is used to transport the global FlexClient Id value in outbound messages once it has been assigned by the server.
AbstractMessage
  GET_OPERATION : uint = 2
[static] This operation requests that the remote destination get a specific managed object based on its unique ID.
DataMessage
  GET_OR_CREATE_OPERATION : uint = 10
[static] This operation requests an item with the specified identity from the remote destination.
DataMessage
  GET_SEQUENCE_ID_OPERATION : uint = 12
[static] This operation requests a sequence id for a set of fill parameters.
DataMessage
  MULTI_BATCH_OPERATION : uint = 6
[static] This operation represents a set of operations to be performed as a single unit but which may contain multiple batched, create, update or delete operations that involve more than one destination, that is, more than one remote adapter.
DataMessage
  PAGE_ITEMS_OPERATION : uint = 20
[static] This operation indicates a request for a page of items specified by identities.
DataMessage
  PAGE_OPERATION : uint = 8
[static] This operation is used to retrieve a page of sequenced content that is delivered across several messages instead of in a single message.
DataMessage
 InheritedPRIORITY_HEADER : String = "DSPriority"
[static] Messages sent by a MessageAgent can have a priority header with a 0-9 numerical value (0 being lowest) and the server can choose to use this numerical value to prioritize messages to clients.
AbstractMessage
  RELEASE_COLLECTION_OPERATION : uint = 18
[static] This operation indicates that the client is no longer interested in receiving notification of operations performed on the specified collection.
DataMessage
  RELEASE_ITEM_OPERATION : uint = 19
[static] This operation indicates that the client is no longer interested in receiving notification of operations performed on the specified item.
DataMessage
  REMOTE_ALIAS : String = "flex.data.messages.DataMessage"
[static] Remote alias specifying the fully qualified server side class corresponding to this class.
DataMessage
 InheritedREMOTE_CREDENTIALS_CHARSET_HEADER : String = "DSRemoteCredentialsCharset"
[static] Messages that need to set remote credentials for a destination may also need to report the character-set encoding that was used to create the credentials String using this header.
AbstractMessage
 InheritedREMOTE_CREDENTIALS_HEADER : String = "DSRemoteCredentials"
[static] Messages that need to set remote credentials for a destination carry the Base64 encoded credentials in this header.
AbstractMessage
 InheritedREQUEST_TIMEOUT_HEADER : String = "DSRequestTimeout"
[static] Messages sent with a defined request timeout use this header.
AbstractMessage
 InheritedSTATUS_CODE_HEADER : String = "DSStatusCode"
[static] A status code can provide context about the nature of a response message.
AbstractMessage
 InheritedSUBTOPIC_HEADER : String = "DSSubtopic"
[static] Messages sent by a MessageAgent with a defined subtopic property indicate their target subtopic in this header.
AsyncMessage
  TRANSACTED_OPERATION : uint = 7
[static] This operation is similar to the MULTI_BATCH_OPERATION with the addition that the server should encapsulate the multiple batches of messages within a transaction.
DataMessage
  UNKNOWN_OPERATION : uint = 1000
[static] Code for an unknown operation type.
DataMessage
  UPDATE_BODY_CHANGES : uint = 0
[static] This constant is used to access the list of changed property names.
DataMessage
  UPDATE_BODY_NEW : uint = 2
[static] This constant is used to access the new value of a changed item.
DataMessage
  UPDATE_BODY_PREV : uint = 1
[static] This constant is used to access the previous value of the changed item.
DataMessage
  UPDATE_COLLECTION_OPERATION : uint = 17
[static] This operation is sent when a local or remote sequence has been modified by insert(s) or delete(s).
DataMessage
  UPDATE_OPERATION : uint = 3
[static] This operation indicates an update to data object has been performed.
DataMessage
Property Detail

identity

property
public var identity:Object

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

Provides access to the identity map which defines the unique identity of the item affected by this DataMessage (relevant for create/update/delete but not fill operations).

operation

property 
public var operation:uint

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

Provides access to the operation/command of this DataMessage. Operations indicate how the remote destination should process this message. To display a description of operation type use the getOperationAsString method.

See also

Constructor Detail

DataMessage

()Constructor
public function DataMessage()

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

Constructor.

Method Detail

getOperationAsString

()method
public static function getOperationAsString(op:uint):String

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

Provides a description of the operation specified. This method is used in toString() operations on this message.

Parameters

op:uint — The operation.

Returns
String — A String representation of the operation, or "unknown" if the operation is undefined.

Example  ( How to use this example )
         var msg:DataMessage = DataMessage(event.message);
         trace("Current operation -'"+
                DataMessage.getOperationAsString(msg.operation)+ "'.");
      

isCreate

()method 
public function isCreate():Boolean

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

Returns true if this is a create operation.

Returns
Boolean — Boolean indicating if this is a create operation.

See also

isEmptyUpdate

()method 
public function isEmptyUpdate():Boolean

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

Returns true if this message is both an update and its list of property names has a length of zero.

Returns
Boolean — Boolean indicating if this message is both an update and has a zero length list of property names.
Constant Detail

BATCHED_OPERATION

Constant
public static const BATCHED_OPERATION:uint = 5

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

This operation represents a set of batched operations to be performed as a single unit. Clients send a batch when DataService.commit() is invoked. All messages in the batch are intended for the same destination. The body property contains all of the messages that belong within this batch.

COUNT_OPERATION

Constant 
public static const COUNT_OPERATION:uint = 9

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

This operation requests that a configured <count-method> be invoked on a remote destination. The body property of the message will contain the arguments that should be passed to the remote destination when invoking the method. Clients send this operation when the DataService.count() method is invoked.

See also

CREATE_AND_SEQUENCE_OPERATION

Constant 
public static const CREATE_AND_SEQUENCE_OPERATION:uint = 11

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

This operation requests a create of the specified item from a remote destination. Clients send this operation when the DataService.createItem() method is invoked. The body property contains the item that should be created.

See also

CREATE_OPERATION

Constant 
public static const CREATE_OPERATION:uint = 0

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

Indicates a create operation. The body property will contain the new item to be created. When the operation is perfomed outside of an association a corresponding UpdateCollectionMessage will be delivered indicating the location/index the item should be added at. Clients will send this operation when a collection under managemenet of a DataService uses the IList.addItemAt(), IList.addItem() or IViewCursor.insert() methods.

See also

DELETE_OPERATION

Constant 
public static const DELETE_OPERATION:uint = 4

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

This operation indicates that the specified item should be removed. Clients will receive and send this operation when the item is removed. Clients will send this operation when DataService.deleteItem() or when a collection under managemenet of a DataService uses the IList.removeItemAt() or IViewCursor.remove() method.

See also

FILL_OPERATION

Constant 
public static const FILL_OPERATION:uint = 1

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

This operation requests that the remote destination create a sequence using the remote destination's adapter. The body property of the message will contain the fill arguments that should be used when creating the remote sequence.

FIND_ITEM_OPERATION

Constant 
public static const FIND_ITEM_OPERATION:uint = 21

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

Like the FILL_OPERATION but ensures only a single item is returned in the response array.

GET_OPERATION

Constant 
public static const GET_OPERATION:uint = 2

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

This operation requests that the remote destination get a specific managed object based on its unique ID. The identity property contains the desired object's identity.

See also

GET_OR_CREATE_OPERATION

Constant 
public static const GET_OR_CREATE_OPERATION:uint = 10

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

This operation requests an item with the specified identity from the remote destination. If no item exists with the identity, a create operation will be performed. Clients send this operation when the DataService.getItem() method is called with non-null default values for the item. The body property contains the default values of the item should it need to be created.

See also

GET_SEQUENCE_ID_OPERATION

Constant 
public static const GET_SEQUENCE_ID_OPERATION:uint = 12

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

This operation requests a sequence id for a set of fill parameters. If the sequence exists, it will not be recreated. If it does not exist, it will be recreated remotely. Clients send this operation when reconnecting to a remote destination or when failing over to a new node within a cluster. This operation is only used if the fetch attribute of the <reconnect> tag in the remote destination's configuration xml file is set to IDENTITY.

See also

MULTI_BATCH_OPERATION

Constant 
public static const MULTI_BATCH_OPERATION:uint = 6

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

This operation represents a set of operations to be performed as a single unit but which may contain multiple batched, create, update or delete operations that involve more than one destination, that is, more than one remote adapter. Clients send a multi-batch when DataService.commit() is invoked and there are associations configured for that destination. Messages in this batch will be sent to multiple destinations.

PAGE_ITEMS_OPERATION

Constant 
public static const PAGE_ITEMS_OPERATION:uint = 20

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

This operation indicates a request for a page of items specified by identities. This is operation is similar to a PAGE_OPERATION except the page index is not needed. Clients send this operation when fetching lazily loaded items for associations configured using one-to-many and many-to-many.

PAGE_OPERATION

Constant 
public static const PAGE_OPERATION:uint = 8

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

This operation is used to retrieve a page of sequenced content that is delivered across several messages instead of in a single message. It represents a request for a portion of a remote sequence. Clients send this operation when an item or property is requested that is not resident locally. This operation is only performed if either the <paging> tag under <network> tag has its enabled attribute set to true with a non-zero pageSize attribute or if an association is configured with the lazy attribute set to true.

RELEASE_COLLECTION_OPERATION

Constant 
public static const RELEASE_COLLECTION_OPERATION:uint = 18

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

This operation indicates that the client is no longer interested in receiving notification of operations performed on the specified collection. Clients send this operation when DataService.releaseCollection() is invoked or if DataService.fill() is invoked with an ArrayCollection which was previously filled with different parameters or if a one-to-many association's owning item is released.

See also

RELEASE_ITEM_OPERATION

Constant 
public static const RELEASE_ITEM_OPERATION:uint = 19

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

This operation indicates that the client is no longer interested in receiving notification of operations performed on the specified item. Clients send this operation when DataService.releaseItem() or ItemReference.releaseItem() is invoked.

See also

REMOTE_ALIAS

Constant 
public static const REMOTE_ALIAS:String = "flex.data.messages.DataMessage"

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

Remote alias specifying the fully qualified server side class corresponding to this class.

TRANSACTED_OPERATION

Constant 
public static const TRANSACTED_OPERATION:uint = 7

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

This operation is similar to the MULTI_BATCH_OPERATION with the addition that the server should encapsulate the multiple batches of messages within a transaction. This operation is only performed when the remote destination has the <use-transactions> tag under the <properties> tag within the destination configuration xml set with a value of true

UNKNOWN_OPERATION

Constant 
public static const UNKNOWN_OPERATION:uint = 1000

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

Code for an unknown operation type.

UPDATE_BODY_CHANGES

Constant 
public static const UPDATE_BODY_CHANGES:uint = 0

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

This constant is used to access the list of changed property names. Use this property with bracket notation on the body property of a message with an operation of UPDATE_OPERATION.

See also


Example  ( How to use this example )
         var msg:DataMessage = DataMessage(event.message);
         if (msg.operation == DataMessage.UPDATE_OPERATION)
         {
            // look at each change and display the old and new values
            var propertyNames:Array = msg.body[DataMessage.UPDATE_BODY_CHANGES];
            var newValues:Object = msg.body[DataMessage.UPDATE_BODY_NEW];
            var oldValues:Object = msg.body[DataMessage.UPDATE_BODY_PREV];
            var propertyName:String;
            for (var i:int=0; i<propertyNames.length; i++)
            {
                propertyName = propertyNames[i];
                trace("Property '"+ propertyName + "' was changed from '" +
                      oldValues[propertyName] + "' to '"+ newValues[propertyName] +
                      "'.");
            }
         }
      

UPDATE_BODY_NEW

Constant 
public static const UPDATE_BODY_NEW:uint = 2

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

This constant is used to access the new value of a changed item. Use this property with bracket notation on the body property of a message with an operation of UPDATE_OPERATION.

See also


Example  ( How to use this example )
         var msg:DataMessage = DataMessage(event.message);
         if (msg.operation == DataMessage.UPDATE_OPERATION)
         {
            // look at each change and display the old and new values
            var propertyNames:Array = msg.body[DataMessage.UPDATE_BODY_CHANGES];
            var newValues:Object = msg.body[DataMessage.UPDATE_BODY_NEW];
            var oldValues:Object = msg.body[DataMessage.UPDATE_BODY_PREV];
            var propertyName:String;
            for (var i:int=0; i<propertyNames.length; i++)
            {
                propertyName = propertyNames[i];
                trace("Property '"+ propertyName + "' was changed from '" +
                      oldValues[propertyName] + "' to '"+ newValues[propertyName] +
                      "'.");
            }
         }
      

UPDATE_BODY_PREV

Constant 
public static const UPDATE_BODY_PREV:uint = 1

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

This constant is used to access the previous value of the changed item. Use this property with bracket notation on the body property of a message with an operation of UPDATE_OPERATION.

See also


Example  ( How to use this example )
         var msg:DataMessage = DataMessage(event.message);
         if (msg.operation == DataMessage.UPDATE_OPERATION)
         {
            // look at each change and display the old and new values
            var propertyNames:Array = msg.body[DataMessage.UPDATE_BODY_CHANGES];
            var newValues:Object = msg.body[DataMessage.UPDATE_BODY_NEW];
            var oldValues:Object = msg.body[DataMessage.UPDATE_BODY_PREV];
            var propertyName:String;
            for (var i:int=0; i<propertyNames.length; i++)
            {
                propertyName = propertyNames[i];
                trace("Property '"+ propertyName + "' was changed from '" +
                      oldValues[propertyName] + "' to '"+ newValues[propertyName] +
                      "'.");
            }
         }
      

UPDATE_COLLECTION_OPERATION

Constant 
public static const UPDATE_COLLECTION_OPERATION:uint = 17

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

This operation is sent when a local or remote sequence has been modified by insert(s) or delete(s). This operation provides information about the locations of all insert(s) and delete(s) such that the state of the collection order can be restored. The body contains an Array of UpdateCollectionRanges indicating what items have been removed and added. Applying the update collection ranges in order will establish a consistent ordering of the items within the specified collection.

UPDATE_OPERATION

Constant 
public static const UPDATE_OPERATION:uint = 3

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

This operation indicates an update to data object has been performed. Clients will receive and send this operation when an item has been updated. The body property of the message is an Array containing specific information about the update that occured. The DataMessage.UPDATE_BODY_CHANGES location within the array contains an array of property names that were changed during the update. The DataMessage.UPDATE_BODY_NEW location within the array contains the object in its new modified state. The DataMessage.UPDATE_BODY_PREV location within the array contains the object in its state prior to the updates.


Example  ( How to use this example )
         var msg:DataMessage = DataMessage(event.message);
         if (msg.operation == DataMessage.UPDATE_OPERATION)
         {
            // look at each change and display the old and new values
            var propertyNames:Array = msg.body[DataMessage.UPDATE_BODY_CHANGES];
            var newValues:Object = msg.body[DataMessage.UPDATE_BODY_NEW];
            var oldValues:Object = msg.body[DataMessage.UPDATE_BODY_PREV];
            var propertyName:String;
            for (var i:int=0; i<propertyNames.length; i++)
            {
                propertyName = propertyNames[i];
                trace("Property '"+ propertyName + "' was changed from '" +
                      oldValues[propertyName] + "' to '"+ newValues[propertyName] +
                      "'.");
            }
         }