Neo4j WebSocket backend for Apache Shindig What is it? ----------- The client part of an Apache Shindig Backend using a Neo4j Websocket Server with custom server side routines. System Requirements ------------------- Java: 1.7 or above. Apache Shindig: 2.5.2 Neo4j WebSocket common resources for Apache Shindig: shindig-websocket-common Neo4j WebSocket common resources: neo4j-websocket-common Neo4j WebSocket Client: neo4j-websocket-client Neo4j WebSocket Server with Apache Shindig WebSocket Server Routines: neo4j-websocket-server shindig-websocket-serverroutines Apache Maven (for building) 3.x Installing Neo4j WebSocket backend for Apache Shindig ----------------------------------------------------- For an installation instructions for the Neo4j WebSocket Client and Neo4j WebSocket common resources, see the client's documentation. The client's sources can be found at "https://github.com/iisys-hof/neo4j-websocket-client" and can be downloaded using git by executing 'git clone https://github.com/iisys-hof/neo4j-websocket-client.git'. Its README file contains installation instructions for the common library. Installing to local Maven repository: 1. Download the source code of "shindig-websocket-common" and extract it The projects's sources can be found at "https://github.com/iisys-hof/shindig-websocket-common" and can be downloaded using git by executing 'git clone https://github.com/iisys-hof/shindig-websocket-common.git'. 2. Open a terminal and enter the root directory containing the file pom.xml 3. execute 'mvn install' 4. Download the source code of "shindig-websocket-client" and extract it 5. Open a terminal and enter the root directory containing the file pom.xml 6. execute 'mvn install' Alternatively, you can use precompiled jars. Prerequisites: For the WebSocket backend to work, you will need a running instance of Neo4j WebSocket Server with Apache Shindig WebSocket Server Routines. The server's sources can be found at "https://github.com/iisys-hof/neo4j-websocket-server" and can be downloaded using git by executing 'git clone https://github.com/iisys-hof/neo4j-websocket-server.git'. In the server's root source directory you will find a file called 'README' explaining how to build it, set it up and configure it. The Java server routines for Apache Shindig ca be found at "https://github.com/iisys-hof/shindig-websocket-serverroutines" and can be downloaded using git by executing 'git clone https://github.com/iisys-hof/shindig-websocket-serverroutines.git'. In the projects's root source directory you will find a file called 'README' explaining how to build it and add these server routines to the server you set up. Installing and configuring for Apache Shindig deployment: 1. Extract an Apache Shindig war file 2. Copy the WebSocket backend jar and all its dependencies into the folder "WEB-INF/lib/". Pay attention to duplicate libraries. If you don't know how to collect the library jars, there is a section in the file "pom.xml" started by "uncomment to generate library directory". If you uncomment it and run a build ("mvn install" for example), there will be an additional "lib/" directory in the "target" directory. (Eclipse may show an error after doing this, but it will work with maven). 3. Open the file "WEB-INF/web.xml" 4. Find the section "<context-param> <param-name>guice-modules</param-name> <param-value>" 5. (optional) for extended functionality, i.e. graph specific requests, user creation, friendship handling and extended organization model replace "org.apache.shindig.social.core.config.SocialApiGuiceModule" with "org.apache.shindig.social.websockbackend.GraphAPIModule" 6. replace "org.apache.shindig.social.sample.SampleModule" with "org.apache.shindig.social.websockbackend.GuiceModule" 7. Get a copy of the file "websocket-backend.properties" and open it with a WYSIWYG editor. If you can't locate the file, there is a copy in the folder "src/main/resources/" of the sources. 8. Configure according to the next section called "websocket-backend.properties" and put the file in Shindig's "WEB-INF/classes" directory. 9. Repackage Shindig's war file and deploy it. websocket-backend.properties: websocket.uri0 - primary WebSocket URI, should point to the Neo4j WebSocket Server you prepared websocket.uri{n} - (optional) additional WebSocket URIs in case you set up a server cluster websocket.connections - number of connections per server; more connections to a server can improve performance in scenarios with many parallel requests websocket.format - format to send and receive data in; this should match your server's configuration websocket.compression - whether to use compression for the connection; this should match your server's configuration websocket.auth.user - (optional) user name to use for authentication only if the websocket server requires it websocket.auth.password - (optional) password to use for authentication only if the websocket server requires it can be either plain or hashed - for instructions on how to hash a password, see the documentation for 'neo4j-websocket-client' websocket.auth.password.hashed - (optional) whether the password provided is already hashed or not people.profileurl - (optional) needed for automatic profile URL generation, ${ID} will be replaced by the user's ID people.infourl - (optional) needed for automatic JSON profile URL generation, ${ID} will be replaced by the user's ID The other properties are used by components that have not yet been implemented for the WebSocket-based backend. Using Neo4j Neo4j WebSocket backend for Apache Shindig ------------------------------------------------------ Maven dependencies: <dependency> <groupId>de.hofuniversity.iisys</groupId> <artifactId>shindig-websocket-client</artifactId> <version>2.5.2-6</version> </dependency> <dependency> <groupId>de.hofuniversity.iisys</groupId> <artifactId>shindig-websocket-common</artifactId> <version>2.5.2-2</version> </dependency> Shindig's default OpenSocial services will work as specified. However, the deprecated ActivityService is not included. The client will connect to your server on Shindig's initialization. Extended functionality: If you enabled extended functionality, the following functionalities will be available. Extended person/organization model The following additional properties will be available for people's organizations: - managerId - (String) - the person's manager's ID - secretaryId - (String) - the person's secretary's ID - department - (String) - the person's department - departmentHead - (boolean) - whether the person is head of department - orgUnit - (String) - name of the person's organizational unit - location - (String) - location of the person in the company (i.e. room) Person service: The following additional API functions will be available among the existing ones: get - (modified) by supplying "@friendrequests" as the group ID you can see who sent you a friend request - returns a list of people create - (new) enables you to either create a person (default, returns the person) or request/confirm a friendship by supplying "@friends" as the group ID (returns nothing) takes a person object as a parameter (new person or the target) delete - (new) enables you to either delete/deactivate a person (default, no actual function yet) or deny/terminate a friendship by supplying "@friends" as the group ID Furthermore you will be able to filter people by all their fields by filtering by the field "@all". User/Graph service (name: "user"): This new service offers basic graph-based and user-centric functionalities: getAll - returns a list of all available/visible people REST path: "user/" additional features: filtering by "@all" fill search all of a person's fields filtering by "@skills" will search for people with matchings skills getFof - returns a list of friends of friends up to a certain depth REST path: "user/{userId}+/fof/{depth}/{unknown}" parameters: "depth" - how deep to traverse friendships (default: 2 (hops)) "unknown" - whether to only return people the user is not yet friends with (default: true) getSFriend - returns a list of friend suggestions REST path: "user/{userId}+/sfriend/{minFriends}" parameters: "minFriends" - how many friends the suggested people need to have in common with you getSGroup - returns a list of group suggestions REST path: "user/{userId}+/sgroup/{minFriends}" parameters: "minFriends" - how many friends need to be in the suggested groups getSPath - returns the shortest path defined by friendships between the user and another person (list of people) REST path: "user/{userId}+/spath/{targetId}" parameters: "targetId" - who to return the shortest path to Skill management service (name: "skills"): This new service offers basic skill management functionalities: getSkills - returns skills linked to a person and the people who linked them to that person REST path (GET): "skills/{userId}" addSkill - links a skill to the specified person in the name of the current viewer REST path (POST): "skills/{userId}/{skill}" parameters: "skill" - name of the skill to link to the person removeSkill - removes a link to a skill from the specified person in the name of the current viewer REST path (DELETE): "skills/{userId}/{skill}" parameters: "skill" - name of the skill to link to the person Autocompletion service (name: "autocomplete"): This new service offers autocompletion for text fragments: getSkillAutocomp - returns an autocompletion attempt for a given text fragment or all skills REST path: "autocomplete/skills?fragment=..." parameters: "fragment" - optional text fragment to autocomplete Organization service (name: "organization"): This new service offers information about organizations and their hierarchy: getHierarchyPath - returns the hierarchical path between two people REST path: "organization/{userId}/hierarchypath/{targetId}" parameters: "targetId" - who to return the hierarchical path to Event system: An system is included which fires events over a central event bus. You can register an "IEventListener" by having the "ShindigEventBus" injected into your implementation via Google Guice. An IShindigEvent contains the handled object, an ActivityEntry for example, as its payload and may contain additional metadata. A list of all event types is availabe in "ShindigEventType". Currently supported events: person/profile created/updated/deleted activity entry created/updated/deleted message created/updated/deleted Known Issues ------------ Newer versions of Apache Tomcat have their own WebSockets library which conflicts with a library included as Tyrus' dependecy. This causes the server to throw an Exception saying "... not a subclass of ...". For these Tomcat versions (tested with Tomcat 7.0.50) this can be fixed by removing the file '${CONTEXT}/WEB-INF/lib/javax.websocket-api-1.0.jar'. However, this file is needed for earlier Tomcat versions (probably below 7.0.42). Furthermore, when all Tyrus libraries are deleted, the connector will automatically use Tomcat's WebSocket libraries. But during our tests connections to the WebSocket server have been unstable. The connection is possibly terminated if unused for a certain amount of time which is not being properly detected yet. Missing features ---------------- A rudimentary Cypher-based implementation of the services is also included which would eliminate the need for server-side Java procedures. It is, however, far from complete and not fully tested and thus deactivated. The source files are located in the package "org.apache.shindig.social.websockbackend.spi.cypher".