Make Your Site an OpenSocial Container Using Shindig

Important disclaimer: This document was written for Shindig v0.7. Lab 3 will no longer work with the latest Shindig.

Chris Schalk, Google Developer Advocate
Chris Chabot, Apache Shindig Committer

(updated on 5/30/08)

Overview

The goal of these tutorials is to provide you with sufficient background on how to checkout, build and develop with Shindig with a goal of turning it into your own social networking site.

Important Notice: Since Shindig is a new and evolving Open Source project that has yet to release in an official alpha or beta release capacity, working with it does require some relatively advanced software development skills. Please check to see if the pre-requisites for the lab exercises are within your capacity before attempting them.

These tutorials are segmented into the following portions:

Java Exercises - These exercises are for those comfortable with the Java programming language as they deal with the Java version of Shindig.

PHP Exercises - These exercises are for those who use PHP as their programming language. These steps get you up and running with a PHP version of Shindig. Note: Labs 4 and 5 are entirely independent of the Java version of Shindig used in labs 1-3. Java developers needn't bother with these exercises and PHP developers needn't bother with the Java exercises.

Goals of these exercises

These exercises are meant to familiarize yourself with Shindig software development. You shouldn't have to complete all the exercises within 2 hours, instead you can start these and then continue to work on them on your own time. As you complete these exercises you will have a firm understanding of how to work with the Shindig code and potentially becoming a contributing member of this project!

 

 

Lab 1: Checking out, building and running Shindig


This lab explains how to check out the entire Shindig code base and build and run the Java portion of Shindig.

These steps were taken and adapted from: http://incubator.apache.org/shindig/#tab-building

 

Prerequisites before building the Java portion of Shindig

In order to build Shindig, you must have the following:

Getting the code

Create a subdirectory on your filesystem and checkout the Shindig code from its Subversion repository.
Here's an example of making a Shindig directory in a Unix based environment.

  1. mkdir ~/src/shindig (this is also referred to as <shindig_home> later in the exercises)
  2. cd ~/src/shindig
  3. svn co http://svn.apache.org/repos/asf/incubator/shindig/trunk/ .

Building and running the code (with Maven)

To build the entire Shindig and run tests, perform the following:

  1. Make sure you have the prerequisites installed first.
  2. cd ~/src/shindig/
  3. mvn (This executes a top level build of Shindig)
  4. Once the build completes, you can run Shindig with:
    mvn -Prun

This will start Shindig in a local Jetty server that will run at localhost:8080. Note: mvn -Prun is the same as changing to the ..shindig/java/server and executing:

  1. mvn jetty:run-war

To run the Jetty server on a different port, use:

  1. mvn -Djetty.port=<port> jetty:run-war

Testing your running Shindig instance using the sample container

Once you are running locally using the Jetty server, you can check to see if Shindig is running by visiting:

Some further facts about the SampleContainer

You'll notice that the samplecontainer as a default points to a test OpenSocial application at:


This is a very basic HelloWorld OpenSocial application example.

Feel free to inspect the source files for the sample container. They are located in <shindig_home>/javascript/samplecontainer


These include:



To experiment with the samplecontainer a bit, you can load other OpenSocial applications described at the code.google.com/opensocial documentation pages. For example, feel free to try out the tutorials listed at:
http://code.google.com/apis/opensocial/docs/0.7/devguide.html

A first example test is to try out the simple listfriends application. The source code for this application is listed here:
http://code.google.com/apis/opensocial/docs/0.7/devguide.html#ListFriends_Complete

---------------------------------------------------------

Lab 2: Editing and Debugging Shindig in Eclipse

This lab explains how to work with Shindig in Eclipse.

To improve the Java development experience, it's helpful to use an IDE such as Eclipse. It is relatively easy to setup Shindig to be able to be run or debugged directly from Eclipse as opposed to running from a command line.

The following steps for running Shindig from Eclipse are based on these original instructions:
http://incubator.apache.org/shindig/#eclipseProject

Note: This lab is entirely optional and is not required to build and run Shindig. Lab 3 also does not require this lab be completed as a pre-requisite.

Installing Maven to work with your Eclipse IDE

The first steps to enabling Eclipse to work with Shindig is to install the Maven plugin for Eclipse. This will allow you to build Shindig from Eclipse using Maven's dependencies.

To get started, in your home directory, create an empty Maven settings file:

The Maven will store a repository of downloaded files in this directory.

Installing the Maven plugin and setting up your Shindig workspace

In order to easily build, package and launch Shindig directly from Eclipse for debugging purposes, you can install the Eclipse Maven plugin.

 

Creating a Java project in Eclipse for the Shindig code

Before creating an Eclipse project to work with Shindig code, it's helpful to understand the Shindig Java code organization. The Java code for Shindig is divided into 3 separate code projects and a utility Web project for running Shindig:

Although it is possible to create Eclipse Java projects for each of these Shindig projects, you will not be able to compile using Maven within Eclipse because of the project's interdependencies. Instead you should simply create a single Java project that maps to the entire Shindig codebase. This allows Maven to successfully compile the source code across all Java projects from within Eclipse.

To create an Eclipse Java project for Shindig do the following:

Enabling Maven for your new Eclipse projects

Creating run and debug profiles in Eclipse

Running Shindig out of the box is possible by using the included Jetty server. Maven can start Jetty directly with the command, "mvn jetty:run" or "mvn jetty:run-war". These would be executed in the <shindig_home>/java directory. Shindig however now uses a higher level "mvn -Prun" which also starts Jetty as well but it is launched directly from the <shindig_home> directory. In order to run Shindig from Eclipse, you can set up run and debug profiles within Eclipse that execute this same high level mvn command ("mvn -Prun").

To create an external tools run profile to execute the command "mvn -Prun", do the following:

(Running Jetty from mvn steps adapted from: http://cwiki.apache.org/WICKET/maven-jetty-plugin.html )

  1. In eclipse, from the main menu, select: "Run --> External Tools --> Open External Tools Dialog..."
  2. In the upper left hand corner of the dialog click on the icon for "New launch configuration".
  3. You can name this configuration something like: "mvn_run".
  4. On the "Main" tab, fill in the "Location:" as the full path to your "mvn" executable.
    For example: /usr/local/apache-maven/apache-maven-2.0.8/bin/mvn
  5. Edit the "Working Directory:" field. Select the workspace and project that matches your Shindig project. Ex: ${workspace_loc:/shindig-all}
  6. For Arguments: add "-Prun" (without quotes).
  7. In the same dialog, now click on the "Environment" tab.
  8. Add these two variables with values:
    JAVA_HOME
    { path to parent of your Java bin directory. ex: /usr }
    MAVEN_OPTS
    -Xdebug -Xnoagent -Djava.compiler=NONE -Xrunjdwp:transport=dt_socket,address=4000,server=y,suspend=y

  9. Click Apply and Close.

You can now launch Shindig with a JPDA port of 4000.

To debug Shindig, you'll need to create a Debug profile.
This step allows you to launch your Shindig project in debug mode and attach to Jetty.

  1. In Eclipse, form the main menu, select "Run --> Open Debug Dialog..."
  2. In the dialog, select "Remote Java Application".
  3. Click on the icon for "New launch configuration".
  4. Feel free to name this configuration, "shindig_debug".
  5. For the "Project:", select your shindig server project that you created earlier. (ex: shindig-all).
  6. Under the "Connection Properties" set the port to 4000, which is the same "address=" port specified in your Jetty run configuration above.
  7. Click Apply and Close.
  8. That's it, you can now run Shindig from Eclipse!

Launching Shindig in debug mode

Launching Shindig in your debugger is actually a 2 step process.

  1. Invoke your "external tool" (mvn_run) by selecting from the main menu "Run --> External Tools --> Open External Tools Dialog..."
  2. Select your run profile: "mvn_run" and run it.
    You will see the following in the console:
    "Listening for transport dt_socket at address: 4000"
  3. You can now launch Shindig by selecting form the main menu: "Run--> Open Debug Dialog..." and selecting your "shindig_debug" profile and running it.
    This will launch Shindig locally as you'll see the server startup in the console on port 8080.

 

Lab 3: Integrating Shindig with an external database

Note: This was written for Shindig version 0.7. It will not work with the latest versions of Shindig/OpenSocial.

This lab explains how to integrate Shindig with an external database. This is done by showing an example of how to implement the three interface that Shindig provides: ActivitiesService, PeopleService and DataService. The codelab steps through how to customize Shindig with this code along with setting up a MySQL database to serve as the backend database.

 

DataBase and Patch Required Downloads

Important Note: This lab uses both:

You can download these files and use them later in this lab. For the SQL script, simply right-click on the link and save as "opensocial_mysql.sql" on your filesystem.

For the patch file, be sure to unzip it into the "sql-patch.patch" text file before attempting to patch Shindig. Also to apply this patch, you'll need to have the command line "patch" utility on your system. If you don't have this, on your system, instructions are provided later in the lab explaining how to obtain/install this.

Note: If you don't have the "patch" utility and can't install it, as a backup, you can manually patch your Shindig with the contents from here: shindig_sql.zip. See the included readme file for instructions on how to manually patch Shindig with the SQL code.


Installing MySQL on your system

This tutorial uses a MySQL database as a backend data store to Shindig. If you don't have a MySQL database, the steps for downloading and installing a MySQL database can be found here:
http://www.mysql.com/

The free "community server" edition of MySQL which runs on all the major OS platforms is sufficient for these exercises and can be found at: http://dev.mysql.com/downloads/

After installing the MySQL database, you might want to also install the GUI Tools available for MySQL. These are available at:
http://dev.mysql.com/downloads/gui-tools/5.0.html

Although the GUI Tools are not required, the 'MySQL Administrator' tool is extremely helpful when setting up any MySQL database. It can be downloaded from the MySQL website.

Setting up a MySQL schema for OpenSocial

  1. Setup an 'opensocial' schema. Log into MySQL as the root user. You should know how to do this after installing your database. 
    > mysql -u root -p
  2. As mysql root, create a new database:
    mysql> create database opensocial;

After creation of the new database, create a new user named 'opensocial' with a password 'opensocial'.
Note: These default username and password values correspond to a Java class (SQLDataLayer.java) which makes a connection to a local database with the same username and password. If you use another username and password here, you'll have to edit this Java class. More info on the Java class is provided later in the tutorial. 

mysql>use opensocial;
mysql>create user opensocial identified by 'opensocial';
mysql>grant all on opensocial.* to 'opensocial'@'localhost' identified by 'opensocial';

3. Install SQL objects using provided script: opensocial_mysql.sql: (be sure to return to the OS prompt again using 'mysql>quit;' and then execute:)

>mysql -u opensocial --password="opensocial" opensocial < /<path_to>/opensocial_mysql.sql

4. Check to see if database installed correctly.

>mysql -u opensocial --password="opensocial" opensocial
mysql> show tables;
(You should see:)
   +----------------------+
   | Tables_in_opensocial |
   +----------------------+
   | activities           | 
   | activity_media_items | 
   | activity_streams     | 
   | addresses            | 
   | movies               | 
   | music                | 
   | organizations        | 
   | people               | 
   | person_appdata       | 
   | person_friends       | 
   | quotes               | 
   | urls                 | 
   +----------------------+

Feel free to issue some more queries:

To see all people preloaded:

mysql>select os_id, name from people;

To see all activities:

mysql>select * from activities;


Congratulations! You now have an OpenSocial schema installed on your MySQL database!

Patching Shindig to communicate with your database

This portion of the codelab involves customizing Shindig to communicate with your newly installed database with OpenSocial data. The changes required for this are to add a new set of Java classes that implement the PeopleService, ActivitiesService and DataService interface but instead of reading from a static XML file, they provide a two way communication with a backend MySQL database.

 

For this exercise you will use a "patch" file to patch your build of Shindig with the necessary Java classes and example code. The link for the patch file was mentioned at the beginning of this lab.

After downloading the patch file into a location such as /tmp/sql-patch.patch.gz, unzip it. You should now have a text file: /tmp/sql-patch.patch.

A quick note on the "patch" utility used in this lab.

To apply the "sql-patch" patch, you will use the command line patch utility. Unix environments including MacOS have this utility already. For Windows users, you'll need to download a GNU version of the "patch" from here:

http://gnuwin32.sourceforge.net/packages/patch.htm

 

Applying the patch

  1. Change into the base directory of Shindig. (Above the subdirectories /java , /php etc.).
  2. Clean out the Shindig codebase. Use "mvn clean".
  3. Using the patch utility, execute:
    patch -Np0 < /tmp/sql-patch.patch
  4. Once the patch is applied, you can then rebuild Shindig using "mvn", or "mvn install".
  5. Note, if you get compilation errors, try cleaning Shindig again, and then rebuilding.
  6. Also, if you do not use the default opensocial/opensocial user name and password for the database, you will have to edit a Java file contained in the patch with your database connection information.
    • To customize the database connection info, you'll need to edit the file <shindig_home>/java/social-api/src/main/java/org/apache/shindig/social/samplecontainer/sql/SQLDataLayer.java.
    • Change the lines:
       // Customize as needed
 private static final String DB_URL = "jdbc:mysql://localhost:3306/opensocial";
 private static final String DB_UID = "your_opensocial_username";
 private static final String DB_PW = "your_opensocial_password";
    • Save the new Java class and rebuild Shindig by executing "mvn" from the Shindig home directory.
  7. You should now be able to run Shindig again using "mvn -Prun" - or if using Eclipse, you can launch Shindig using your run/debug profiles.
  8. You can then see the new patched container again using:

http://localhost:8080/gadgets/files/samplecontainer/samplecontainer.html

Also, to experiment with a simpler client page, use:

http://localhost:8080/gadgets/files/samplecontainer/simplecontainer.html

This second link points to a simplified version of a Shindig samplecontainer client page and allows you to easily test 3 simple included example OpenSocial applications that use the the three services of OpenSocial; Activities, People, and Data.

 

Lab 4: Checking out and configuring Shindig for PHP on Apache

Both lab 4 and 5 explain how to work with the PHP version of Shindig. Please contact Chris Chabot through the shindig-dev mailing list for further questions.

Important: In order to successfully work with this lab, you must have the following set up:

Without these pre-requisites installed first, this lab is not possible.

Checking out the PHP version of Shindig is essentially the same as checking out the Java version as explained in Lab 1.

However for easiest development, it's best to check out the Shindig code beneath your HTML root of your PHP enabled Apache HTML root. So for example if your Apache HTML root is '/var/www/html', you could checkout the Shindig code directly into a subdirectory of this.

Here's how you would checkout Shindig into a subdirectory named 'shindig' beneath the Apache HTML root :

  1. cd /var/www/html
  2. svn co http://svn.apache.org/repos/asf/incubator/shindig/trunk/ shindig

Now instead of building the Java sources located in /java, you can instead work with the PHP sources in /php.

 

Setting up PHP Shindig

With PHP There is no need to build anything - the source code is already built.

To run the code, you have several options:

a. Create a new virtual host

Edit your httpd.conf (or on some systems this is the vhost.conf). Point your apache to the php dir with a virtual host like:

		<VirtualHost your_ip:your_port>
	
		       ServerName your.host
		       DocumentRoot /var/www/html/shindig/php
		       ... other normal settings in vhosts...
		</VirtualHost>

Restart apache, and point your browser to:

http://your.host/gadgets/ifr?url=http://www.labpixies.com/campaigns/todo/todo.xml

you should see something like this.

b. Run with an existing host

If you cannot/don't want to create a virtual host, you can edit the file php/config.php and change the web_prefix setting to '/shindig/php'.

Then you can run the gadget by pointing your browser to:

http://your.host/shindig/php/gadgets/ifr?url=http://www.labpixies.com/campaigns/todo/todo.xml

Additional reading

Read php/README for original instructions on how to start up the php shindig server.

Read javascript/README for instructions for using the Shindig Gadget Container JavaScript to enable your page to render Gadgets using gmodules.com or a server started up as described above.

 

Lab 5: Installing and running Partuza

This lab explains how to install and run Partuza, which is a PHP based social networking site that uses the PHP version of Shindig.

Please see the instructions at:

http://code.google.com/p/partuza/wiki/GettingStarted