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
