Social Networking Library
Overview
The purpose of this document is to provide instructions for developers wishing to exploit Social Networking from within their applications.
The gCube Social Library, so far, provides methods for:
- Publishing Users Posts;
- Retrieving Users Feeds, Comments, Likes;
- Managing Users Connections;
- Publishing Users Notifications;
- Publishing Application News to User feeds.
Architecture Scenario
The gCube Social Networking Library is the 'bridge' between your gCube Applications and the social networking facilities. The social networking facilities exploit a NoSQL data store for their storage. Specifically an Apache Cassandra data store. Figure 1 present the place of the Social Library in a simplified gCube Portal architecture.
How to use the gCube Social Networking Library (SNL)
Your gCube Application will the SNL through a specific ASL Extension, the ASL Social Extension
Social Networking Library on Maven
Always check the latest version on maven: nexus-search;quick~social-library
- SNL without dependencies:
<dependency> <groupId>org.gcube.portal</groupId> <artifactId>social-library</artifactId> <version>0.1.0-SNAPSHOT</version> </dependency>
- SNL with dependencies (to be used at Runtime within Eclipse):
<dependency> <groupId>org.gcube.portal</groupId> <artifactId>social-library</artifactId> <version>0.1.0-SNAPSHOT</version> <classifier>jar-with-dependencies</classifier> </dependency>
ASL Social Extension
The ASL Social Extension is formed by different modules, each of these is delegated to one specific task. Every module inherits from a super class called SocialPortalBridge. Currently there are two modules available:
- Application News Manager: to be used by gCube Applications when they need to post news on their user news feeds;
- User Notifications Manager: to be used by gCube Applications when they need to notify their users about some events.
ASL Social Extension on Maven
Always check the latest version on maven: nexus-search;quick~aslsocial
<dependency> <groupId>org.gcube.applicationsupportlayer</groupId> <artifactId>aslsocial</artifactId> <version>0.1.0-SNAPSHOT</version> </dependency>
Application News Manager
Create Your Application Profile
In order to publish a news from within your application you first need to create an Application Profile for your gCube Application. You need to create Generic Resource in of secondary type 'ApplicationProfile' having your application name as resource name in the Root Scope. You will also need to provide additional information in the body of your Generic Resource.
An Application Profile needs to provide the following information:
- Name
- Description
- Unique Identifier
- Thumbnail image URL
- Endpoints
In the following an example of an Application Profile is reported for the Fake AquaMaps Portlet:
<Resource version="0.4.x"> <ID>dec27470-447e-11e2-a749-e3b17e68146a</ID> <Type>GenericResource</Type> <Scopes> <!-- The Generic Resource scope must be the Root VO --> <Scope>/gcube</Scope> </Scopes> <Profile> <!-- The Generic Resource SecondaryType must be ApplicationProfile --> <SecondaryType>ApplicationProfile</SecondaryType> <Name>FakeAquaMaps</Name> <Description>desc for FakeAquaMaps Application</Description> <Body> <!-- The App Id is your servlet class name --> <AppId>org.gcube.sample.FakeAquaMaps</AppId> <ThumbnailURL>http://dl.dropbox.com/u/15737233/aquamaps-preview.jpg</ThumbnailURL> <!-- The EndPoints of your application with the absolute path to reach it, one for every scope in which the application is deployed --> <EndPoint> <Scope>/gcube/devsec/devVRE</Scope> <URL>/group/devvre/fake-aquamaps</URL> </EndPoint> <EndPoint> <Scope>/gcube/devNext/NextNext</Scope> <URL>/group/nextnext/fake-or-not-aquamaps</URL> </EndPoint> </Body> </Profile> </Resource>
The <body> part of your Generic Resource must be compliant with the following xml schema, available in this File:SampleApplicationProfile.xsd in case you need.
<?xml version="1.0" encoding="UTF-8"?> <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified"> <xs:element name="body"> <xs:complexType> <xs:sequence> <xs:element ref="AppId"/> <xs:element ref="ThumbnailURL"/> <xs:element maxOccurs="unbounded" ref="EndPoint"/> </xs:sequence> </xs:complexType> </xs:element> <xs:element name="AppId" type="xs:string"/> <xs:element name="ThumbnailURL" type="xs:anyURI"/> <xs:element name="EndPoint"> <xs:complexType> <xs:sequence> <xs:element ref="scope"/> <xs:element ref="URL"/> </xs:sequence> </xs:complexType> </xs:element> <xs:element name="scope" type="xs:string"/> <xs:element name="URL" type="xs:string"/> </xs:schema>
Instantiate the News Manager from your Application
The signature of the ApplicationNewsManager Constructor is the following:
ApplicationNewsManager(ASLSession session, Class<? extends HttpServlet> applicationClass)
In the following the ApplicationNewsManager is instantiated by the Fake AquaMaps servlet class:
** * The server side implementation of the RPC service. */ @SuppressWarnings("serial") public class FakeAquaMaps extends RemoteServiceServlet implements ... { ........ NewsManager anm = new ApplicationNewsManager(getASLSession(), this.getClass()); .......
Publish News from your Application
Once you have the ApplicationNewsManager instantiated you have to simply call the ApplicationNewsManager#shareApplicationUpdate method for publishing feeds that comes with 3 different flavors:
/** * use to share an update from your application * * @param feedtext add a description for the update you are sharing * @return true if the update is correctly delivered, false otherwise */ boolean shareApplicationUpdate(String feedtext); /** * use to share an update from your application with a reference to the news object * * @param feedtext description for the update you are sharing * @param uriGETparams additional parameters if your application supports the direct opening of of this update's object e.g. id=12345&type=foo * @return true if the update is correctly delivered, false otherwise */ boolean shareApplicationUpdate(String feedtext, String uriGETparams); /** * use to share an update from your application with a reference to the news object and with a link preview * * @param feedtext add a description for the update you are sharing * @param uriGETparams additional parameters if your application supports the direct opening of of this update's object e.g. id=12345&type=foo * @param previewTitle the title to show in the preview * @param previewDescription the description to show in the preview * @param previewThumbnailUrl the image url to show in the preview * @return true if the update is correctly delivered, false otherwise */ boolean shareApplicationUpdate(String feedtext, String uriGETparams, String previewTitle, String previewDescription, String previewThumbnailUrl);
EXAMPLES
- anm.shareApplicationUpdate("A new Fake Species Distribution Map was generated by Ermit the Frog");
- will generate the following feed:
- anm.shareApplicationUpdate("A new Fake Species Distribution Map was generated by Ermit the Frog", "objectid=12345");
- will generate the same feed above graphically but if your map has id 12345 and your application supports direct opening the parameter will be passed via http GET
- anm.shareApplicationUpdate(
"A new Fake Species Distribution Map was generated by Ermit the Frog", "id=123", "Thunnus alalunga - Continental Asia View", "The Thunnus alalunga Species Distribution Map for the Asia area is available, " + "fake AquaMaps exploits several computational backends: a single multi-core server, " + "distributed services offered by the D4science infrastructure and cloud resources.", "http://dl.dropbox.com/u/15737233/ContinentViewAsia.jpg");
- will generate the following feed:
Enjoy.
User Notifications Manager
There is no implementation so far however the interface is available:
usage: NotificationsManager nm = new UserNotificationsManager(getAslSession());
public interface NotificationsManager { /** * use to notify a user he got a workspace folder shared * * @param userIdToNotify the user you want to notify * @param sharedFolder the shared {@link WorkspaceFolder} * @return true if the notification is correctly delivered, false otherwise */ boolean notifyFolderSharing(String userIdToNotify, WorkspaceFolder sharedFolder); /** * use to notify a user that a new user was added in on of his workspace shared folder * * @param userIdToNotify the user you want to notify * @param sharedFolder the shared {@link WorkspaceFolder} * @param newAddedUserId the new user that was added * @return true if the notification is correctly delivered, false otherwise */ boolean notifyFolderAddedUser(String userIdToNotify, WorkspaceFolder sharedFolder, String newAddedUserId); /** * use to notify a user that an existing user was removed from one of his workspace shared folder * * @param userIdToNotify the user you want to notify * @param sharedFolder the shared {@link WorkspaceFolder} * @param removedUserId the new user that was removed * @return true if the notification is correctly delivered, false otherwise */ boolean notifyFolderRemovedUser(String userIdToNotify, WorkspaceFolder sharedFolder, String removedUserId); /** * use to notify a user he got a workspace item new in some of his workspace shared folder * @param userIdToNotify the user you want to notify * @param newItem the new shared {@link WorkspaceItem} * @return true if the notification is correctly delivered, false otherwise */ boolean notifyAddedItem(String userIdToNotify, WorkspaceItem newItem); /** * use to notify a user he got a workspace item deleted from one of his workspace shared folder * @param userIdToNotify the user you want to notify * @param removedItem the removed {@link WorkspaceItem} * @return true if the notification is correctly delivered, false otherwise */ boolean notifyRemovedItem(String userIdToNotify, WorkspaceItem removedItem); /** * use to notify a user he got a workspace item updated from one of his workspace shared folder * @param userIdToNotify the user you want to notify * @param updatedItem the updated shared {@link WorkspaceItem} * @return true if the notification is correctly delivered, false otherwise */ boolean notifyUpdatedItem(String userIdToNotify, WorkspaceItem updatedItem); /** * * @param userIdToNotify the user you want to notify * @param message the {@link WorkspaceMessage} sent * @return true if the notification is correctly delivered, false otherwise */ boolean notifyMessageReceived(String userIdToNotify, WorkspaceMessage message); /** * * @param userIdToNotify the user you want to notify * @param comment the {@link Comment} instance to which someone replied to * @return true if the notification is correctly delivered, false otherwise */ boolean notifyOwnCommentReply(String userIdToNotify, Comment comment); /** * use to notify a user that commented on a feed (Not his) that someone commented too * * @param userIdToNotify the user you want to notify * @param comment the {@link Comment} instance to which someone replied to * @return true if the notification is correctly delivered, false otherwise */ boolean notifyCommentReply(String userIdToNotify, Comment comment); /** * use to notify a user he got one of his feed liked * * @param userIdToNotify the user you want to notify * @param likedFeed the {@link Feed} instance someone liked * @return true if the notification is correctly delivered, false otherwise */ boolean notifyLikedFeed(String userIdToNotify, Feed likedFeed);
