Here is a first pass at a newbie FAQ. There's still lots I'd like to
add, but I thought I'd let the community have a look at this point:
Shindig Newbie FAQ
v 0.1
by Jordan Zimmerman
* Who this FAQ is For
* Someone starting from "square one" with Shindig
* Developers needing to integrate Shinding into their app
* Shindig developers who are at their wits end
* Shindig is an application not a code library
* Can only be hosted in a Servlet Container that supports WARs
* If you are used to code libraries, take a step back. Shindig is a
self-contained application. You plug into it to integrate with
your
application.
* Shindig is, essentially, undocumented
* Shindig does not have a user manual of any kind
* You must search the net for documentation
* Some of the docs are good
* Some are out of date
* See the "Important URLs" section below from some helpful links
* Important directories:
* <shindig>/java/server/target - maven target for the built Shindig
WAR:
shindig-server-1.1-SNAPSHOT.war
* Main source directories:
<shindig>/java/common/src/main/java
<shindig>/java/gadgets/src/main/java
<shindig>/java/server/src/main/webapp
<shindig>/java/social-api/src/main/java
* Learn how to use Maven
* Shindig is built via Maven
* In order to integrate with your app, you will need to change
Shindig
files and rebuild Shindig
* Learn about Guice and dependency injection
* Shindig is built using Google's Guice dependency injection library
* The only way to integrate your own code is via Guice
* You need to write a Guice module
* In order to integrate with your app, you will need to write a
Guice
Module
* This module needs to be added to Shindig's web.xml list of modules
* Your module _replaces_ SampleModule.java
* Your module will most likely need to copy some of the code in
SampleModule.java
* You will need to modify web.xml
* Shindig's main web.xml must be modified to add your code
* location: <shindig>/java/server/src/main/webapp/WEB-INF/web.xml
* Implement PersonService, AppDataService, and ActivityService
* These are the closest things to APIs in Shindig
* These interfaces handle data storage/retrieval for various
OpenSocial
methods
* You need to register your implementations of these interfaces in
your
Guice module
* This doc is not bad:
http://cwiki.apache.org/SHINDIG/providing-your-own-data-service-implemen
tation.html
* SecurityToken
* The SecurityToken object is the key to integrating your app with
Shindig
* There are lots of methodologies for doing this
* One option is to register (via your Guice module) an
implementation of
The AuthenticationHandler interface. The important method is
getSecurityTokenFromRequest().
* OAuth
* You should read the OAuth spec/docs: http://oauth.net/
* OAuth is an authentication specification
* For Shindig/OpenSocial, it allows a server to validate OS
makeRequest() calls
* This FAQ does not deal 3-legged OAuth
* To get OAuth working, you only need to implement the OAuthStore
interface and register it via your Guice module
* On your server that handles the makeRequest() method, you can use
the
code from ouath.net to validate the OAuth parameters
* The existing OAuth Shindig docs are confusing. Read them, but
realize
that you need more info than they provide.
* Container, iframe, Hostnames
* You will read about the "container". Shindig is an OpenSocial
container. However, Shindig has its own concept of a container: a
page
that contains gadgets. Think of an iGoogle page with applets in
it.
The iGoogle page is the container.
* Each gadget is a self-contained <iframe> in the container page.
* For security reasons, the gadget iframe URL should be a hostname
_different_ than the container hostname. This prevents the gadget
from
getting the container's cookies, DOM, etc.
* A lot of Shindig docs assume that your container is written in
pure
Javascript. However this is not a requirement.
* Container Responsibilities
* TBD
* Important URLs:
* http://incubator.apache.org/shindig/
* http://cwiki.apache.org/SHINDIG/index.html
*
http://cwiki.apache.org/SHINDIGxSITE/how-to-support-features-that-depend
-on-gadgetsrpc.html
* http://incubator.apache.org/shindig/mail-lists.html (subscribe to
these listservs)
* http://code.google.com/p/mediated-opensocial/ - this is how this
FAQ
writer integrated Shindig
Jordan Zimmerman
Principal Software Architect
831.647.4712
831.214.2990 (cell)
[email protected]
SHOP*COMTM
Shop Smart, Save Big(tm)
www.shop.com
This message (including any attachments) is intended only for
the use of the individual or entity to which it is addressed and
may contain information that is non-public, proprietary,
privileged, confidential, and exempt from disclosure under
applicable law or may constitute as attorney work product.
If you are not the intended recipient, you are hereby notified
that any use, dissemination, distribution, or copying of this
communication is strictly prohibited. If you have received this
communication in error, notify us immediately by telephone and
(i) destroy this message if a facsimile or (ii) delete this
message
immediately if this is an electronic communication.
Thank you.
