View source for Personalisation

== 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:
* <tt>getUserProfile() -> String</tt><br>This operation returns the user's profile in a String representation.
* <tt>getElementValue(String elementName) -> String</tt><br>This operation returns the value of the element with name 'elementName' of the user's profile.
* <tt>getElement(String elementName) -> String[]</tt><br>This operation returns an array which contains all the elements with name ‘elementName’.
* <tt>setElement(String elementName, String value, String path) -> Void</tt><br>This operation creates a new element in the user profile.
* <tt>SetElementValue(String elementName, String value) -> Void</tt><br>This operation sets a new value to the element with name 'elementName'.
* <tt>DeleteElement(String elementName) -> Void</tt><br>This operation deletes the element with name 'elementName' from the user profile.
* <tt>UpdateUserProfile(String profileContent) -> Void</tt><br>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 [https://technical.wiki.d4science.research-infrastructures.eu/documentation/index.php/Administration#DefaultUserProfile DefaultUserProfile].

The service exposes the following operations:
* <tt>createUserprofile(String username) -> Void</tt><br>This operation creates a new user profile with 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.

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 ===
* UserProfileAccess Service:
** Java Runtime Environment
** gCore
** gCube Information Service
** gCube Storage Manager
<br>
* ProfileAdministration Service:
** Java Runtime Environment
** gCore
** gCube UserProfileAccess Service
** gCube Information Service
** gCube Storage Manager

== 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>