A Services Dictionary Publishes a UcompOS Entity’s Public API Methods

As I discussed in my posting yesterday, each application, sub-application, and the UcompOS Portal itself is considered an entity in the context of the UcompOS Continuum.

For an entity to play a meaningful role in the Continuum, it must have the UcompOS SDK installed and there is an SDK for Flash/Flex, AIR, and JavaScript UcompOS applications.

The SDK enables each entity to serve as both a client as well as a server as far as its ability to send requests to and receive requests from other entities.

The implementation details of the UcompOS SDK are well hidden from the developer, however, to build the most engaging and interactive experiences with the UcompOS RPF, a command of the core mechanics of the UcompOS SDK will serve you very well.

Before I continue, I recommend you take a look at the Video Tutorials entitled Services Dictionaries and Proxy Components that will provide a foundation for the client-server paradigm of a UcompOS entity.

Messages are sent back and forth between entities in the UcompOS Continuum in a format called a DataPackageDataPackage is a class in the UcompOS SDK.  Full SDK documentation is online for ActionScript and JavaScript developers.

The SDK class SDKClient is the interface to the UcompOS Continuum for outbound DataPackage instances and the class SDKServer is the interface to the UcompOS Continuum for inbound DataPackage instances.

The functionality an entity makes publicly available to other entities are considered that entities Public API Methods.  The list of Public API Methods that an entity sponsors are published in an instance of a class known as a Services Dictonary.

A Services Dictionary by strict convention will extend the abstract class AbstractServicesDictionary which is built into the SDK.

AbstractServicesDictionary furnishes a protected variable _map, which will be overridden in the extending Services Dictionary class instance.

_map is a simple Object where each property is an Object whose key is the name of a public API method and whose value is an Object that points to the internal implementation location of the functionality.

For instance, in the UcompOS Portal Services Dictionary, you’ll see the following property in the _map Object:

'MDI.addWindow':{
  static:false,
  classRef:com.ucompass.ucompos.controller.api.commands.MDI,
  method:'add',
  description:'Forms a new MDI window on the UcompOS Main Container'
}

MDI.addWindow is then considered a Public API Method sponsored by the UcompOS Portal.

You can sort of think of a Services Dictionary as being analogous to a web server configuration file where virtual hosts are analogous to public API method names and the local directory they resolve to are analogous to the mapping to the internal functionality that is leveraged when the public API method is contacted.

When the UcompOS SDK is instantiated, the static getInstance() method of the SDKClient class is passed a reference to the main application class (an extension of MovieClip or Sprite in a Flash application or an implementation of Application or WindowedApplication in a Flex application).

The syntax to instantiate the UcompOS SDK client is as follows:

SDKClient.getInstance(this);

and this command is generally going to be in the application’s main class either in the constructor of the main Document class in a Flash application, or in a private event handler in the main MXML document of a Flex application being called AFTER the applicationComplete event is fired.

The instantiation of the UcompOS SDK Client can accept a second parameter as well which would be a new instance of a Services Dictionary.  So suppose in my entity my Services Dictionary was a class named ServicesDictionary.  I would instantiate the UcompOS SDK as follows:

SDKClient.getInstance(this,new ServicesDictionary());

Once I do this, any other entity can easily target my entity’s public API methods.

I will add at this point that by strict convention, any public API method must be configured to accept exactly one parameter of type Object and return a value of type Object.  Any data that needs to be sent to a particular public API method must be encapsulated within the single Object parameter passed to it.

Also, the UcompOS SDK has been kept deliberately as simple as possible.  There are no Flex dependencies in it which is why you can use the SDK interchangeably in Flash as well as Flex applications so keep this in mind when packaging data for transmission across the UcompOS Continuum.  For instance, sending an ArrayCollection from a Flex application to the public API method of a Flash application will obviously not work.

An entity can target functionality in another entity even if that functionality is not exposed in the target entity’s Services Dictionary.  However in this case, obviously, the calling entity requires intimate knowledge of the internal implementation details of the target entity.

In my blog posting tomorrow, I’ll focus on the other side of a UcompOS transaction between two entities and I’ll introduce Proxy Components.  A Proxy Component is a client to the public API method in another entity.  As a brief foreshadowing, the UcompOSWindowProxy’s add(); method in the UcompOS SDK can be considered a client to the example UcompOS Portal public API method above, MDI.addWindow.

Further, packaged into the UcompOS SDK are a host of Proxy Components that represent the client interface to all the public API methods that are exposed by the UcompOS Portal.

More on this crucial topic tomorrow.

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.