Packagecom.adobe.rtc.sharedModel
Classpublic class CollectionNode
InheritanceCollectionNode Inheritance flash.events.EventDispatcher
ImplementsISessionSubscriber
SubclassesRootCollectionNode

CollectionNode is the foundation class for building shared models requiring publish and subscribe messaging. All shared classes including the sharedModel, sharedManager, and many pods use CollectionNodes in order to manage messages, permissions, and roles.

At its core, a room can be logically seen as a group of CollectionNodes. For example, one CollectionNode is used in a chat pod, one within UserManager, and so on. CollectionNodes, in turn, are made up of nodes which can be thought of as permission-managed channels through which MessageItems are sent and received. Each node has its own NodeConfiguration which determines the permissions and storage policies sent through it.

CollectionNode is the main component class developers will create and interact with in order accomplish the following:

Only users with a role of UserRoles.OWNER may create and configure collectionNodes. Users of UserRoles.PUBLISHER can typically publish MessageItems, and UserRoles.VIEWER may subscribe and receive messages. As such, it's typically the case that an owner set up the required CollectionNodes in a room before publishers may publish or viewers may receive MessageItems.

CollectionNodes do not store the items which pass through them even if they are stored on the services. Developers are advised to listen to the ITEM_RECEIVE event and store details as needed in their own models.

See also

Developer Guide
com.adobe.rtc.messaging.NodeConfiguration
com.adobe.rtc.messaging.MessageItem
com.adobe.rtc.messaging.UserRoles


Public Properties
 PropertyDefined by
  connectSession : IConnectSession
The IConnectSession with which this component is associated.
CollectionNode
  isEmpty : Boolean
[read-only] Determines whether or not the collection is empty, that is, having no nodes
CollectionNode
  isSynchronized : Boolean
[read-only] Determines whether or not the collection is "up to state" with all previously stored items in its nodes.
CollectionNode
  nodeNames : Array
[read-only] Returns the names of all the nodes within this collection.
CollectionNode
  sharedID : String
The sharedID is the logical address of this collection within the room and must therefore be unique from all other CollectionNode names.
CollectionNode
  userRoles : Object
The complete set of roles for this collection described as {userID:role} pairs.
CollectionNode
Public Methods
 MethodDefined by
  
CollectionNode
  
canUserConfigure(p_userID:String, p_nodeName:String = null):Boolean
Determines whether a given user is allowed to configue this collection.
CollectionNode
  
canUserPublish(p_userID:String, p_nodeName:String):Boolean
Determines whether a given user is allowed to publish to a given node in this collection.
CollectionNode
  
canUserSubscribe(p_userID:String, p_nodeName:String = null):Boolean
Determines whether a given user is allowed to subscribe to this entire collection or a node within it.
CollectionNode
  
createNode(p_nodeName:String, p_nodeConfiguration:NodeConfiguration = null):void
Creates a new node in this collection; they are either optionally configured when created or accept the default configuration.
CollectionNode
  
fetchItems(p_nodeName:String, p_itemIDs:Array):void
Fetches the set of items specified by itemIDs from a given node.
CollectionNode
  
getExplicitUserRole(p_userID:String, p_nodeName:String = null):int
Gets the role of a given user for a node within this collection or the collection itself.
CollectionNode
  
getExplicitUserRoles(p_nodeName:String = null):Object
Gets the roles explicitly set for a node within this collection.
CollectionNode
  
Returns the NodeConfiguration options for a given node in this CollectionNode.
CollectionNode
  
getUserRole(p_userID:String, p_nodeName:String = null):int
Gets the role of a given user for this collection or a node within it.
CollectionNode
  
isNodeDefined(p_nodeName:String):Boolean
Whether the given node exists in this CollectionNode.
CollectionNode
  
publishItem(p_messageItem:MessageItem, p_overWrite:Boolean = false):void
Publishes a MessageItem.
CollectionNode
  
removeNode(p_nodeName:String):void
Removes the given node from this collection.
CollectionNode
  
retractItem(p_nodeName:String, p_itemID:String = null):void
Retracts the indicated item.
CollectionNode
  
setNodeConfiguration(p_nodeName:String, p_nodeConfiguration:NodeConfiguration):void
Configures a node in this collection and replaces the existing NodeConfiguration.
CollectionNode
  
setUserRole(p_userID:String, p_role:int, p_nodeName:String = null):void
Gives a specific user a specific role level for this entire collection or optionally a specified node within it.
CollectionNode
  
subscribe():void
subscribe() causes the CollectionNode to subscribe to the logical destination provided by collectionName.
CollectionNode
  
unsubscribe():void
Disconnects this CollectionNode from the server.
CollectionNode
Events
 EventSummaryDefined by
   Dispatched when a node within the collection has a change in its configuration (typically, its access-model).CollectionNode
   Dispatched when a node within the collection receives an item.CollectionNode
   Dispatched when a node within the collection retracts an item.CollectionNode
   Dispatched when the current user's role changes for the collectionNode as a whole and not nodes within it.CollectionNode
   Dispatched when a node is created within the collection.CollectionNode
   Dispatched when a node is deleted within the collection.CollectionNode
   Dispatched when the collection has been disconnected from the server and is in the process of reconnecting and re-subscribing.CollectionNode
   Dispatched when the collection has fully received all nodes and items stored up until the present time thereby becoming synchronized as well as when the collection becomes disconnected from (and thus "out of sync" with) the room's messaging bus.CollectionNode
   Dispatched when the collection or a node within the collection, has a change in roles for any user.CollectionNode
Public Constants
 ConstantDefined by
  NO_EXPLICIT_ROLE : int = -999
[static] When clearing a role at the CollectionNode or the node level, NO_EXPLICIT_ROLE is sent to the service to clear that role.
CollectionNode
Property detail
connectSessionproperty
connectSession:IConnectSession  [read-write]

The IConnectSession with which this component is associated. Note that this may only be set once before subscribe is called; re-sessioning of components is not supported. Defaults to the first IConnectSession created in the application.

Implementation
    public function get connectSession():IConnectSession
    public function set connectSession(value:IConnectSession):void
isEmptyproperty 
isEmpty:Boolean  [read-only]

Determines whether or not the collection is empty, that is, having no nodes

Implementation
    public function get isEmpty():Boolean
isSynchronizedproperty 
isSynchronized:Boolean  [read-only]

Determines whether or not the collection is "up to state" with all previously stored items in its nodes. Once a CollectionNode has successfully connected to the service and retrieved all its nodes and messageItems, it is considered synchronized. If the connection is lost, it becomes unsynchronized until it fully reconnects and re-retrieves its state.

Implementation
    public function get isSynchronized():Boolean
nodeNamesproperty 
nodeNames:Array  [read-only]

Returns the names of all the nodes within this collection.

This property can be used as the source for data binding.

Implementation
    public function get nodeNames():Array
sharedIDproperty 
sharedID:String  [read-write]

The sharedID is the logical address of this collection within the room and must therefore be unique from all other CollectionNode names.

Implementation
    public function get sharedID():String
    public function set sharedID(value:String):void
userRolesproperty 
public var userRoles:Object

The complete set of roles for this collection described as {userID:role} pairs.

Constructor detail
CollectionNode()constructor
public function CollectionNode()
Method detail
canUserConfigure()method
public function canUserConfigure(p_userID:String, p_nodeName:String = null):Boolean

Determines whether a given user is allowed to configue this collection.

Parameters
p_userID:String — The ID of the user whose role (and therefore permissions) is being queried.
 
p_nodeName:String (default = null) — Optionally, the name of the requested node. Defaults to the collection.

Returns
Boolean
canUserPublish()method 
public function canUserPublish(p_userID:String, p_nodeName:String):Boolean

Determines whether a given user is allowed to publish to a given node in this collection.

Parameters
p_userID:String — The ID of the user whose role (and therefore permissions) is being queried.
 
p_nodeName:String — The name of the desired node.

Returns
Boolean
canUserSubscribe()method 
public function canUserSubscribe(p_userID:String, p_nodeName:String = null):Boolean

Determines whether a given user is allowed to subscribe to this entire collection or a node within it.

Parameters
p_userID:String — The ID of the user whose role is being queried.
 
p_nodeName:String (default = null) — [Optional, null if empty]. The node to check. If null, it checks the entire CollectionNode.

Returns
Boolean
createNode()method 
public function createNode(p_nodeName:String, p_nodeConfiguration:NodeConfiguration = null):void

Creates a new node in this collection; they are either optionally configured when created or accept the default configuration. Note that only users with and owner role may create or configure nodes on a CollectionNode.

Parameters
p_nodeName:String — The name for the new node which must be unique within the CollectionNode.
 
p_nodeConfiguration:NodeConfiguration (default = null) — Optionally, the configuration for this node. If none is supplied, NodeConfiguration.defaultConfiguration is used.
fetchItems()method 
public function fetchItems(p_nodeName:String, p_itemIDs:Array):void

Fetches the set of items specified by itemIDs from a given node. This will result in one ITEM_RECEIVE event per item retrieved, for the current user. Attempts to fetch items which don't exist fails silently.

Parameters
p_nodeName:String — The name of the node from which to fetch the items.
 
p_itemIDs:Array — An array of itemIDs (Strings) to fetch from the service.
getExplicitUserRole()method 
public function getExplicitUserRole(p_userID:String, p_nodeName:String = null):int

Gets the role of a given user for a node within this collection or the collection itself. This only returns the explicit roles set on the particular node and doesn't look up the cascading roles from the root as getUserRole() does.

Parameters
p_userID:String — The user whose role is being queried.
 
p_nodeName:String (default = null) — The name of the node to whose roles are desired. Null for the collection itself.

Returns
int — The requested role. If the role for the user isn't explicitly set, it returns NO_EXPLICIT_ROLE.
getExplicitUserRoles()method 
public function getExplicitUserRoles(p_nodeName:String = null):Object

Gets the roles explicitly set for a node within this collection. This only returns the explicit roles set on the particular node and doesn't look up the cascading roles from the root as getUserRole() does.

Parameters
p_nodeName:String (default = null) — The user whose role is being queried.

Returns
Object — An object table of {userID:role} tuples.
getNodeConfiguration()method 
public function getNodeConfiguration(p_nodeName:String):NodeConfiguration

Returns the NodeConfiguration options for a given node in this CollectionNode.

Parameters
p_nodeName:String — The name of the desired node.

Returns
NodeConfiguration
getUserRole()method 
public function getUserRole(p_userID:String, p_nodeName:String = null):int

Gets the role of a given user for this collection or a node within it. Note that this function discovers the implicit or cascading role of the user at this location; that is, if no explicit role is specified for a node, the user's role on the parent collection's is queried. If the user's role isn't explicitly defined on the collection, the root role is queried.

Parameters
p_userID:String — The user whose role is being queried.
 
p_nodeName:String (default = null) — [Optional, defaults to null]. The name of the node to check for roles. If null, check the entire CollectionNode.

Returns
int — the level of role of the specified user
isNodeDefined()method 
public function isNodeDefined(p_nodeName:String):Boolean

Whether the given node exists in this CollectionNode.

Parameters
p_nodeName:String — the name of desired node

Returns
Boolean
publishItem()method 
public function publishItem(p_messageItem:MessageItem, p_overWrite:Boolean = false):void

Publishes a MessageItem. The MessageItem itself will have a nodeName declared.

p_overWrite provides users with control over whether edits take precedence over delete actions. It is essentially a lock that assures an item can only be published if it exists. The general rule of thumb is that if you want to add a new item, use the p_overWrite default flag of false. If you're editing an item that may be retracted, then set the flag according to your preference.

For example, consider a whiteboard, where each shape is represented by one or more items. For a dynamic system like a whiteboard, shapes can be modified and retracted. p_overwrite makes sure that if you modify a shape but a message race causes that item to be deleted before the edit is committed, the delete takes precedence over the edit. Since the edit is meaningless on a non-existent item, that action is not accepted; otherwise, the edit would cause the shape to exist again. Parameters

p_messageItem:MessageItem — The MessageItem to publish.
 
p_overWrite:Boolean (default = false) — True if this call is overwriting an existing item. False (the default) if it is not.
removeNode()method 
public function removeNode(p_nodeName:String):void

Removes the given node from this collection. Only users with an owner role may change a node's configuration.

Parameters
p_nodeName:String
retractItem()method 
public function retractItem(p_nodeName:String, p_itemID:String = null):void

Retracts the indicated item. This removes the item from storage on the server and sends an itemRetract event to all users.

Parameters
p_nodeName:String — The nodeName of the messageItem to retract.
 
p_itemID:String (default = null) — The itemID of the messageItem (stored on the server) to retract.
setNodeConfiguration()method 
public function setNodeConfiguration(p_nodeName:String, p_nodeConfiguration:NodeConfiguration):void

Configures a node in this collection and replaces the existing NodeConfiguration. Only users with an owner role may change a node's configuration.

Parameters
p_nodeName:String — The name of the node to configure.
 
p_nodeConfiguration:NodeConfiguration — The new NodeConfiguration for the node.
setUserRole()method 
public function setUserRole(p_userID:String, p_role:int, p_nodeName:String = null):void

Gives a specific user a specific role level for this entire collection or optionally a specified node within it. Roles cascade down from the root level of the room to the CollectionNode level and then to the node level. The following override rules apply:

Parameters
p_userID:String — The desired user's userID.
 
p_role:int — The users new role.
 
p_nodeName:String (default = null) — [Optional, defaults to null] The UserRole for the entire CollectionNode
subscribe()method 
public function subscribe():void

subscribe() causes the CollectionNode to subscribe to the logical destination provided by collectionName. If there is no such destination on the service and the current user has an owner role, a new CollectionNode is created and stored on the service with the given collectionName. When subscription is successful or a new CollectionNode is created, the collection:

unsubscribe()method 
public function unsubscribe():void

Disconnects this CollectionNode from the server. Typically used for garbage collection. If a node is subscribed but a network or services glitch causes it to disconnect, the CollectionNode will attempt to reconnect automatically.

Event detail
configurationChangeevent 
Event object type: com.adobe.rtc.events.CollectionNodeEvent

Dispatched when a node within the collection has a change in its configuration (typically, its access-model).

itemReceiveevent  
Event object type: com.adobe.rtc.events.CollectionNodeEvent

Dispatched when a node within the collection receives an item.

itemRetractevent  
Event object type: com.adobe.rtc.events.CollectionNodeEvent

Dispatched when a node within the collection retracts an item.

myRoleChangeevent  
Event object type: com.adobe.rtc.events.CollectionNodeEvent

Dispatched when the current user's role changes for the collectionNode as a whole and not nodes within it. This event is more frequently useful than its more general counterpart, userRoleChange.

nodeCreateevent  
Event object type: com.adobe.rtc.events.CollectionNodeEvent

Dispatched when a node is created within the collection.

nodeDeleteevent  
Event object type: com.adobe.rtc.events.CollectionNodeEvent

Dispatched when a node is deleted within the collection.

reconnectevent  
Event object type: com.adobe.rtc.events.CollectionNodeEvent

Dispatched when the collection has been disconnected from the server and is in the process of reconnecting and re-subscribing. A typical response to this event would be to reinitialize any shared parts of a model which depend on this collectionNode as the items will be re-received from the server. SYNCHRONIZATION_CHANGE will fire once this process completes.

synchronizationChangeevent  
Event object type: com.adobe.rtc.events.CollectionNodeEvent

Dispatched when the collection has fully received all nodes and items stored up until the present time thereby becoming synchronized as well as when the collection becomes disconnected from (and thus "out of sync" with) the room's messaging bus.

userRoleChangeevent  
Event object type: com.adobe.rtc.events.CollectionNodeEvent

Dispatched when the collection or a node within the collection, has a change in roles for any user. This event is less frequently used than its more useful counterpart, myRoleChange. In general, this event is only useful for situations in which the individual nodes have roles assigned to them and where the developer cares about the roles of users other than the current user for these nodes.

Constant detail
NO_EXPLICIT_ROLEconstant
public static const NO_EXPLICIT_ROLE:int = -999

When clearing a role at the CollectionNode or the node level, NO_EXPLICIT_ROLE is sent to the service to clear that role.





 

Send me an e-mail when comments are added to this page | Comment Report

Current page: http://livedocs.adobe.com/labs/acrobatcom/com/adobe/rtc/sharedModel/CollectionNode.html