Difference between revisions of "Personalisation"

From Gcube Wiki
Jump to: navigation, search
(Dependencies)
(ProfileAdministration Client Libary)
 
(17 intermediate revisions by the same user not shown)
Line 10: Line 10:
  
 
Each WS-Resource has two properties:
 
Each WS-Resource has two properties:
* The username, which is the logical name of the XML file, that contains the real data of the user's profile and it is stored in the Content Management Layer.
+
* The username, which is the logical name of the XML file, that contains the real data of the user's profile and it is stored in the Storage System. The current scope is also used as part of the name to ensure the retrieval of the correct profile, as the service is running in VO  mode while the invocations are usually done from VRE level.
* The ID of the user profile, which is the identifier returned by the Content Management Service when the profile is stored in the Content Management Layer.
+
* The ID of the user profile, which is the identifier returned by the Storage Management Service when the profile is stored.
  
In order to create or retrieve the profile of a user a service/portlet must invoke the createResource(String username) giving as a parameter the username of the user.
+
In order to create or retrieve the profile of a user, a service/portlet must invoke the createResource(String username) giving as a parameter the username of the user.
 
When this method is invoked there are different options:
 
When this method is invoked there are different options:
 
* If there is no WS-Resource for this user, a new resource is created.
 
* If there is no WS-Resource for this user, a new resource is created.
** If a profile exists in the Content Management Layer but for a reason there is no WS-resource, the new WS-resource has as property the username ant the ID Of the profile that already exists.
+
** If a profile already exists in the Storage System but for a reason there is no WS-resource, the new WS-resource has as property the username and the ID Of the profile that already exists.
** If there is no profile in the Content Management Layer, it creates e new profile and the WS-resource has the ID of the new profile.
+
** If there is no profile available, it creates e new profile and the WS-resource has the ID of the new profile.
  
 
The profiles are created per VRE level for each user.
 
The profiles are created per VRE level for each user.
Line 36: Line 36:
  
 
The 'elementName' should be an XPath expression.
 
The 'elementName' should be an XPath expression.
 
For more information about the default elements of the user profile click [https://technical.wiki.d4science.research-infrastructures.eu/documentation/index.php/Administration#DefaultUserProfile here].
 
  
 
=== ProfileAdministration Service ===
 
=== ProfileAdministration Service ===
Line 47: Line 45:
 
* <tt>dropUserProfile(String username) -> Void</tt><br>This operation deletes the profile for the given username.
 
* <tt>dropUserProfile(String username) -> Void</tt><br>This operation deletes the profile for the given username.
 
* <tt>setDefaultProfile(String profile) -> Void</tt><br>This operation sets or updates (if already exists) the DefaultUserProfile, which is stored on the IS.
 
* <tt>setDefaultProfile(String profile) -> Void</tt><br>This operation sets or updates (if already exists) the DefaultUserProfile, which is stored on the IS.
 +
 +
The ''DefaultUserProfile'' that is currently being used is saved as a generic resource on IS and is the following:
 +
<code>
 +
        <userprofile>
 +
            <userinfo>
 +
              <username />
 +
              <fullname />
 +
              <email />
 +
            </userinfo>
 +
            <preferences>
 +
              <defLanguage>ENGLISH</defLanguage>
 +
            </preferences>           
 +
        </userprofile>
 +
 +
</code>
  
 
=== Dependencies ===
 
=== Dependencies ===
 
* UserProfileAccess Service:
 
* UserProfileAccess Service:
** Java Runtime Environment 1.6.24
+
** Java Runtime Environment
 
** gCore
 
** gCore
 
** gCube Information Service
 
** gCube Information Service
** gCube Document Library
+
** gCube Storage Manager
** gCube Model Library
+
** gCube SMS plugin
+
 
<br>
 
<br>
 
* ProfileAdministration Service:
 
* ProfileAdministration Service:
** Java Runtime Environment 1.6.24
+
** Java Runtime Environment
 
** gCore
 
** gCore
 
** gCube UserProfileAccess Service
 
** gCube UserProfileAccess Service
 
** gCube Information Service
 
** gCube Information Service
** gCube Document Library
+
** gCube Storage Manager
** gCube Model Library
+
 
 +
== Personalization Client Libraries ==
 +
[https://gcube.wiki.gcube-system.org/gcube/index.php/Integration_and_Interoperability_Facilities_Framework:_Client_Libraries_Framework Client Libraries] are available for the personalization services in order to eliminate the needed dependencies and hide the complexity of the WSRF services.
 +
 
 +
=== UserProfileAccess Client Libary ===
 +
The UserProfileAccess client library offers the same functionality with its related service, as this described above.
 +
In order to use the client library you should:
 +
 
 +
* Get the WS-resource for a specific user and scope. Notice here that "scope" is the a String holding the leaf scope (i.e. the name of the VRE: iSearch)
 +
<code>
 +
 
 +
StatefulQuery q = UserProfileAccessDSL.getSource().withUsernameAndScope("user", "scope").build();                 
 +
List<EndpointReference> refs = q.fire();
 +
if (!refs.isEmpty())                                                   
 +
  System.out.println("EPR -> " + refs.get(0));
 +
 
 +
</code>
 +
 
 +
* Invoke the available functions
 +
<code>
 +
 
 +
    UserProfileAccessCLProxyI proxyRandom = UserProfileAccessDSL.getUserProfileAccessProxyBuilder().at((W3CEndpointReference)refs.get(0)).build();
 +
    /* getProfile */
 +
    String profile = proxyRandom.getUserProfile();
 +
    String username = proxyRandom.getElementValue("userprofile/userinfo/username");
 +
 
 +
</code>
 +
 
 +
* Create a new user profile
 +
<code>
 +
 
 +
UserProfileAccessFactoryCLProxyI factoryProxy = UserProfileAccessFactoryDSL.getUserProfileAccessFactoryProxyBuilder().build();
 +
CreateResourceResponse response = factoryProxy.createResource("username");
 +
 +
</code>
 +
 
 +
==== Maven Coordinates ====
 +
 
 +
<source lang="xml">
 +
<dependency>
 +
  <groupId>org.gcube.personalisation</groupId>
 +
  <artifactId>userprofileaccess-client-library</artifactId>
 +
  <version>1.0.0-SNAPSHOT</version>
 +
</dependency>
 +
</source>
 +
 
 +
=== ProfileAdministration Client Libary ===
 +
The ProfileAdministration client library offers the same funnctionality with its related service, as this described above.
 +
In order to use the client library you should:
 +
 
 +
* Create a new user profile:
 +
<code>
 +
ProfileAdministrationCLProxyI prProxy = ProfileAdministrationDSL.getSearchProxyBuilder().build();
 +
prProxy.createUserProfile("username");
 +
</code>
 +
 
 +
* Delete an existing profile:
 +
<code>
 +
ProfileAdministrationCLProxyI prProxy = ProfileAdministrationDSL.getSearchProxyBuilder().build();
 +
prProxy.dropUserProfile("username");
 +
</code>
 +
 
 +
 
 +
* Create the DefaultUserProfile generic resource:
 +
<code>
 +
/* The XML default user profile is needed to be passed as a parameter */
 +
ProfileAdministrationCLProxyI prProxy = ProfileAdministrationDSL.getSearchProxyBuilder().build();
 +
prProxy.setDefaultProfile("profile");
 +
</code>
 +
 
 +
* The scope should have been set in the first step of the invocation chain. For more information please see here: [https://gcube.wiki.gcube-system.org/gcube/index.php/Scope_Handling:_from_gCore_to_common-scope Scope Handling]
 +
 
 +
==== Maven Coordinates ====
 +
 
 +
<source lang="xml">
 +
<dependency>
 +
  <groupId>org.gcube.personalisation</groupId>
 +
  <artifactId>profileadministration-client-library</artifactId>
 +
  <version>1.0.0-SNAPSHOT</version>
 +
</dependency>
 +
</source>

Latest revision as of 09:13, 28 November 2013

Personalisation

Introduction

The main functionality of the Personalization is to handle the user's profiles. The objective of the personalization service in the gCube platform is the personalization of information retrieval. The Personalization service consists of two components, the UserProfileAccess service and the ProfileAdministration service. Each one of them will be described below.

UserProfileAccess Service

The UserProfileAccess service is a statefull service and it is responsible for creating and managing the user's profiles. It creates WS-Resources, one for each user profile, and publishes them on the DIS.

Each WS-Resource has two properties:

  • The username, which is the logical name of the XML file, that contains the real data of the user's profile and it is stored in the Storage System. The current scope is also used as part of the name to ensure the retrieval of the correct profile, as the service is running in VO mode while the invocations are usually done from VRE level.
  • The ID of the user profile, which is the identifier returned by the Storage Management Service when the profile is stored.

In order to create or retrieve the profile of a user, a service/portlet must invoke the createResource(String username) giving as a parameter the username of the user. When this method is invoked there are different options:

  • If there is no WS-Resource for this user, a new resource is created.
    • If a profile already exists in the Storage System but for a reason there is no WS-resource, the new WS-resource has as property the username and the ID Of the profile that already exists.
    • If there is no profile available, it creates e new profile and the WS-resource has the ID of the new profile.

The profiles are created per VRE level for each user.

  • If WS-Resources exist for this user.
    • If any of the existing WS-Resources had been created from the same Running instance that invoked this method, then it returns this resource.
    • Otherwise it creates a new WS-Resource with the same properties as the ones that already exist.


The service exposes the following operations:

  • getUserProfile() -> String
    This operation returns the user's profile in a String representation.
  • getElementValue(String elementName) -> String
    This operation returns the value of the element with name 'elementName' of the user's profile.
  • getElement(String elementName) -> String[]
    This operation returns an array which contains all the elements with name ‘elementName’.
  • setElement(String elementName, String value, String path) -> Void
    This operation creates a new element in the user profile.
  • SetElementValue(String elementName, String value) -> Void
    This operation sets a new value to the element with name 'elementName'.
  • DeleteElement(String elementName) -> Void
    This operation deletes the element with name 'elementName' from the user profile.
  • UpdateUserProfile(String profileContent) -> Void
    This operation replaces the profile with the given content. For now non validation is performed.

The 'elementName' should be an XPath expression.

ProfileAdministration Service

The ProfileAdministration service is a stateless service which provides the administrator with the functionality for creating or deleting a user profile. It also provides the functionality to upload or edit the DefaultUserProfile.

The service exposes the following operations:

  • createUserprofile(String username) -> Void
    This operation creates a new user profile with the given username.
  • dropUserProfile(String username) -> Void
    This operation deletes the profile for the given username.
  • setDefaultProfile(String profile) -> Void
    This operation sets or updates (if already exists) the DefaultUserProfile, which is stored on the IS.

The DefaultUserProfile that is currently being used is saved as a generic resource on IS and is the following:

       <userprofile>
           <userinfo>
              <username />
              <fullname />
              <email />
           </userinfo>
           <preferences>
              <defLanguage>ENGLISH</defLanguage>
           </preferences>            
        </userprofile>

Dependencies

  • UserProfileAccess Service:
    • Java Runtime Environment
    • gCore
    • gCube Information Service
    • gCube Storage Manager


  • ProfileAdministration Service:
    • Java Runtime Environment
    • gCore
    • gCube UserProfileAccess Service
    • gCube Information Service
    • gCube Storage Manager

Personalization Client Libraries

Client Libraries are available for the personalization services in order to eliminate the needed dependencies and hide the complexity of the WSRF services.

UserProfileAccess Client Libary

The UserProfileAccess client library offers the same functionality with its related service, as this described above. In order to use the client library you should:

  • Get the WS-resource for a specific user and scope. Notice here that "scope" is the a String holding the leaf scope (i.e. the name of the VRE: iSearch)

StatefulQuery q = UserProfileAccessDSL.getSource().withUsernameAndScope("user", "scope").build();                   
List<EndpointReference> refs = q.fire();
if (!refs.isEmpty())                                                    
  System.out.println("EPR -> " + refs.get(0));

  • Invoke the available functions

    UserProfileAccessCLProxyI proxyRandom = UserProfileAccessDSL.getUserProfileAccessProxyBuilder().at((W3CEndpointReference)refs.get(0)).build();
    /* getProfile */
    String profile = proxyRandom.getUserProfile();
    String username = proxyRandom.getElementValue("userprofile/userinfo/username");

  • Create a new user profile

UserProfileAccessFactoryCLProxyI factoryProxy = UserProfileAccessFactoryDSL.getUserProfileAccessFactoryProxyBuilder().build();
CreateResourceResponse response = factoryProxy.createResource("username");

Maven Coordinates

<dependency>
  <groupId>org.gcube.personalisation</groupId>
  <artifactId>userprofileaccess-client-library</artifactId>
  <version>1.0.0-SNAPSHOT</version>
</dependency>

ProfileAdministration Client Libary

The ProfileAdministration client library offers the same funnctionality with its related service, as this described above. In order to use the client library you should:

  • Create a new user profile:

ProfileAdministrationCLProxyI prProxy = ProfileAdministrationDSL.getSearchProxyBuilder().build();
prProxy.createUserProfile("username");

  • Delete an existing profile:

ProfileAdministrationCLProxyI prProxy = ProfileAdministrationDSL.getSearchProxyBuilder().build();
prProxy.dropUserProfile("username");


  • Create the DefaultUserProfile generic resource:

/* The XML default user profile is needed to be passed as a parameter */
ProfileAdministrationCLProxyI prProxy = ProfileAdministrationDSL.getSearchProxyBuilder().build();
prProxy.setDefaultProfile("profile");

  • The scope should have been set in the first step of the invocation chain. For more information please see here: Scope Handling

Maven Coordinates

<dependency>
  <groupId>org.gcube.personalisation</groupId>
  <artifactId>profileadministration-client-library</artifactId>
  <version>1.0.0-SNAPSHOT</version>
</dependency>