Be Social by running SocialSite on Tomcat

Sometime ago, I saw an announcement of the first release of SocialSite. Basically it is a Java implementation to add social features to your existing website. Check out Arun Gupta's blog on the usage of SocialSite. I thought of trying it out and it works fine on Glassfish. Out of the box there was no way of getting it to work on another container, such as Tomcat. Not very social I thought :-)

Anyway thought of trying to get it to run on Tomcat. Following is the procedure to get SocialSite to work on Tomcat. If you understand and follow what is going on, and why each of these steps is being done, it should be trivial to port SocialSite to run on any other container.

These instructions are for Tomcat 5.5 and MySQL. I would rather you proceed with the source code download of SocialSite and build the distribution from there. You can download the distribution from the SocialSite site, and add the following things mentioned in your downloaded bundle, but I haven't tested that. But I don't see a reason why that shouldn't work either.

So go ahead, download the source code for the SocialSite as per instructions given here. Once you have the source code downloaded, follow the steps given below to get SocialSite to work on Tomcat.

SOCIALSITE_SRC_HOME is where you downloaded the source code for SocialSite.

• Configure the JNDI Resource for the database and Mail


• Update persistance related entries of SocialSite so Tomcat loves them


• Build the SocialSite distribution


• Create tables in database of your choice


• Create the Realm for SocialSite


• Enable SSO Valve


• Prepare Tomcat for being SocialSite enabled by making JARS available to apps.


• Enable JSTL in Tomcat


• Enable SSL on tomcat, or disable SSL login in SocialSite

Configure the Global JNDI Resource for the database.

SocialSite uses a JNDI resource by the name of 'jdbc/SocialSite_DB' to access your database. So you need to create a JNDI resource by that name. You can refer to the Tomcat 5.5 documentation page here to get information on how to define a per-application JNDI resource using the <Resource> tag in your context.xml. Or you can read along as I show below how to do it.

Under the SOCIALSITE_SRC_HOME/web/META-INF there is a file called context.xml. Make sure it looks following and save the file. Ofcourse make sure that entries for url, username and password do match for your MySQL database, so that the connection to the DB succeeds. The other JNDI resource is about javax.mail.Session that SocialSite uses to send out e-mails.

<Context path="/socialsite">



   <Resource name="jdbc/SocialSite_DB" auth="Container"

     type="javax.sql.DataSource" user="root" username="root" password="abc123"

     driverClassName="com.mysql.jdbc.Driver" url="jdbc:mysql://localhost:3306/socialsite"

     maxActive="100" maxIdle="30" maxWait="10000"/>

   <Resource name="mail/SocialSite/Session" auth="Container"

     type="javax.mail.Session"

     description="Mail Session for SocialSite" scope="Shareable" />



</Context>

Update persistance related entries of SocialSite so Tomcat loves them

The default SocialSite install works on Glassfish. Glassfish is a container which supports the JavaEE 5 specification and hence has a persistence engine built-in. SocialSite uses the JPA features to interface to a database. So to get SocialSite to work with Tomcat we need to enable persistence capabilities in it. Fortunately SocialSite bundles the EclipseLink libraries which include a persistence provider.

However, the persistence.xml included in the SocialSite includes a persistence.xml which tries to lookup the DB via a JNDI lookup. This doesn't work outside a EJB container by default, and Tomcat is not a EJB container. So to enable EclipseLink to pick up the DB details we need to configure it as we would be doing in a pure Java SE environment. For doing this you will have to modify the SOCIALSITE_SRC_HOME/src/java/META-INF/persistence.xml accordingly. The entries which you have to modify are indicated in red. Make sure the entries for the DB marked in red are correct for your DB install.

<!--

   DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.

 Copyright 2007-2008 Sun Microsystems, Inc. All rights reserved.

 The contents of this file are subject to the terms of either the GNU

   General Public License Version 2 only ("GPL") or the Common Development

   and Distribution License("CDDL") (collectively, the "License").  You

   may not use this file except in compliance with the License. You can obtain

   a copy of the License at https://socialsite.dev.java.net/legal/CDDL+GPL.html

   or legal/LICENSE.txt.  See the License for the specific language governing

   permissions and limitations under the License.

 When distributing the software, include this License Header Notice in each

   file and include the License file at legal/LICENSE.txt.  Sun designates this

   particular file as subject to the "Classpath" exception as provided by Sun

   in the GPL Version 2 section of the License file that accompanied this code.

   If applicable, add the following below the License Header, with the fields

   enclosed by brackets [] replaced by your own identifying information:

   "Portions Copyrighted [year] [name of copyright owner]"

 Contributor(s):

 If you wish your version of this file to be governed by only the CDDL or

   only the GPL Version 2, indicate your decision by adding "[Contributor]

   elects to include this software in this distribution under the [CDDL or GPL

   Version 2] license."  If you don't indicate a single choice of license, a

   recipient has the option to distribute your version of this file under

   either the CDDL, the GPL Version 2 or to extend the choice of license to

   its licensees as provided above.  However, if you add GPL Version 2 code

   and therefore, elected the GPL Version 2 license, then the option applies

   only if the new code is made subject to such option by the copyright

   holder.

   -->

<persistence xmlns="http://java.sun.com/xml/ns/persistence" version="1.0">

 <persistence-unit name="SocialSite_PU" transaction-type="RESOURCE_LOCAL">

   <provider>org.eclipse.persistence.jpa.PersistenceProvider</provider>

   <!-- <provider>oracle.toplink.essentials.ejb.cmp3.EntityManagerFactoryProvider</provider> -->

   <!-- <provider>org.apache.openjpa.persistence.PersistenceProviderImpl</provider> -->

   <!-- <provider>org.hibernate.ejb.HibernatePersistence</provider> -->

   <!--<non-jta-data-source>java:comp/env/jdbc/SocialSite_DB</non-jta-data-source>-->

 

 

   <class>com.sun.socialsite.pojos.ActivityContent</class>

   <class>com.sun.socialsite.pojos.ApiKey</class>

   <class>com.sun.socialsite.pojos.Content</class>

   <class>com.sun.socialsite.pojos.FriendRelationship</class>

   <class>com.sun.socialsite.pojos.FriendRequest</class>

   <class>com.sun.socialsite.pojos.Gadget</class>

   <class>com.sun.socialsite.pojos.Group</class>

   <class>com.sun.socialsite.pojos.GroupProperty</class>

   <class>com.sun.socialsite.pojos.GroupRelationship</class>

   <class>com.sun.socialsite.pojos.GroupRequest</class>

   <class>com.sun.socialsite.pojos.InstalledGadget</class>

   <class>com.sun.socialsite.pojos.InstalledGadgetProperty</class>

   <class>com.sun.socialsite.pojos.MessageContent</class>

   <class>com.sun.socialsite.pojos.MessageContentState</class>

   <class>com.sun.socialsite.pojos.PermissionGrant</class>

   <class>com.sun.socialsite.pojos.Profile</class>

   <class>com.sun.socialsite.pojos.ProfileProperty</class>

   <class>com.sun.socialsite.pojos.RuntimeConfigProperty</class>

   <class>com.sun.socialsite.pojos.SocialRequest</class>

   <class>com.sun.socialsite.userapi.User</class>

   <class>com.sun.socialsite.userapi.UserRole</class>

   <class>com.sun.socialsite.userapi.Permission</class>

 <properties>

   <property name="eclipselink.jdbc.platform" value="oracle.toplink.platform.database.mysql"/>

   <property name="eclipselink.jdbc.driver" value="com.mysql.jdbc.Driver"/>

   <property name="eclipselink.jdbc.url" value="jdbc:mysql://localhost:3306/socialsite"/>

   <property name="eclipselink.jdbc.user" value="root"/>

   <property name="eclipselink.jdbc.password" value="abc123"/>

   </properties>



   </persistence-unit>

   <persistence-unit name="SocialSite_PU_Standalone" transaction-type="RESOURCE_LOCAL">

   <provider>org.eclipse.persistence.jpa.PersistenceProvider</provider>

   <!-- <provider>oracle.toplink.essentials.ejb.cmp3.EntityManagerFactoryProvider</provider> -->

   <!-- <provider>org.apache.openjpa.persistence.PersistenceProviderImpl</provider> -->

   <!-- <provider>org.hibernate.ejb.HibernatePersistence</provider> -->

   <class>com.sun.socialsite.pojos.ActivityContent</class>

   <class>com.sun.socialsite.pojos.ApiKey</class>

   <class>com.sun.socialsite.pojos.Content</class>

   <class>com.sun.socialsite.pojos.FriendRelationship</class>

   <class>com.sun.socialsite.pojos.FriendRequest</class>

   <class>com.sun.socialsite.pojos.Gadget</class>

   <class>com.sun.socialsite.pojos.Group</class>

   <class>com.sun.socialsite.pojos.GroupProperty</class>

   <class>com.sun.socialsite.pojos.GroupRequest</class>

   <class>com.sun.socialsite.pojos.GroupRelationship</class>

   <class>com.sun.socialsite.pojos.InstalledGadget</class>

   <class>com.sun.socialsite.pojos.InstalledGadgetProperty</class>

   <class>com.sun.socialsite.pojos.MessageContent</class>

   <class>com.sun.socialsite.pojos.MessageContentState</class>

   <class>com.sun.socialsite.pojos.PermissionGrant</class>

   <class>com.sun.socialsite.pojos.Profile</class>

   <class>com.sun.socialsite.pojos.ProfileProperty</class>

   <class>com.sun.socialsite.pojos.RuntimeConfigProperty</class>

   <class>com.sun.socialsite.pojos.SocialRequest</class>

   <class>com.sun.socialsite.userapi.User</class>

   <class>com.sun.socialsite.userapi.UserRole</class>

   <class>com.sun.socialsite.userapi.Permission</class>

   </persistence-unit>

</persistence>

Build the SocialSite distribution

From SOCIALSITE_SRC_HOME execute

ant dist

The above will build a folder called SOCIALSITE_SRC_HOME/dist under which the SocialSite distribution is created. In the distSocialSite/webapp folder is the socialsite.war file. Make sure the two steps you did above do end up showing properly in the built war file.

Create tables in database of your choice

Under the SOCIALSITE_SRC_HOME/dist/SocialSite/dbscripts directory there are directories, one for each database supported. Choose MySQL ( since I did the setup with MySQL ). Login to MySQLAdmin, and create a database of name 'socialsite'. The DB name can be anything of your choice. Make note of this name, as this is the name of the DB we will be using in all JDBC URL's which get configured in different steps in this blog. Now go ahead and execute the createdb.sql script in the context of the 'socialsite' database.

Create the Realm for SocialSite

Socialsite by default authenticates users to a realm named "SocialSite_UserRealm". So you must create this realm in Tomcat. You can refer to docs for information on how to create a realm. Or if you are impatient here is how you do it. Open the file TOMCAT_HOME/conf/server.xml and add the following line to it. There are several entries in this file for JDBCRealm, but they are commented by default. Uncomment the one for MySQL, and make sure your entry matches the one below. Ofcourse, change parameters to match your database configuration.

<Realm  className="org.apache.catalina.realm.JDBCRealm"

   driverName="org.gjt.mm.mysql.Driver"

   connectionURL="jdbc:mysql://localhost:3306/socialsite"

   connectionName="root" connectionPassword="abc123"

   userTable="userapi_user" userNameCol="username" userCredCol="passphrase"

   userRoleTable="userapi_userrole_view" roleNameCol="rolename" 

   resourceName="SocialSite_UserRealm" digest="SHA"/>

Enable SSO Valve

Enable the SSO valve in TOMCAT_HOME/conf/server.xml. It is already there and probably commented out.

   <Valve className="org.apache.catalina.authenticator.SingleSignOn" />

Prepare Tomcat for being SocialSite enabled by making JARS available to apps.

Glassfish is a JavaEE compliant App server and hence has the full webservices stack bundled with it. For Tomcat you need to enable this stack, since SocialSite uses some parts of it. For that purpose,

1. Download the JAX-WS RI from hte JAX-WS site. Copy all jars (except sjsxp.jar) from the JAX-WS-INSTALL/lib folder to the TOMCAT_HOME/shared/lib folder.


2. Copy sjsxp.jar to the TOMCAT_HOME/common/endorsed directory.


3. Also download the stax.jar from here and copy that jar also the TOMCAT_HOME/common/endorsed directory.


4. Copy mail.jar and MySQL JDBC Driver (mysql-connector-java-3.1.12-bin.jar) to TOMCAT_HOME/common/lib folder.

Enable JSTL in Tomcat

Tomcat 5.5 doesn't have JSTL support by default. From the Jakarta JSTL site, they seem to suggest to use the Glassfish JSTL implementation. So following that, we pick up the appserv-jstl.jar from the GLASSFISH_HOME/lib to TOMCAT_HOME/common/lib folder.

Enable SSL on tomcat, or disable SSL login in SocialSite

Follow this page on Tomcat docsIf you enable SSL on Tomcat on port 8443.

SocialSite Admin Site

To enable SocialSite administration, under the SOCIALSITE_SRC_HOME/dist/SocialSite/bin folder there is a setup-glassfish.xml file. In this there is a create-admin-user target. Run that target as follows:

ant -f setup-glassfish.xml create-admin-user

to create an admin user for your socialsite installation. You might have to fill in properties in the sjsas.props file to get it to work fine.