r15 - 31 Mar 2007 - 16:08:19 - PriscillaChungYou are here: OSAF >  Projects Web  >  ContributorNotes > TravisVachonNotes > CosmoWebUIServiceLayerProposal

Try out Chandler

Check out the new Desktop 0.7.7

Desktop | Hub | Server

Edit page

Useful Links

Cosmo Web UI Service Layer

Overview

Goals and Objectives

The Web UI Service layer is intended to provide a stable API for access to server data.

Background

As of Cosmo 0.6, access to server data is provided via fairly ad-hoc apis. Transport is frequently exposed directly to the client. For our Preview release a more stable API is required. This API should change very little in the future even across changes in the transport layer.

Use Cases

  • Getting a user's collections or subscriptions
  • Getting all events in a given collection
  • Getting a collection with a uid and a ticket key
  • Saving event details
  • Deleting events

Definition

Requirements

  • Provide simple, intuitive API to UI (and similar clients).
  • Throw clean, useful errors.
  • Publish on Topic channels with results of calls to allow UI to update properly.
  • Hide transport details from clients.
  • Allow synchronous and asynchronous versions of all service calls.

Open Questions

* Should we build another layer on top of the Conduits for service methods not already used by the Model?

Assumptions

High Level Decisions

  • All service calls can be made synchronously or asynchronously.
    • Synchronous calls return the result of the call.
    • Asynchronous calls return a dojo.Deferred object.
    • Asynchronous will be default
  • When service calls return they will automatically publish appropriate topics so that ui will update.
  • All service calls take an optional hash argument. This MUST be the last argument in the method call, and can be used for passing optional arguments which we call keyword arguments.
  • Calls can be made synchronous by including a keyword argument with a key of 'sync' and a value that evaluates to true.

Terminology

Service Layer

  • The layer of code we are proposing. Should be used for all client/server communication.
Item
  • The basic model object. More information at CosmoUIModelProposal?, when available.
Conduit
  • An object representing a way of connecting to a data source. SHOULD extend cosmo.service.conduits.AbstractConduit.

Translator

  • A class extending cosmo.service.translators.AbstractTranslator that knows how to translate from a server response to Cosmo WebUI? Model object[s]. A Conduit should be initialized with a Translator corresponding to the data format expected from the remote data source represented by the Conduit.

Service method

  • A method method made available by a Conduit.

Transport Method

  • A method made available by an underlying transport layer (like the JSON-RPC service). Should not be called by client code like UI.

Technical Design

Conduits

Justification

There is a need to encapsulate transport details to a Allow for changes in transport APIs without changing "business code" like UI. b Provide a clean API to "business code."

Happily, the changes required are fairly minimal. The API we are proposing is very close to our current model. Significant changes include:

  • Conduits will keep track of auth/z information, so there must be a different Conduit instance for each different auth/z vector (ticket, current user, etc)
  • Conduit methods will tie into the new Topic event system
  • Optional arguments are passed with a more flexible syntax.

Overview

  • Each Conduit instance should encapsulate ALL information needed to successfully connect/authenticate with a remote data source. Therefore, there should be a single Conduit instance for interacting with a user's "Owned" collections, and a single Conduit instance for each ticket in a user's subcriptions.
  • Conduit objects MUST be associated with Items and Collections at the time those objects are created. Business code should not have access to Items or Collections that do not have associated Conduits.
  • All Conduits should extend the base class AbstractConduit? (or one of its subclasses). This abstract class is responsible for the topic notification and object translation functions needed by all Conduits. To extend AbstractConduit?, use the standard dojo.declare syntax and override the do* methods (ie, doGetCollections) methods that perform calls to the transport layer and return dojo.Deferred objects.

Translators

  • Translators should implement the interface cosmo.service.translators.Translator. The are responsible for transforming raw server responses into Cosmo WebUI? Model objects.

Optional arguments

There is a general need in Javascript to accommodate optional arguments in a flexible way. We propose the following solution for this API:
  • All Conduit methods take a hash as their last argument. This hash may contain optional arguments called keyword arguments.
  • Possible keyword arguments SHOULD be well documented.

Example: sync

All conduit methods may be called either synchronously or asynchronously. By default, methods are asynchronous, but can be made synchronous by including "sync":true in the hash of keyword arguments for a method. When called synchronously, the return value of the methods is the "result of the call" instead of a dojo.Deferred object. See Return Values for more information.

Example: retry

There will, in the future, most likely be a desire to build some "auto retry" capabilities into this API. That is, it will be desirable for certain Conduit methods to automatically retry a server request instead of throwing an error upon receiving certain types of errors from the server. This feature will be enabled by including "retry":retryObject in the hash of keyword arguments for a method, where retryObject will contain information about number of retries and types of errors to retry on. This functionality may or may not make it into the first version of this API, and will require further technical design work.

Return Values

By default, Conduit methods will return dojo.Deferred objects. Success callbacks may be added to these objects using dojo.Deferred.addCallback, while error callbacks may be added using dojo.Deferred.addErrback. Please see the dojo.Deferred API reference for more information about Deferreds.

Synchronous versions of Conduit methods MUST return a sensible, useful data object or null. For example, Conduit.getItem should return an Item when called synchronously.

Topic Publishing

To allow for features like automatic UI updating after Item saves, Conduit methods will publish to appropriate Topic channels upon receiving a result from the server. More detailed information about this will be available once the proposal in HighLevelCosmoUIEventsProposal has been solidified.

API/Partial Implementations

Service layer as currently designed:

Notes:

  • We need to remember to reset the "serverAccessTime" whenever we make a server call, as per http://lists.osafoundation.org/pipermail/cosmo-dev/2007-March/003111.html

Special Considerations

QA / Test

We should work with QA to verify these APIs and make sure they are very stable. Can we work with the dojo.Deferred stuff to build mock responses to async calls?

API / Developer Platform

Formal API here when completed.

Security

Security questions?

Build / Install

  • dojo.Deferred will be added to the Cosmo build of Dojo


toggleopenShow attachmentstogglecloseHide attachments
Topic attachments
I Attachment Action Size Date Who Comment
pngpng Model_Data_Convenience_Syntax.png manage 34.6 K 02 Mar 2007 - 17:05 TravisVachon UML Class Diagram of MDCS
pngpng HighLevelCosmoUIServiceLayerRelationships.png manage 22.4 K 02 Mar 2007 - 17:06 TravisVachon The Conduit API will be stable enough for business object use. However, it is recommended that developers use the Model Data Convenience affordances whenever possible.
Edit | WYSIWYG | Attach | Printable | Raw View | Backlinks: Web, All Webs | History: r15 < r14 < r13 < r12 < r11 | More topic actions
 
Open Source Applications Foundation
Except where otherwise noted, this site and its content are licensed by OSAF under an Creative Commons License, Attribution Only 3.0.
See list of page contributors for attributions.