Proxy Components are Client Interfaces to Public API Methods

In my blog posting yesterday entitled A Services Dictionary Publishes a UcompOS Entity’s Public API Methods we learned that a UcompOS entity exposes functionality to other entities by publishing a Services Dictionary at the time the UcompOS SDK is instantiated.

The Services Dictionary can be thought of as a map that maps the name of a public API method to its internal implementation within that entity so as to not have to divulge the internal implementation details of the entity and its class structure.

This is the same concept as in a webserver configuration file.  You generally do not expose the internal absolute path of a virtual host, rather translate a domain or subdomain to resolve to an internal path on the local file system.

In the entity that originates a call to the public API method of another entity, the UcompOS SDK’s client infrastructure is leveraged.

Any data that is to be sent is packaged in an instance of an SDK class called a CommandObject which is then packaged into an instance of an SDK class called DataPackage which is the exclusive format of data that travels between entities in the UcompOS Continuum.

While it is certainly permissible to manually construct CommandObjects and DataPackages and then send them to the send(); method of the SDKClient Singleton (AS3 SDK documentation is available to help with this), it is far more convenient to set up a Proxy Component to handle this.

In advanced cases, you may find the need to call up functionality in a remote entity that is NOT exposed in the ServicesDictionary.  You can still do this but of course it requires knowledge of the remote entity’s internal implementation details and you have to specify the class path and associated method in the target entity.  This scenario does require the manual construction of a CommandObject and DataPackage and then a call to the SDKClient Singleton send(); method.

Proxy Components allow you to add more practical interfaces to the functionality exposed by a remote entity.

For instance, by strict convention, all methods that participate in UcompOS Continuum activity must receive one parameter of type Object.

You could create a Proxy Component however that masks this implementation requirement.

As I explained in my posting yesterday, the UcompOS SDK is packaged with a number of Proxy Components that represent the client interfaces to the public API methods exposed by the UcompOS Portal.

The UcompOS Portal is just another entity with the SDK installed in the context of the UcompOS Continuum.

As an example, we looked at the UcompOSWindowProxy class and specifically, its add(); method.

Let’s look at a simple example here to help explain this.

Suppose we have two UcompOS entities loaded into the UcompOS Portal.  One will expose a public API method, the other will call that public API method.

In the Services Dictionary of the entity being contacted, we may see a property that looks something like this:

'API.someMethod':{ static:true, classRef:APIClass,method:'testMethod',description:'A test API method'}

The classRef is the internal class path that houses the target implementation method, testMethod.  Notice there is also a requirement to articulate whether the method is static or not.

Let’s suppose our internal testMethod(); implementation looks like this:

public static function testMethod(data:Object):Object
{
 return {value:data.value*data.value};
}

Again, by strict convention, any public API method must receive exactly one parameter of type Object as input and return a value of type Object.  In this extremely simple method, we return the square of the value property of the Object passed to the API method.

In the entity that will call this public API method, we could create a Proxy Component.

All Proxy Components by strict convention MUST extend the SDK class AbstractProxyComponent.

Our Proxy Component class may look something like this:

package
{
 
 import com.ucompass.ucompos.sdk.client.AbstractProxyComponent;
 
 public class TestProxyComponent extends AbstractProxyComponent
 {
 
   public function TextProxyComponent()
   {
     super();
     super._destination = _sdkModel.parent;
   }
 
   public function squareNumber(value:Number):void
   {
     call("API.someMethod",{value:value});
   }
 
 }
 
}

Some things to point out:

  • The call method in our Proxy Component requires exactly two parameters – the public API method name in the remote entity and the Object instance to be passed to the method – this is the strict convention to be employed in Proxy Components
  • In the constructor of our Proxy Component, we are setting the value of the protected property _destination – this concept will be covered in a follow-up posting in the near future but for now I’ll point out that all entities have a universally unique identifier associated with them (UUID) that can easily be determined dynamically
  • In this case, since the _destination property is being sent to _sdkModel.parent, the implementation scenario would involve the entity that is publishing the public API method ‘API.testMethod‘ has launched the sub-application that will call the public API method – thus the target entity is the parent in this context and its UUID is accessible on the public property parent on the _sdkModel instance that is inherited from AbstractProxyComponent

And then to invoke the squareNumber(); method, you’d see something like this:

var p:TextProxyComponent = new TestProxyComponent();
p.squareNumber(5);

The call(); method of the AbstractProxyComponent class that all Proxy Components extend masks the implementation details of CommandObjects and DataPackages from the developer.  call(); provides a direct interface to the SDKClient Singleton send(); method that sends a DataPackage instance into the UcompOS Continuum bound for the target entity.

In tomorrow’s posting, I’ll talk about how you actually get data back from the public API method.  In other words, how we actually get the result from the squareNumber(); method in our Proxy Component.

This has to do with the asynchronous event handling implementation model in the UcompOS RPF that is modeled after the MVC (Model-View-Controller) design pattern.  (Is MVC really a Design Pattern?  Lott and Patterson seem to think so in their book Advanced ActionScript 3 with Design Patterns).

About Edward Mansouri
Edward Mansouri is the CEO and Founder of Ucompass.com, Inc., a company focused on building scalable and profitable e-Learning enterprises. His expertise is in building e-Learning software, as well as in building visual frameworks such as the Enrich Content Enrichment System and the newly announced UcompOS Rich Experience Framework. He has been working with Flash since 1998, building Flash applications since 2002, and working with Adobe AIR since its private alpha release in 2006. He authored the site AIRApps.net (later renamed to O2Apps.com) dedicated to providing leadership in building Adobe AIR applications. In 2010, he is building and releasing a new e-Learning platform called Educator 2 which is built entirely upon the UcompOS Rich Experience Framework. Since 1999, over 1,000,000 students have taken courses served with his original e-Learning platform, Educator 1.

Comments are closed.