svn commit: r1104487 - /incubator/wookie/site/trunk/content/wookie/docs/embedding.mdtext

[rg...@apache.org]

Author: rgardler
Date: Tue May 17 19:36:53 2011
New Revision: 1104487

URL: http://svn.apache.org/viewvc?rev=1104487&view=rev
Log:
Minor rewrite to make it a little more understandable

Modified:
    incubator/wookie/site/trunk/content/wookie/docs/embedding.mdtext

Modified: incubator/wookie/site/trunk/content/wookie/docs/embedding.mdtext
URL: http://svn.apache.org/viewvc/incubator/wookie/site/trunk/content/wookie/docs/embedding.mdtext?rev=1104487&r1=1104486&r2=1104487&view=diff
==============================================================================
--- incubator/wookie/site/trunk/content/wookie/docs/embedding.mdtext (original)
+++ incubator/wookie/site/trunk/content/wookie/docs/embedding.mdtext Tue May 17 19:36:53 2011
@@ -58,43 +58,45 @@ extending it to support additional widge
 Wookie provides connector framework code in many languages. These frameworks 
 provides most of the code you need to build a plugin for your platform.
 
-If you intend to write a plugin for your favourite host application please check 
-the latest version of our [connector frameworks in Subversion](http://svn.apache.org/repos/asf/incubator/wookie/trunk/connector/) 
-for the latest available connector code.
-
-Naturally, we would prefer to work together in order to build as large a set of 
-connector frameworks and plugins as possible, so please help us improve and expand 
-this set of connector frameworks.
+If you need a connector for a platform not listed above you need to implement
+your own using our provided connector frameworks. The latest versions of the 
+connector frameworks can be found in [Subversion](http://svn.apache.org/repos/asf/incubator/wookie/trunk/connector/).
 
-### Viewer
+The documentation below refers to the Java connector. As far as possible we've kept
+to the names and method signatures the same in the connector framework for each 
+language.
+
+### Implementing a Connector for your Platform
+
+To implement the connector you simply need to create an implementation of the 
+[AbstractWookieConnectorFrameowrk][1] class. This class provides abstract methods
+for communicating with the host environment.
+
+We provide a [reference implementation][2] of this AbstractClass that is used within
+Wookie itself. 
+
+### Concepts
+
+This section introduces the various concepts you need to understand in order to 
+build a connector for your host application.
+
+#### Viewer
 The viewer is the current user who is viewing a widget in the browser. 
 Typically an application uses session information to know who the current user is, 
 and this is used to request a particular widget instance. It is up to the plugin 
 to determine how to identify the viewer; for example the user's real id is one 
 possibility; another is an opaque hashcode using the id.
 
-### Widget Instance
+#### Widget Instance
 A widget instance is a persistent instance of a particular widget created for a user. Each widget instance has its own storage area in Wookie. Widget Instances are created by invoking the Wookie REST API using an API Key and supplying values for the viewer and the shared data key.
 
-### API Key
+#### API Key
 An API Key is used to access many of the features of the Wookie REST API. Each individual web application needs its own API key. API Keys are generated from Wookie's administration interface.
 
-### Shared Data Key
+#### Shared Data Key
 The shared data key is an arbitrary identifier that marks widget instances as being sibling instances that can share state information. It is up to the plugin to determine this value; typically there is a persistent identifier available for whichever view is being used as the container for a widget.
 
-## Building Plugins with the Connector Framework
-
-The Java connector framework is used within Wookie itself and is therefore 
-considered the reference implementation. Other connector frameworks include PHP, 
-C#, Ruby and Python. However, even the Java framwork is incomplete and some 
-activities are accessed directly through the REST API (see next section). We welcome your help in expanding the framework code (in any language) so that all features can be accessed through it.
-
-See [Subversion](http://svn.apache.org/repos/asf/incubator/wookie/trunk/connector/) for 
-the latest available code.
-
-All code examples in this page are in Java, but other languages will use the same method names and parameters.
-
-### Basic usage of the framework
+## Basic usage of the framework
 
 In this section we document the most basic use of the connector framework. All example code is written in Java, but it should be the same in other languages (if not, help us bring them all up to date).
 
@@ -142,3 +144,6 @@ To do this you will need an URL for retr
     String url = instance.getUrl(); // get the URL from the WidgetInstance
     displayWidget(url); // a method you implement that displays the data at the URL
 
+
+  [1]: https://svn.apache.org/repos/asf/incubator/wookie/trunk/connector/java/src/org/apache/wookie/connector/framework/AbstractWookieConnectorService.java
+  [2]: http://svn.apache.org/repos/asf/incubator/wookie/trunk/connector/java/src/org/apache/wookie/connector/framework/WookieConnectorService.java
\ No newline at end of file