com.oracle.sites.visitors.client

Class VisitorsClient

java.lang.Object

com.oracle.sites.visitors.client.VisitorsClient

All Implemented Interfaces:

AutoCloseable

public class VisitorsClient
extends Object
implements AutoCloseable

The class VisitorsClient provides functionality for Visitor Services back-end Java REST APIs. Java client is used when Visitor Services and consumer applications owned by Oracle interact.

Constructor Summary

Constructors

Constructor and Description
VisitorsClient(AuthType authentication, String url) Constructor for VisitorsClient.
VisitorsClient(AuthType authentication, String url, Map<String,Object> params) Allocate and initialize a VisitorsClient object.
VisitorsClient(String url) Allocate and initialize a VisitorsClient object.

Method Summary

Modifier and Type	Method and Description
boolean	addActivity(String visitorId, Map<String,String> activities) Add visitor's activity to Visitor Services storage
void	close()
String	getAggregatedProfile(String visitorId, String rule) Get an aggregated profile from Visitor Services using existing visitor's ID All the linked profiles for the visitor are background updated in different profile storages.
String	getAggregatedProfile(String visitorId, String rule, boolean updated) Get an aggregated profile from Visitor Services using existing visitor's ID All the linked profiles for the visitor are updated in different profile storages.
List<ActivityApi>	getLatest(String visitorId, String type, int limit) Get a list of visitor's activities sorted by date
LinkedProfilesApi	getLinkedProfiles(String visitorId) Returns linked profiles from Visitor Services using existing visitor's ID.
LinkedProfilesApi	getLinkedProfiles(String visitorId, boolean updated) Returns linked profiles from Visitor Services using existing visitor's ID.
List<ActivityApi>	getRated(String visitorId, String type, int limit) Get a list of visitor's activities sorted by rating
String	getVisitorId(javax.servlet.http.HttpServletRequest request) Get visitor's ID from Visitor Services using external ID from Single Sign On solution.
Boolean	isExist(String visitorId) Verify if the visitor ID exists in database.
Boolean	isGuest(String visitorId) Verifies if the visitor is a guest profile or has no profile in DB.
boolean	linkProfiles(String[] ids) Add visitors into the linked group.
String	registerGuest(String guestId) Register visitor as guest in the database.
String	registerGuest(String guestId, Map<String,String> formParams) Deprecated.
String	saveExtendedAttributes(String visitorId, Map<String,String> formParams) Save extended attribute for visitor profile.
boolean	unlinkProfiles(String[] ids) Remove specified visitors from current linked group.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

VisitorsClient

public VisitorsClient(AuthType authentication,
                      String url,
                      Map<String,Object> params)

Allocate and initialize a VisitorsClient object.

Parameters:

authentication - AuthType object. AuthType is an authentication type for getting access to Visitor Services back-end REST.

url - String object. Is a base URL to Visitor Services REST. For example, http://example.com:8080/visitors-webapp

params - Map object. Map for Jersey Client initialization

VisitorsClient

public VisitorsClient(AuthType authentication,
                      String url)

Constructor for VisitorsClient.

Initializes a newly created VisitorsClient

Parameters:

authentication - a AuthType object.

url - a String object. Is a base URL to Visitor Services REST. For example, http://example.com:8080/visitors-webapp

VisitorsClient

public VisitorsClient(String url)

Allocate and initialize a VisitorsClient object. AuthType is NoAuthentication.

Parameters:

url - a String object. Base URL to SVS REST. For example, http://example.com:8080/visitors-webapp

Method Detail

getVisitorId

public String getVisitorId(javax.servlet.http.HttpServletRequest request)

Get visitor's ID from Visitor Services using external ID from Single Sign On solution. Visitor Services searches and links another visitor’s profile in different storage areas. This is known as an enrichment process for a visitor.

REST API information:

POST http://host:port/context/rest/v1/visitor/getId

Content type: application/x-www-form-urlencoded

Return: IdProfilesResponse visitorId - visitor ID from SVS.

Parameters:

request - HttpServletRequest object.

Returns:

Visitor Id String.

Throws:

UnauthorizedAccessException - when there is a mismatch between access credentials passed while creating visitor client object and the expected credentials that visitor services expects javax.ws.rs.WebApplicationException in case the response status code of the response returned by the server is not successful.

isExist

public Boolean isExist(String visitorId)

Verify if the visitor ID exists in database. If the visitor ID exists in the database the response is true. Visitor ID can be guest user or register user.

REST API information:

GET http://host:port/context/rest/v1/visitor/id/visitorId/check/exist

Accept

: application/json, application/xml

Return: BooleanResponse

Parameters:

visitorId - String object.

Returns:

true if the visitor ID exists in the database. in the database

false if the visitor ID does not exist.

Throws:

UnauthorizedAccessException - when there is a mismatch between access credentials passed while creating visitor client object and the expected credentials that visitor services expects javax.ws.rs.WebApplicationException in case the response status code of the response returned by the server is not successful.

isGuest

public Boolean isGuest(String visitorId)

Verifies if the visitor is a guest profile or has no profile in DB.

REST API information:

GET http://host:port/context/rest/v1/visitor/id/visitorId/check/guest

Accept

: application/json, application/xml

Return: BooleanResponse

Parameters:

visitorId - a String object.

Returns:

false if visitor has one non guest profile between linked profiles.

Possible 5 cases:

1. true if no profile in database.

2. true if one guest profile in database.

3. false if one non guest profile in database.

4. true if more then one linked profile exists and all profiles are guest profiles/

5. false if more than one linked profile exists and one profile is not a guest profile

Throws:

UnauthorizedAccessException - when there is a mismatch between access credentials passed while creating visitor client object and the expected credentials that visitor services expects javax.ws.rs.WebApplicationException in case the response status code of the response returned by the server is not successful.

getAggregatedProfile

public String getAggregatedProfile(String visitorId,
                                   String rule,
                                   boolean updated)

Get an aggregated profile from Visitor Services using existing visitor's ID All the linked profiles for the visitor are updated in different profile storages.

REST API information:

GET http://host:port/context/rest/v1/visitor/id/visitorId/profile/aggregated/rule

Accept

: application/json, application/xml

Path Params: visitorId, rule

Query Params: updated

Return: AggregatedProfileResponse aggregated profile for visitor with id as visitorId aggregated by rule aggregation template.

Parameters:

visitorId - String object.

rule - String object. Aggregation template name

updated - - If true, method executes profile update and enrichment in synchronous way and returns profile attributes from fresh data. If false, then depending on whether profile has expired it executes profile update and enirchment process as below - If profile has expired and a) JMS is configured in Visitor Services, method submits the update and enrichment task and returns profile data from old data, b) JMS is not configured in Visitor Services, method executes update and enrichment in synchronous way and method returns profile data from fresh data If profile has not expired, it has same effect as passing value 'false', i.e. returns profile data from data present in Visitor Services storage.

Returns:

aggregated profile String object in JSON format.

Throws:

UnauthorizedAccessException - when there is a mismatch between access credentials passed while creating visitor client object and the expected credentials that visitor services expects javax.ws.rs.WebApplicationException in case the response status code of the response returned by the server is not successful.

getAggregatedProfile

public String getAggregatedProfile(String visitorId,
                                   String rule)

Get an aggregated profile from Visitor Services using existing visitor's ID All the linked profiles for the visitor are background updated in different profile storages.

REST API information:

GET http://host:port/context/rest/v1/visitor/id/visitorId/profile/aggregated/rule

Accept

: application/json, application/xml

Path Params: visitorId, rule

Query Params: updated

Return: AggregatedProfileResponse aggregated profile for visitor with id as visitorId aggregated by rule aggregation template.

Parameters:

visitorId - String object.

rule - String object. Aggregation template name

Returns:

aggregated profile String object in JSON format. It has same effect as calling the overloaded method with param updated=false.

Throws:

UnauthorizedAccessException - when there is a mismatch between access credentials passed while creating visitor client object and the expected credentials that visitor services expects javax.ws.rs.WebApplicationException in case the response status code of the response returned by the server is not successful.

getLinkedProfiles

public LinkedProfilesApi getLinkedProfiles(String visitorId)

Returns linked profiles from Visitor Services using existing visitor's ID. All the linked profiles for the visitor are updated in different profile storages.

REST API information:

GET http://host:port/context/rest/v1/visitor/id/visitorId/profiles/linked

Accept

: application/json, application/xml

Path Params: visitorId

Query Params: updated

Return: LinkedProfilesResponse linked profiles for visitor with id as visitorId

Parameters:

visitorId - String object.

Returns:

LinkedProfilesApi object. It has same effect as calling the overloaded method with param updated=false.

Throws:

UnauthorizedAccessException - when there is a mismatch between access credentials passed while creating visitor client object and the expected credentials that visitor services expects javax.ws.rs.WebApplicationException in case the response status code of the response returned by the server is not successful.

getLinkedProfiles

public LinkedProfilesApi getLinkedProfiles(String visitorId,
                                           boolean updated)

Returns linked profiles from Visitor Services using existing visitor's ID. All the linked profiles for the visitor are updated in different profile storages.

REST API information:

GET http://host:port/context/rest/v1/visitor/id/visitorId/profiles/linked

Accept

: application/json, application/xml

Path Params: visitorId

Query Params: updated

Return: LinkedProfilesResponse linked profiles for visitor with id as visitorId

Parameters:

visitorId - String object.

updated - - If true, method executes profile update and enrichment in synchronous way and returns profile attributes from fresh data. If false, then depending on whether profile has expired it executes profile update and enirchment process as below - If profile has expired and a) JMS is configured in Visitor Services, method submits the update and enrichment task and returns profile data from old data, b) JMS is not configured in Visitor Services, method executes update and enrichment in synchronous way and method returns profile data from fresh data If profile has not expired, it has same effect as passing value 'false', i.e. returns profile data from data present in Visitor Services storage.

Returns:

LinkedProfilesApi object.

Throws:

UnauthorizedAccessException - when there is a mismatch between access credentials passed while creating visitor client object and the expected credentials that visitor services expects javax.ws.rs.WebApplicationException in case the response status code of the response returned by the server is not successful.

addActivity

public boolean addActivity(String visitorId,
                           Map<String,String> activities)

Add visitor's activity to Visitor Services storage

REST API information:

POST http://host:port/context/rest/v1/visitor/id/visitorId/activity/add

Path Params: visitorId

Form Params: activities map. Format: activityType=activity

Accept

: application/json, application/xml

Content type: application/x-www-form-urlencoded

Return: RestResponse

Parameters:

visitorId - String object.

activities - Map object. The format is activityType=activity

Returns:

true if operation succeeds.

Throws:

UnauthorizedAccessException - when there is a mismatch between access credentials passed while creating visitor client object and the expected credentials that visitor services expects javax.ws.rs.WebApplicationException in case the response status code of the response returned by the server is not successful.

getRated

public List<ActivityApi> getRated(String visitorId,
                                  String type,
                                  int limit)

Get a list of visitor's activities sorted by rating

REST API information:

GET http://host:port/context/rest/v1/visitor/id/visitorId/activity/type/attivityType/rated ?limit=activitiesLimit

Path Params: visitorId, attivityType

Query Params: limit

Accept

: application/json, application/xml

Return: ActivitiesResponse

Parameters:

visitorId - String object.

type - any String value that represent type of visitors activities. For example for visitor's searches it can be search_query.

limit - int.

Returns:

List of visitor's ActivityApi objects sorted by rating.

Throws:

UnauthorizedAccessException - when there is a mismatch between access credentials passed while creating visitor client object and the expected credentials that visitor services expects javax.ws.rs.WebApplicationException in case the response status code of the response returned by the server is not successful.

getLatest

public List<ActivityApi> getLatest(String visitorId,
                                   String type,
                                   int limit)

Get a list of visitor's activities sorted by date

REST API information:

GET http://host:port/context/rest/v1/visitor/id/visitorId/activity/type/attivityType/latest ?limit=activitiesLimit

Path Params: visitorId, attivityType

Query Params: limit

Accept

: application/json, application/xml

Return: ActivitiesResponse

Parameters:

visitorId - a String object.

type - any String value that represent type of visitors activities. For example for visitor's searches it can be search_query.

limit - int.

Returns:

List of visitor's ActivityApi objects sorted by date.

Throws:

UnauthorizedAccessException - when there is a mismatch between access credentials passed while creating visitor client object and the expected credentials that visitor services expects javax.ws.rs.WebApplicationException in case the response status code of the response returned by the server is not successful.

saveExtendedAttributes

public String saveExtendedAttributes(String visitorId,
                                     Map<String,String> formParams)

Save extended attribute for visitor profile.

REST API information:

POST http://host:port/context/rest/v1/visitor/id/visitorId/attributes/save

Path Params: visitorId

Form Params: array of custom visitor attributes

Accept

: application/json, application/xml

Content type: application/x-www-form-urlencoded

Return: RestResponse

Parameters:

visitorId - String object.

formParams - Map object with extended attributes. For example, "gender"="male", "locale"="us".

Returns:

String object. "success" or "failure" status

Throws:

UnauthorizedAccessException - when there is a mismatch between access credentials passed while creating visitor client object and the expected credentials that visitor services expects javax.ws.rs.WebApplicationException in case the response status code of the response returned by the server is not successful.

registerGuest

public String registerGuest(String guestId)

Register visitor as guest in the database.

REST API information:

POST http://host:port/context/rest/v1/visitor/register?id=guestId

Query Params: id

Accept

: application/json, application/xml

Return: IdProfilesResponse

Parameters:

guestId - String object. visitor ID from SVS

Returns:

guest idString value.

Throws:

UnauthorizedAccessException - when there is a mismatch between access credentials passed while creating visitor client object and the expected credentials that visitor services expects javax.ws.rs.WebApplicationException in case the response status code of the response returned by the server is not successful.

registerGuest

@Deprecated
public String registerGuest(String guestId,
                                        Map<String,String> formParams)

Deprecated.

Register visitor as guest in the database.

REST API information:

POST http://host:port/context/rest/v1/visitor/register?id=guestId

Query Params: id

Form Params: post form attributes - array of custom visitor attributes

Accept

: application/json, application/xml

Return: IdProfilesResponse

Parameters:

guestId - String object. visitor ID from SVS

formParams - Map object. Array of custom visitor attributes

Returns:

guest idString value.

Throws:

UnauthorizedAccessException - when there is a mismatch between access credentials passed while creating visitor client object and the expected credentials that visitor services expects javax.ws.rs.WebApplicationException in case the response status code of the response returned by the server is not successful.

linkProfiles

public boolean linkProfiles(String[] ids)

Add visitors into the linked group. If a visitor is a member of another group then all the members from the other group are added to the linked group.

REST API information:

POST http://host:port/context/rest/v1/visitor/link?ids=id1,id2,...idN

Query Params: id1,id2,...idN - comma separated list of visitorIDs that need tobe moved to the separate group.

Form Params: post form attributes - array of custom visitor attributes

Accept

: application/json, application/xml

Return: RestResponse

Parameters:

ids - array of String objects.

Returns:

true if operation success

Throws:

UnauthorizedAccessException - when there is a mismatch between access credentials passed while creating visitor client object and the expected credentials that visitor services expects javax.ws.rs.WebApplicationException in case the response status code of the response returned by the server is not successful.

unlinkProfiles

public boolean unlinkProfiles(String[] ids)

Remove specified visitors from current linked group. The visitors are also unlinked with other profiles. The impacted profiles have different linkIds.

REST API information:

POST http://host:port/context/rest/v1/visitor/unlink?ids=id1,id2,...idN

Query Params: id1,id2,...idN - comma separated list of visitorIDs that need tobe moved to the separate group.

Form Params: post form attributes - array of custom visitor attributes

Accept

: application/json, application/xml

Return: RestResponse

Parameters:

ids - array of String objects.

Returns:

true if operation success

Throws:

UnauthorizedAccessException - when there is a mismatch between access credentials passed while creating visitor client object and the expected credentials that visitor services expects javax.ws.rs.WebApplicationException in case the response status code of the response returned by the server is not successful.

close

public void close()
           throws Exception

Specified by:

close in interface AutoCloseable

Throws:

Exception