Garbage Collection in the UcompOS RPF

OscarTheGrouch In large and sophisticated Flash-based applications, such as the Rich Portal Applications you develop with the UcompOS Rich Productivity Framework, Garbage Collection becomes an increasingly important consideration.

Garbage Collection is a computer science concept that deals with memory management and re-allocating memory occupied by objects that are no longer needed or in use by the computer program.

Garbage Collection in a large-scale event-driven Flash architecture is a crucial consideration and unfortunately, can also be a tedious proposition to properly implement.

One of the more important considerations in aiding with Garbage Collection in Flash-based application is proper management of event listeners.

In a best-practice implementation, any call to addEventListener() would be followed up with a call to removeEventListener() once the event listener was no longer needed. Event listeners perpetuate the objects they are associated with so even once a particular object is destroyed, that doesn’t necessarily mean any event listeners associated with it will be destroyed too.

Failure to remove event listeners once they are no longer needed in a large-scale implementation can cause memory leaks and performance can break down over time.

In all your Flash applications, you should employ this strategy when and where possible.

In a typical large-scale UcompOS RPF implementation, Flash-based applications and sub-applications are continuously being loaded and unloaded into the UcompOS Portal.

The concept of Proxy Components in the UcompOS RPF involves event listeners being attached to a Proxy Component in one entity that represents an object in another UcompOS entity and then listening for dispatched events.

Therefore, the concept of garbage collection takes on especially critical importance in the UcompOS RPF because if UcompOS applications are being loaded and unloaded constantly and the event listeners that are attached to them are not being properly removed, performance would become an issue in a large-scale implementation.

The UcompOS Portal has been designed such that when SWF content that has been loaded into the UcompOS Portal is unloaded, a garbage collection routine is implemented to try to optimize system performance. (The three ways SWF content is loaded into the UcompOS Portal is in UcompOS Window instances, UcompOS Artifact instances, or into the UcompOS run-time.)

As of the UcompOS RPF Public Alpha release 0.4.6, some additional enhancements to the garbage collection process have been implemented that I will discuss here.

Understanding the UcompOS RPF garbage collection architecture can help you build more scalable Rich Portal Applications.

The recent enhancements come in the realm of Proxy Components.

By strict convention, all Proxy Components must extend the SDK class AbstractProxyComponent. As of UcompOS RPF 0.4.6, AbstractProxyComponent now extends a new SDK class called SDKEventDispatcher which extends EventDispatcher.

(Also, as a side-note, the AbstractProxyComponent class now implements IEventDispatcher in addition to IProxyComponent so you can refer to your Proxy Components as IEventDispatcher or IProxyComponent instances interchangably.)

SDKEventDispatcher simply overrides addEventListener() and offers a protected property _listeners of type Array.

I chose to create this separate class versus simply overriding addEventListener() in AbstractProxyComponent so that in the event the new clean-up process employed can be useful outside the scope of a Proxy Component, one could simply extend SDKEventDispatcher versus EventDispatcher.

Here is the over-ridden addEventListener():

override public function addEventListener(type:String, listener:Function, useCapture:Boolean=false, priority:int=0, useWeakReference:Boolean=false):void
{
	_listeners.push({type:type,listener:listener});
	super.addEventListener(type,listener,useCapture,priority,true);
}

Notice that I am always assigning a true value to the useWeakReference parameter in the super call to addEventListener(). This is because in the context of attaching event listeners to Proxy Components, you always would want them to be weak references to aid in garbage collection.

In AbstractProxyComponent, there is a new protected method, cleanup() which is as follows:

protected function cleanup(event:SDKEvent=null):void
{
	while(_listeners.length)
	{
		var object:Object = _listeners.pop();
		removeEventListener(object.type,object.listener);
	}
	_sdkModel.removeProxyComponent(this.uuid);
	var commandObject:CommandObject = new CommandObject("SDK.cleanup",{uuid:this.uuid});
	var dataPackage:DataPackage = new DataPackage(Utilities.createUID(),_sdkModel.connectionId,this.destination,commandObject);
	_sdkClient.send(dataPackage);
}

What the cleanup() method does is it automatically removes any event listeners that have been attached to the Proxy Component.

It also sends a message to the end-point of the Proxy Component targeting its SDK.cleanup public API method that is built into the UcompOS SDK and therefore exposed by any UcompOS entity. This aids in UcompOS RPF garbage collection-related activities.

Calls to cleanup() do not occur automatically.

When you would call cleanup() in a Proxy Component would be an implementation specific consideration.

For instance, with these new capabilities, I have updated some of the UcompOS Portal Proxy Components that are built into the UcompOS SDK.

Consider the updated constructor of the UcompOSWindowProxy class:

public function UcompOSWindowProxy()
{
	super();
 
	// set the destination property to the UcompOS Portal
	super._destination = _sdkModel.root;
	<strong>addEventListener(CLOSE,cleanup);</strong>
}

The call to addEventListener(CLOSE,cleanup) is the new addition to the constructor.

What it does is it causes the inherited cleanup() method to always be called when the UcompOS Window instance on the UcompOS Portal that is represented by the UcompOSWindowProxy instance is closed.

Therefore, any event listeners you have attached to the UcompOSWindowProxy instance are automatically removed whenever the window is closed.

In 100% of the possible use cases for the UcompOSWindowProxy, this is the desired behavior.

The net result of this is you don’t have to worry about making your own calls to removeEventListener() for your particular UcompOSWindowProxy instances.

The same sort of behavior has been engineered into some of the other Proxy Components built into the UcompOS SDK including UcompOSAlertProxy, UcompOSDialogueProxy, UcompOSArtifactProxy, and UcompOSBrowserWindowProxy.

Consider this strategy when you are building your own Proxy Components and remember to always use removeEventListener() in all your other Flash applications whether you are deploying them in the UcompOS Portal or not.

Cross-Application Interactions in UcompOS Implementations

One of my primary goals in the design of the UcompOS Rich Productivity Framework was to create a flexible environment for the deployment of multiple Rich Internet Applications that needed to work either separately, or discretely to create a singular overall rich experience.

UcompOS Applications launched by the UcompOS Portal are sandboxed in such a way that they exist as isolated entities that can operate independently from the environment they’ve been loaded into.

As I touched upon in my posting on Building Drag and Drop Experiences in the UcompOS RPF, UcompOS applications should not attempt to access other UcompOS entities directly through direct ActionScript or JavaScript class/method interaction.

This is not to say that you cannot do this, but if you were going to, say, load two separate UcompOS entities into a n0n-sandboxed configuration, and have each entity access the other’s classes, you would obviously be tightly coupling the entities in such a way that if two different developers were working on each entity, one could very easily break the implementation unintentionally.

If you have a very compelling reason to do this, I have not prevented you from doing this.

In this posting, I will touch upon some of the numerous models for achieving cross-application interactivity in the UcompOS RPF.

Proxy Components and Services Dictionaries

The model for interactivity across the boundaries of UcompOS entities and applications is to use the framework that’s built into the UcompOS SDK, mainly Services Dictionaries and Proxy Components.  These are two extremely important concepts to understand, which is why I touch upon them so frequently.

In review, a Services Dictionary publishes a list of the “Public API” methods that an entity exposes to other entities.  A Proxy Component is a client apparatus in one entity that is built to connect to the Public API method sponsored by some other entity.

As I’ve also explained numerous times, and particularly in this posting, the UcompOS SDK has a number of Proxy Components built into it that are client apparatus’ to the Public API methods of the UcompOS Portal.  After all, the UcompOS Portal is simply one entity in the overall context of the UcompOS Continuum.

Numerous postings and tutorials I’ve posted give examples of building Services Dictionaries and Proxy Components so I won’t go into the details of this in this posting, but again, understanding their mechanics is crucial.

UcompOS SDK Events

Another crucial concept to understand in the UcompOS RPF is its Event-based implementation.

By strict convention, all Proxy Components extend a class in the UcompOS SDK named AbstractProxyComponent.

As the name implies, it is an abstract class and should never be instantiated directly, only extended.  (Unfortunately, ActionScript 3 doesn’t give us a true foolproof way to enforce abstractness.)

AbstractProxyComponent extends EventDispatcher so thus all Proxy Components inherit an addEventListener(); method.

So essentially, in one UcompOS entity, you can build a Proxy Component that talks to the Public API method in another entity.  And you can register an event listener to receive event notices from that Proxy Component.

That’s why I call these things “Proxy” Components.

You are creating a virtual representation in one entity of a physical implementation in another entity, so essentially, your Proxy Component is a “Proxy” to the true implementation that is actually located in an entirely different entity.

So when you do something like the following:

var w:UcompOSWindowProxy = new UcompOSWindowProxy();
w.add("http://blog.ucompass.com","UcompOS",800,600);
w.addEventListener(UcompOSWindowProxy.CLOSE,closeHandler);

w in the above scenario is an instance of the Proxy Component UcompOSWindowProxy that is built into the UcompOS SDK.

w is not REALLY the window that gets created on the UcompOS Portal, but it is a virtual representation of it.

But when you add an event listener on the CLOSE event of the window, it is as if you are attaching an event listener to the actual window itself.

I am hopeful that the concept of Proxy Components is making more and more sense to the dedicated readers of this blog.

The event handlers implemented with any Proxy Component are exclusively dispatched an instance of the SDKEvent class.

The SDKEvent class is worth studying.

If you look at the AS3 docs for the SDKEvent class, you’ll notice it has a collection of read-only properties.  One of which is data and another is proxyComponent.

By strict convention, any Public API method in a UcompOS entity returns an item of type Object.  This data is carried back to the Proxy Component that invoked the Public API Method in the form of an SDKEvent instance.

So for instance, building to our simple example above, I could do something like this:

w.addEventListener(UcompOSWindowProxy.WINDOW_INFO,windowInfoHandler);
w.getWindowInfo();
 
private function windowInfoHandler(event:SDKEvent):void
{
 
 // this will be the Object returned by the Public API method I contacted
 var data:Object = event.data;
 
 trace("Window size is "+data.width+" x "+data.height);
 
}

Let’s talk a bit about the proxyComponent property of SDKEvent instances.

It is of type IProxyComponent.

The AbstractProxyComponent event implements the interface IProxyComponent from the SDK, so any Proxy Component can be cast as an item of type IProxyComponent.

Dispatching an Event to a Proxy Component from a Public API Method

So you have built your Public API method and you have set up a Proxy Component in another entity to connect to this Public API Method.

As I have explained, the Object your Public API Method MUST return will be returned to your Proxy Component packaged in an SDKEvent instance.

But what if you asynchronously want to dispatch an SDKEvent to a Proxy Component?

The key to this is the BroadcastEvent class in the SDK and its static dispatchEvent(); method.

As an example of when we might use this capability, suppose we have a UcompOS AIR application that sponsors a Public API Method that allows us to asynchronously return the list of files in a directory.

The implementation of this might look something like this:

private var _uuid:String;
 
public function getFilesInDirectory(data:Object):Object
{
 _uuid = data._dataPackage.uuid;
 var directory:File = new File(data.directory);
 directory.addEventListener(FileListEvent.DIRECTORY_LISTING,getFilesInDirectory_handler);
 directory.getDirectoryListingAsync();
 return SDKEvent.VOID;
}
 
private function getFilesInDirectory_handler(event:FileListEvent):void
{
 var files:Array = [];
 for(var i:uint = 0;i&lt;event.files.length;i++)
 {
 files.push((event.files[i] as File).name);
 }
 BroadcastEvent.dispatchEvent(_uuid,"fileListing",{files:files});    
}

As a brief aside, notice in the Public API method, I am returning SDKEvent.VOID.  This actually suppresses the return altogether of any data to the calling Proxy Component.  This is the best practice when your Public API method doesn’t return anything of value to the calling Proxy Component.

When the UcompOS SDK passes the input Object to a Public API method, it adds a property to the Object called _dataPackage which itself is an Object.

This Object has a property, uuid, which is the same value of the uuid property on the Proxy Component that originated the transaction with the Public API method.

The BroadcastEvent.dispatchEvent(); method expects this uuid value as the first input parameter.

A Proxy Component that invoked this Public API method could have an event listener listening for events of type “fileListing”.  In this scenario, the event handler would be dispatched an SDKEvent with the data dispatched to the BroadcastEvent.dispatchEvent(); method.

Dispatching Continuum Events

The UcompOSGlobalManagerProxy class in the UcompOS SDK has a method named dispatchContinuumEvent();.

It accepts two parameters – the type of event, and a data Object.

When you call this method, you are dispatching an event to every entity in the UcompOS Continuum and the event can be listened for on the UcompOSGlobalManagerProxy Singleton.

So for instance, you could say something like:

UcompOSGlobalManagerProxy.getInstance().dispatchContinuumEvent("myEvent",{name:Ed});

And in an entirely different entity, you could do something like this:

UcompOSGlobalManagerProxy.getInstance().addEventListener("myEvent",eventHandler);

and your event handler could look something like:

private function eventHandler(event:SDKEvent):void 
{
 
 trace("Your name is "+event.data.name);
 
}

The dispatchContinuumEvent(); method doesn’t need to target a specific entity as the BroadcastEvent.dispatchEvent(); method does – it simply dispatches an event to EVERY entity.

Launching one UcompOS Application from Another Entity

The UcompOSGlobalManagerProxy class has a launchApplication(); method which accepts as input an Application Manifest URL as a String.

This enables you to launch a UcompOS Application from another entity.  Similarly, there is a quitApplication(); method as well as a getConnectionId(); method which can be used to find the connectionId of an already running UcompOS Application.

UcompOS Shared Objects

As I posted here, the UcompOS RPF now has a Shared Object implementation where an entity can house Objects of specific names on an Object on the UcompOS Portal that is available to all other entities.

When any Shared Object is created or its properties are updated, a Continuum Event is dispatched.

This creates an environment where the Shared Object itself can become a useful medium for achieving inter-application and inter-entity communication.

A Simple UcompOS Shared Object Impementation Example

The new Shared Object implementation in the UcompOS Rich Productivity Framework provides an additional model for achieving inter-application and sub-application communication and data exchange in a manner that is grounded in the MVC (Model-View-Controller) Design Pattern.

The term Shared Object in the context of the UcompOS RPF is similar in principle to the concept of the Local Shared Object infrastructure that has been in the Flash Player since the days of Flash 4 but in our case, the UcompOS RPF Shared Object is a run-time Object that does not get saved locally (unless you of course configure your own implementation to do so).

In the UcompOS Portal is an Object that gets instantiated into the application’s run-time memory upon authentication.

This Object is then freely available for all UcompOS entities to access using the GlobalManager.setSharedObject, GlobalManager.getSharedObject, and GlobalManager.getSharedObjects public API methods sponsored by the UcompOS Portal.

The UcompOSGlobalManagerProxy class in the UcompOS SDK has an API to these methods in the public methods of the class as indicated  below:

public function setSharedObject(key:String, value:Object):void
public function getSharedObject(key:String):void
public function getSharedObjects(keys:Array):void

One of the more important aspects of the Shared Object implementation is that the UcompOS Portal dispatches a Continuum Event of type SDKEvent.SHARED_OBJECT whenever a property of the Shared Object changes.

A Continuum Event is an event dispatched to every entity in the UcompOS Continuum.

An entity can attach a listener to the UcompOSGlobalManagerProxy Singleton listening for SDKEvent.SHARED_OBJECT events.

The event Object will have a key and a value property representing the property on the Shared Object that was just modified and its associated value.

As a very simple example of what we can do with this, I set up a basic UcompOS implementation.

The implementation involves a UcompOS background application that launches a UcompOS Window with a text area.  Upon initialization, this application launches another UcompOS Window with a sub-application in it next to the initial window  This sub-application also has a text area.

When text is entered in the primary application window’s text area, the text is instantly displayed in the sub-application window’s text area.

The mechanics for this employ the UcompOS Shared Object.

I’ll share the code below so you can get an understanding of how it was configured:

The Dock Manifest

<applications>
 <application background="true">
  http://desktop.ucompass.com/Shared_Object/manifest.xml
 </application>
</applications>

The Application Manifest

<application selfLoading="true" width="500" height="500" x="0" y="100">
 <source>
 <base>http://desktop.ucompass.com/Shared_Object/windowA.html</base>
 </source>
 <titles>
 <title locale="en_US">Shared Object Example</title>
 </titles>
</application>

The Application Code

<html>
<head>
<title>Window A</title>
<script type="text/javascript" src="/UcompOSSDK.js"></script>
<script type="text/javascript">
 
 var g;
 var w;
 
 function start()
 {
  g = new UcompOSGlobalManagerProxy();
  w = new UcompOSWindowProxy();
  w.add("http://desktop.ucompass.com/Shared_Object/windowB.html","Echo",500,500,510,100);
 }
 
 function echo()
 {
  // pause for 1/100th of a second as the onkeypress event is dispatched before the textarea is updated
  setTimeout(function() { g.setSharedObject("echo",document.getElementById('text').value); },10);
 }
 
</script>
</head>
<body>
<u>Enter some text</u><br/>
<textarea id="text" style="width: 400px; height: 400px;" onkeypress="echo();"></textarea>
</body>
</html>

The Sub-Application Code

 
<html>
<head>
<title>Window B</title>
<script type="text/javascript" src="/UcompOSSDK.js"></script>
<script type="text/javascript">
 
 var g;
 var w;
 
 function start()
 {
  g = new UcompOSGlobalManagerProxy();
  g.addEventListener(g.SHARED_OBJECT,echo);
 }
 
 function echo(data)
 {
  switch(data.key)
  {
   case "echo":
    document.getElementById('text').value = data.value;
   break;
  }
 }
 
</script>
</head>
<body>
<u>What you're saying in the other window</u><br/>
<textarea id="text" style="width: 400px; height: 400px;"></textarea>
</body>
</html>

UcompOS SDK Communication Mechanics

I want to spend some time looking a bit deeper under the hood of the UcompOS SDK particularly in terms of how the SDK is configured to enable entities to talk to one another.

Understanding these mechanics can help you understand how to build the best Proxy Components that will promote the richest experiences for your UcompOS Rich Portal Application.

As you’ve read about in my previous blog postings, the Flash Player’s LocalConnection infrastructure is the medium used for inter-entity communication in the UcompOS Rich Productivity Framework.

A slight exception to this is with UcompOS AIR 2.0 applications that take advantage of AIR 2.0′s new ServerSocket class such that messages are sent to the AIR application over a socket versus LocalConnection.

My reasons for using LocalConnection despite its known limitations have to do with the fact that LocalConnection is such a practical lowest common denominator solution and is equally available to all versions of ActionScript.

Limitations of the LocalConnection include the inability to send data packets in greater than 40K chunks. The SDK elegantly works around this limitation by implementing its own incremental transmission and aggregation logic.

For the most part, the messages sent between entities don’t ever come anywhere near 40K but are closer to 1K. In some use cases, larger data chunks may need to be sent over the UcompOS “SDK Tunnel”. For instance, in Educator 2, I am building a whiteboard application and content drawn in the application often needs to be transmitted elsewhere as a ByteArray encoded PNG.

Messages sent back and forth in the UcompOS Continuum via the SDK are placed into an instance of a class called DataPackage. The DataPackage itself will receive a polymorphic construct of type IDataPackageObject as one of its input parameters.

(REMINDER: There is AS3 documentation for the SDK)

Currently, the classes in the SDK that implement IDataPackageObject are CommandObject and EventObject.

With this knowledge we can talk a bit more about the mechanics of data transmission.

As I’ve explained, a UcompOS entity serves both as a server and a client in the context of the UcompOS Continuum.

The “touch points” of a UcompOS entity are the classes SDKClient and SDKServer. SDKClient is of course also the class that is instantiated when a UcompOS application starts up.

The SDKClient‘s send(); method receives a DataPackage as input. In addition to the DataPackage having the polymorphic IDataPackageObject instance embedded, it also has information about the destination entity as well as the origin entity. The send(); method then uses the LocalConnection infrastructure, or an extended Socket class, to send the DataPackage to the remote entity (encoded into a compressed ByteArray).

The SDKServer then serves as the server infrastructure in a UcompOS entity.

The SDKServer‘s server(); method is the method targeted by the SDKClient‘s send(); method.

This method decodes the compressed ByteArray, serializes it into a DataPackage, and then determines what type of IDataPackageObject instance is in it.

It then passes the DataPackage to a polymorphic construct of type IServerHandler.

Right now, as you’d expect, there are two classes in the SDK that implement IServerHandler: CommandObjectHandler and EventObjectHandler.

Communication in the UcompOS RPF is both synchronous and asynchronous.

The transmission of a CommandObject from one entity to another results in the receiving entity generating an EventObject and passing it back to the sending entity in real-time. In that regard it is a synchronous communication process.

From an implementation point of view, the EventObjectHandler class causes the Proxy Component that made the original call in the calling entity to dispatch an event of type SDKEvent and this event object will have a data property that represents the data returned by the method contacted in the target entity.

The API method in the target entity must by strict convention return an item of type Object. This Object can have an eventType property which will be the event type of the SDKEvent dispatched by the calling Proxy Component via the EventObjectHandler class.

Typically in a UcompOS application, one would attach an event listener to a Proxy Component instance for the event type they knew would be returned by the target remote API method.

Thus the model takes on more of an asynchronous flavor even though you are able to take action on the return of data from a target entity in real-time.

There is a way to implement more of a callback type synchronous implementation.

The AbstractProxyComponent‘s call(); method returns a String that is used as the Universally Unique ID of the Transmission. All Proxy Components by strict convention must extend AbstractProxyComponent.

The EventObject that is returned from the target entity has a transactionId property that is the value of the String returned by the call(); method of AbstractProxyComponent.

One can easily facilitate a true callback strategy armed with this knowledge.

The UcompOS Event Propagation Model

The other day, I wrote a blog posting describing how the UcompOS RPF implements the MVC design pattern.

This implies that there is an event-driven architecture that has been facilitated in the UcompOS Continuum and that is indeed the case.

In this blog posting, we have to roll our sleeves up and really dig into the UcompOS SDK so that I can help you understand how the UcompOS RPF Event Architecture works.  If you have full command of the UcompOS RPF’s event architecture, it will help you build the most engaging and interactive rich experiences for your Rich Portal Applications.

The architecture at first glance is necessarily complex and involved and this will probably likely be just one of many blog postings I’ll make in reference to this topic and as time passes, I am going to work hard to make the event architecture simpler, more transparent, and as close as possible to best practice.  Of course developer feedback will be a crucial part of that mission.

CommandObject Transactions

If you’ve read my other postings, you have a very basic understanding of Proxy Components and Services Dictionaries.

Simply put, a UcompOS entity exposes its internal functionality to other UcompOS entities by publishing a Services Dictionary and a UcompOS entity contacts functionality in another entity by using a Proxy Component.

By strict convention, ALL communication between entities in the UcompOS Continuum should occur via the SDK class SDKClient and its send(); method.  (NOTE: There is a very esoteric exception to this that is handled behind the scenes by the UcompOS RPF that would involve two UcompOS entities participating in drag and drop interactions but that is beyond the scope of my article here and will be covered in an upcoming tutorial.)

The UcompOS SDK has both client and server infrastructure implemented.  Therefore, each UcompOS entity is capable of serving both as a server capable of receiving commands from other entities as well as a client capable of sending commands to other entities simultaneously.

The UcompOS RPF implements an asynchronous event dispatchment model.

When an entity needs to access a public API command in another entity, it (usually with the assistance of a Proxy Component) creates a CommandObject instance that is packaged into a DataPackage instance and sends it to the target entity via the SDKClient send(); method.  All these details are masked by the call(); method of AbstractProxyComponent which all Proxy Components must inherit from.

The server(); method of the SDKServer class is the first spot in the target entity to come in contact with the DataPackage.

DataPackages sent across the SDK Tunnel are encoded into compressed ByteArrays.

The server implementation in the SDK decodes the DataPackage and passes it to one of a couple different polymorphic constructs in the SDK:  CommandObjectHandler or EventObjectHandler

In the scenario where one entity is contacting the public API method of another entity, the DataPackage will contain a CommandObject and thus the DataPackage will be passed to the CommandObjectHandler in the SDK.

This will pass the data Object to the internal implementation code in the target entity.

By strict convention, any method that is capable of being targeted by another entity must accept exactly one parameter of type Object and return an item of type Object.

In order to understand the full event cycle in the UcompOS RPF, we must study what happens when this public API method returns this Object.  Where does this Object go from here?  How does it get back to the calling entity?

CommandObjectHandler passed the DataPackage to the internal implementation method and is returned the Object return from the method.

At this point, CommandObjectHandler turns from a server implementation to a client implementation and it creates a new DataPackage, puts an EventObject instance into it, and then sends the DataPackage back to the original entity.  So the original entity then becomes a server.

When the DataPackage with the EventObject packaged into it gets back to the SDKServer implementation in the calling entity, it is passed to the EventObjectHandler class.

The EventObjectHandler class then passes it to any event handlers that have been attached to the Proxy Component that made the initial public API call in the first place.

This is in fact why AbstractProxyComponent, which all Proxy Components extend from, inherits from EventDispatcher – so we can implement addEventListener(); thus implementing a paradigm many Flex and Flash coders are much more accustomed to.

When a public API method returns its required Object, an eventType property can be set to it.  If you do not explicitly set this, then CommandObjectHandler will set this for you as the constant SDKEvent.COMPLETE.

This eventType property is important as it has implications as far as how events get passed to a Proxy Component’s event handlers.

Suppose I have the following Services Dictionary class in a UcompOS application:

package
{
 
  import com.ucompass.ucompos.sdk.server.AbstractServicesDictionary;
 
  public class ServicesDictionary extends AbstractServicesDictionary
  {
    _map =
    {
      'Greeting.sayHello':
      {
 
        static:true,
        classRef:api,
        method:'sayHello',
        description:'Returns a greeting'
      }
 
    };
 
  }
 
}

Let’s suppose I have the following public API method that maps to Greeting.sayHello in my Services Dictionary example above:

public static function sayHello(data:Object):Object
{
  return {eventType:"Hello",greeting:"Hello there, "+data.name+"!"};
}

Now let’s suppose my Proxy Component located in another entity that will contact the Greeting.sayHello method above looks something like this:

package
{
 
  import com.ucompass.ucompos.sdk.client.AbstractProxyComponent;
  import com.ucompass.ucompos.sdk.model.SDKModel;
 
  public class Greeting extends AbstractProxyComponent
  {
 
    public function Greeting()
    {
      super._destination = SDKModel.getInstance().parent;
    }
 
    public function getGreeting(name:String):void
    {
      call("Greeting.sayHello",{name:name});
    }
 
  }
 
}
}

In my entity that will call Greeting.sayHello, I may see the following:

var g:Greeting = new Greeting();
g.getGreeting("Edward");

Now how do I get the greeting back from the entity that is exposing the public API method Greeting.sayHello?

Because AbstractProxyComponent extends EventDispatcher, and because my Greeting Proxy Component extends AbstractProxyComponent (a strict requirement of all Proxy Components), I can add an event listener to it.

g.addEventListener("Hello",greetingHandler);
 
private function greetingHandler(event:SDKEvent):void
{
  var greeting:String = event.data.greeting;
}

Notice my event handler is passed an instance of SDKEvent.  This is universal for all Proxy Components.

The SDKEvent instance will have a data property which will be the data Object returned by the remote public API method in the contacted entity.

Therefore, the eventType property in the return Object of a public API method determines which Proxy Component event handlers are passed an SDKEvent instance.

UcompOS Continuum Events

The above example shows a very simple example of an asynchronous request-response phase of a Proxy Component – public API method transaction.

There is another type of event in the UcompOS RPF called a Continuum Event.

The UcompOS Portal sponsors a public API method named GlobalManager.dispatchEvent.  This is accessed through the UcompOSGlobalManagerProxy Singleton class in the UcompOS SDK and its dispatchContinuumEvent(); method which accepts as input two parameters: type:String, and data:Object

When this method is accessed, every entity in the entire UcompOS Continuum is dispatched the event.

The implications of this is that you can monitor activity across the boundaries of different applications.  For instance, maybe you have a UcompOS Chat Application and when you receive an instant message from an individual user, you automatically want a separate UcompOS Address Book Application to open to that user’s Address Book entry.

Targeted EventObject Instances

The BroadcastEvent Singleton class in the UcompOS SDK has a dispatchEvent(); method.  This lets you send an EventObject on the fly to a single target entity.

For instance, the UcompOS SDK has a Proxy Component, that is the interface to various public API methods in the UcompOS Portal, called UcompOSWindowProxy.  The UcompOSWindowProxy‘s add(); method attaches an MDI window to the UcompOS Portal.

Internal to the UcompOS Portal implementation, it wants to notify the entity that created the UcompOS Window instance when certain user-driven activities occur such as when the window is moved, closed, minimized, maximized, etc.

Let’s look at a very simple example with some code.

Let’s suppose I have a UcompOS Application and I want to create a UcompOS Window, then I want to know when the user has closed the window.

In my application, the code I’d use to form the UcompOS Window could look like this:

var w:UcompOSWindowProxy = new UcompOSWindowProxy();
w.add("http://desktop.ucompass.com/MySubApp.swf","My Sub Application",500,500,100,100);

This will load the content at http://desktop.ucompass.com/MySubApp.swf into a UcompOS Window of dimensions 500 x 500 positioned at (100,100) from the upper-left origin point of the UcompOS Portal.

Now suppose I want to know when that window has closed.

No problem:

w.addEventListener(UcompOSWindowProxy.CLOSE,closeHandler);
private function closeHandler(event:SDKEvent):void
{
 // the window has closed
}

The reason why this works this way is that internal to the UcompOS Portal, there is a call to the UcompOS SDK static method BroadcastEvent.dispatchEvent(); that dispatches an EventObject (encapsulated in a DataPackage of course) to the entity that created the UcompOS Window.

As another example, consider the UcompOSMenuBarProxy class.  I haven’t covered the UcompOS Menu Bar in any tutorials quite yet, but the UcompOSMenuBarProxy class has a setMenuBar(); method that lets you attach an XML model that will be used as the dataProvider for the Menu Bar on the UcompOS Portal while the application in scope is in focus.

You could do something like this:

var menuModel:XML = new XML("<menu><menuitem label='File'><menuitem label='Open' data='1'/><menuitem label='Close' data='2'/></menuitem></menu>");
var m:UcompOSMenuBarProxy = UcompOSMenuBarProxy.getInstance();
m.setMenuBar(menuModel);
m.addEventListener(UcompOSMenuBarProxy.CHANGE,menuBarHandler);
 
private function menuBarHandler(event:SDKEvent):void
{
 var chooseString:String = "User chose "+event.data.label+" whose data property is "+event.data.data;
}

Summary

The event architecture in the UcompOS RPF is indeed complex at first glance.  There is no getting around that.  I am going to continue to work to simplify it, improve the documentation surrounding it, and get the implementation details as close as possible to a true best practice MVC implementation.