Difference between revisions of "Social Networking Library"

From Gcube Wiki
Jump to: navigation, search
(ASL Social Extension)
(ASL Social Extension on Maven)
 
(72 intermediate revisions by 2 users not shown)
Line 1: Line 1:
{|
+
<!-- CATEGORIES -->
|| __TOC__
+
[[Category:Developer's Guide]]
 +
<!-- END CATEGORIES -->
 +
{| align="right"
 +
| __TOC__
 
|}
 
|}
 +
 +
[[Image:SNLWhat.png | Figure 1. Social Networking Library in a very nutshell]]
 +
 
== Overview ==
 
== Overview ==
  
Line 10: Line 16:
 
* Retrieving Users Feeds, Comments, Likes;
 
* Retrieving Users Feeds, Comments, Likes;
 
* Managing Users Connections;
 
* Managing Users Connections;
* Managing Users Notifications;
+
* Publishing Users Notifications;
* Publishing Application Posts.
+
* Publishing Application News to User feeds.
 +
 
 +
=== Social Networking Library Web Service Interface (REST) ===
 +
 
 +
Please note that also a restful interface exists for this library: see [http://wiki.gcube-system.org/gcube/Social_Networking_Library_Web_Service_Interface Social Networking Library Web Service Interface]
  
 
=== Architecture Scenario ===
 
=== Architecture Scenario ===
  
The gCube Social Networking Library is the 'bridge' between your gCube Applications and the social networking facilities as depicted in the figure 1 below.  The social networking facilities exploit a NoSQL data store for their storage. Specifically an Apache Cassandra data store.  
+
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 2 presents the place of the Social Library in a simplified gCube Portal architecture.
  
[[File:Social library.png]]
+
[[Image:SNL.png |frame| center | Figure 2. Social Networking Library in the simplified gCube Portal  Reference Architecture]]
  
 
== How to use the gCube Social Networking Library (SNL) ==
 
== How to use the gCube Social Networking Library (SNL) ==
  
 
Your gCube Application will the SNL through a specific ASL Extension, the ASL Social Extension
 
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: [http://maven.research-infrastructures.eu/nexus/index.html#nexus-search;quick~social-networking-library nexus-search;quick~social-networking-library ]
 +
 +
* SNL:
 +
<source lang="xml">
 +
<dependency>
 +
  <groupId>org.gcube.portal</groupId>
 +
  <artifactId>social-networking-library</artifactId>
 +
  <version>2.0.0-SNAPSHOT</version>
 +
</dependency>
 +
</source>
  
 
=== ASL Social Extension ===
 
=== ASL Social Extension ===
 +
 +
[[File:Aslsocial.png]]
  
 
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:
 
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:
Line 30: Line 55:
 
* '''User Notifications Manager''': to be used by gCube Applications when they need to notify their users about some events.
 
* '''User Notifications Manager''': to be used by gCube Applications when they need to notify their users about some events.
  
The overall
+
=== ASL Social Extension on Maven ===
 +
 
 +
Always check the latest version on maven: [http://maven.research-infrastructures.eu/nexus/index.html#nexus-search;quick~aslsocial nexus-search;quick~aslsocial ]
 +
 
 +
<source lang="xml">
 +
<dependency>
 +
  <groupId>org.gcube.applicationsupportlayer</groupId>
 +
  <artifactId>aslsocial</artifactId>
 +
  <version>[1.0.0-SNAPSHOT,)</version>
 +
</dependency>
 +
</source>
  
 
==== Application News Manager ====
 
==== 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 having secondary type 'ApplicationProfile' and having your application name as resource name in the Root Scope of the infrastructure. You will also need to provide additional information in the body section of your Generic Resource.
 +
 +
An Application Profile needs to provide the following information:
 +
 +
* Name;
 +
* Description;
 +
* Unique Identifier;
 +
* Thumbnail image URL (See section [http://gcube.wiki.gcube-system.org/gcube/index.php?title=Social_Networking_Library#Create_Your_Application_Profile_Thumb_Image below] for instructions on how to upload your app image profile);
 +
* Endpoints.
 +
 +
In the following an example of an Application Profile is reported for the '''Fake''' AquaMaps Portlet:
 +
 +
<source lang="xml">
 +
<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.server.portlet.FakeAquaMapsPortlet</AppId>
 +
            <ThumbnailURL>http://ftp.d4science.org/apps/profiles/aquamaps.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>
 +
</source>
 +
 +
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.
 +
 +
<source lang="xml">
 +
<?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>
 +
</source>
 +
 +
======Create Your Application Profile Thumb Image======
 +
 +
To register/upload your Application Profile Thumbnail images, you '''must''' use the d4science.org FTP node. Choose between these 2 options:
 +
 +
* '''Upload your own''': You can read the credentials in the dedicated runtime resource (if you have the encryption key).
 +
** Scope: Root VO
 +
** Name: SocialPortalStorage
 +
** Category: FTPServer
 +
 +
* '''We do it for you''': create a ticket on the iMarine issue Tracker [https://issue.imarine.research-infrastructures.eu/newticket newticket] with the following settings:
 +
** Type: Task
 +
** Functional Area: Social Data Sharing, Social Portal
 +
** Add your image file in attachment to this ticket
 +
 +
=====Instantiate the News Manager from your Application=====
 +
 +
The signature of the ApplicationNewsManager Constructor is the following:
 +
 +
<source lang="java">
 +
import javax.servlet.http.HttpServletRequest;
 +
import org.gcube.applicationsupportlayer.social.shared.SocialNetworkingUser;
 +
...
 +
...
 +
ApplicationNewsManager(HttpServletRequest request, String scope, SocialNetworkingUser curser, $applicationId)
 +
</source>
 +
 +
In the following the ApplicationNewsManager is instantiated by the Fake AquaMaps servlet class:
 +
 +
<source lang="java">
 +
import javax.servlet.http.HttpServletRequest;
 +
import org.gcube.applicationsupportlayer.social.shared.SocialNetworkingUser;
 +
...
 +
...
 +
 +
public class FakeAquaMapsServiceImpl extends ... {
 +
 +
........
 +
NewsManager anm = new ApplicationNewsManager(HttpServletRequest request, String scope, SocialNetworkingUser curser,
 +
                            "org.gcube.sample.server.portlet.FakeAquaMapsPortlet"));
 +
.......
 +
</source>
 +
 +
=====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:
 +
 +
<source lang="java">
 +
      /**
 +
* 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);
 +
</source>
 +
 +
''' EXAMPLES '''
 +
* anm.shareApplicationUpdate("A new Fake Species Distribution Map was generated by Ermit the Frog");
 +
** will generate the following feed:
 +
 +
[[File:Fake-Aquamaps.png]]
 +
 +
 +
* 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:
 +
 +
[[File:Fake-aquamap2.png]]
 +
 +
Enjoy.
  
 
==== User Notifications Manager ====
 
==== User Notifications Manager ====
 +
 +
There are 2 ways of using the Notifications Manager, regular & advanced. The meaning is in the following:
 +
 +
*''' Regular''': You just want to notify the user about something.
 +
usage:
 +
<source lang="java">
 +
import javax.servlet.http.HttpServletRequest;
 +
import org.gcube.applicationsupportlayer.social.shared.SocialNetworkingUser;
 +
import org.gcube.applicationsupportlayer.social.shared.SocialNetworkingSite;
 +
...
 +
...
 +
SocialNetworkingSite site = new SocialNetworkingSite(getThreadLocalRequest());
 +
NotificationsManager nm = new ApplicationNotificationsManager(SocialNetworkingSite site, String scope, SocialNetworkingUser curser);
 +
</source>
 +
* '''Advanced''': You want to notify the user about something,  but you do want notifications to point back to your application, giving users the possibility to click and open up the subject of this notification in your application.
 +
** Example: A new folder was shared in my workspace, if the user clicks on the notification then the workspace portlet is open displaying the yet shared folder.
 +
** Make sure you create your application profile on the infrastructure if you want to do so.
 +
usage:
 +
 +
<source lang="java">
 +
import javax.servlet.http.HttpServletRequest;
 +
import org.gcube.applicationsupportlayer.social.shared.SocialNetworkingUser;
 +
import org.gcube.applicationsupportlayer.social.shared.SocialNetworkingSite;
 +
...
 +
...
 +
**
 +
* The server side implementation of the RPC service.
 +
*/
 +
@SuppressWarnings("serial")
 +
public class FakeAquaMapsServiceImpl extends ... {
 +
 +
SocialNetworkingSite site = new SocialNetworkingSite(getThreadLocalRequest());
 +
........
 +
NotificationsManager nm = new ApplicationNotificationsManager(SocialNetworkingSite site, String scope, SocialNetworkingUser curser, $applicationId);
 +
.......
 +
</source>
 +
 +
For further information about the supported methods please locate the '''aslsocial''' javadoc in the [https://www.gcube-system.org/software-releases gCube Software Release page]
 +
 +
=== See Also ===
 +
[https://wiki.gcube-system.org/gcube/Social_Networking_Library_Web_Service_Interface Social Networking Library Web Service Interface]

Latest revision as of 14:06, 18 May 2017

Figure 1. Social Networking Library in a very nutshell

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.

Social Networking Library Web Service Interface (REST)

Please note that also a restful interface exists for this library: see Social Networking Library Web Service Interface

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 2 presents the place of the Social Library in a simplified gCube Portal architecture.

Figure 2. Social Networking Library in the simplified gCube Portal Reference 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-networking-library

  • SNL:
<dependency>
  <groupId>org.gcube.portal</groupId>
  <artifactId>social-networking-library</artifactId>
  <version>2.0.0-SNAPSHOT</version>
</dependency>

ASL Social Extension

Aslsocial.png

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>[1.0.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 having secondary type 'ApplicationProfile' and having your application name as resource name in the Root Scope of the infrastructure. You will also need to provide additional information in the body section of your Generic Resource.

An Application Profile needs to provide the following information:

  • Name;
  • Description;
  • Unique Identifier;
  • Thumbnail image URL (See section below for instructions on how to upload your app image profile);
  • 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.server.portlet.FakeAquaMapsPortlet</AppId>
            <ThumbnailURL>http://ftp.d4science.org/apps/profiles/aquamaps.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>
Create Your Application Profile Thumb Image

To register/upload your Application Profile Thumbnail images, you must use the d4science.org FTP node. Choose between these 2 options:

  • Upload your own: You can read the credentials in the dedicated runtime resource (if you have the encryption key).
    • Scope: Root VO
    • Name: SocialPortalStorage
    • Category: FTPServer
  • We do it for you: create a ticket on the iMarine issue Tracker newticket with the following settings:
    • Type: Task
    • Functional Area: Social Data Sharing, Social Portal
    • Add your image file in attachment to this ticket
Instantiate the News Manager from your Application

The signature of the ApplicationNewsManager Constructor is the following:

import javax.servlet.http.HttpServletRequest;
import org.gcube.applicationsupportlayer.social.shared.SocialNetworkingUser;
...
...
ApplicationNewsManager(HttpServletRequest request, String scope, SocialNetworkingUser curser, $applicationId)

In the following the ApplicationNewsManager is instantiated by the Fake AquaMaps servlet class:

import javax.servlet.http.HttpServletRequest;
import org.gcube.applicationsupportlayer.social.shared.SocialNetworkingUser;
...
...
 
public class FakeAquaMapsServiceImpl extends ... {
 
........
NewsManager anm = new ApplicationNewsManager(HttpServletRequest request, String scope, SocialNetworkingUser curser, 
                            "org.gcube.sample.server.portlet.FakeAquaMapsPortlet"));
.......
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:

Fake-Aquamaps.png


  • 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:

Fake-aquamap2.png

Enjoy.

User Notifications Manager

There are 2 ways of using the Notifications Manager, regular & advanced. The meaning is in the following:

  • Regular: You just want to notify the user about something.

usage:

import javax.servlet.http.HttpServletRequest;
import org.gcube.applicationsupportlayer.social.shared.SocialNetworkingUser;
import org.gcube.applicationsupportlayer.social.shared.SocialNetworkingSite;
...
...
SocialNetworkingSite site = new SocialNetworkingSite(getThreadLocalRequest());
NotificationsManager nm = new ApplicationNotificationsManager(SocialNetworkingSite site, String scope, SocialNetworkingUser curser);
  • Advanced: You want to notify the user about something, but you do want notifications to point back to your application, giving users the possibility to click and open up the subject of this notification in your application.
    • Example: A new folder was shared in my workspace, if the user clicks on the notification then the workspace portlet is open displaying the yet shared folder.
    • Make sure you create your application profile on the infrastructure if you want to do so.

usage:

import javax.servlet.http.HttpServletRequest;
import org.gcube.applicationsupportlayer.social.shared.SocialNetworkingUser;
import org.gcube.applicationsupportlayer.social.shared.SocialNetworkingSite;
...
...
**
 * The server side implementation of the RPC service.
 */
@SuppressWarnings("serial")
public class FakeAquaMapsServiceImpl extends ... {
 
SocialNetworkingSite site = new SocialNetworkingSite(getThreadLocalRequest());
........
NotificationsManager nm = new ApplicationNotificationsManager(SocialNetworkingSite site, String scope, SocialNetworkingUser curser, $applicationId);
.......

For further information about the supported methods please locate the aslsocial javadoc in the gCube Software Release page

See Also

Social Networking Library Web Service Interface