org.apache.unomi.api.services

Interface ProfileService

All Known Implementing Classes:

ProfileServiceImpl

public interface ProfileService

A service to access and operate on Profiles, Sessions and Personas.

Field Summary

Fields

Modifier and Type	Field and Description
static String	PERSONAL_IDENTIFIER_TAG_NAME

Method Summary

Modifier and Type	Method and Description
void	addAliasToProfile(String profileID, String alias, String clientID) Adds the alias to the profile.
void	batchProfilesUpdate(BatchUpdate update) Update all profiles in batch according to the specified BatchUpdate
Persona	createPersona(String personaId) Creates a persona with the specified identifier and automatically creates an associated session with it.
void	delete(String profileId, boolean persona) Removes the profile (or persona if the persona parameter is set to true) identified by the specified identifier.
boolean	deletePropertyType(String propertyId) Deletes the property type identified by the specified identifier.
String	exportProfilesPropertiesToCsv(Query query) Creates a String containing comma-separated values (CSV) formatted version of profiles matching the specified query.
PartialList<ProfileAlias>	findProfileAliases(String profileId, int offset, int size, String sortBy) Find profile aliases which have the specified property with the specified value, ordered according to the specified sortBy String and paged: only size of them are retrieved, starting with the offset-th one.
PartialList<Profile>	findProfilesByPropertyValue(String propertyName, String propertyValue, int offset, int size, String sortBy) Find profiles which have the specified property with the specified value, ordered according to the specified sortBy String and paged: only size of them are retrieved, starting with the offset-th one.
PartialList<Session>	findProfileSessions(String profileId) Retrieves sessions associated with the profile identified by the specified identifier.
long	getAllProfilesCount() Retrieves the number of unique profiles.
Set<PropertyType>	getExistingProperties(String tag, String itemType) Retrieves the existing property types for the specified type as defined by the Item subclass public field ITEM_TYPE and with the specified tag.
Set<PropertyType>	getExistingProperties(String tag, String itemType, boolean systemTag) Retrieves the existing property types for the specified type as defined by the Item subclass public field ITEM_TYPE and with the specified tag (system or regular) TODO: move to a different class
PartialList<Session>	getPersonaSessions(String personaId, int offset, int size, String sortBy) Retrieves the sessions associated with the persona identified by the specified identifier, ordered according to the specified sortBy String and and paged: only size of them are retrieved, starting with the offset-th one.
PartialList<Session>	getProfileSessions(String profileId, String query, int offset, int size, String sortBy) Retrieves the sessions associated with the profile identified by the specified identifier that match the specified query (if specified), ordered according to the specified sortBy String and and paged: only size of them are retrieved, starting with the offset-th one.
PropertyType	getPropertyType(String id) Retrieves the property type identified by the specified identifier.
Collection<PropertyType>	getPropertyTypeByMapping(String propertyName) TODO
Set<PropertyType>	getPropertyTypeBySystemTag(String tag) Retrieves all property types with the specified system tag TODO: move to a different class
Set<PropertyType>	getPropertyTypeByTag(String tag) Retrieves all property types with the specified tag TODO: move to a different class
String	getPropertyTypeMapping(String fromPropertyTypeId) TODO
Map<String,Collection<PropertyType>>	getTargetPropertyTypes() Retrieves all known property types.
Collection<PropertyType>	getTargetPropertyTypes(String target) Retrieves all the property types associated with the specified target.
Profile	load(String profileId) Retrieves the profile identified by the specified identifier.
Persona	loadPersona(String personaId) Retrieves the persona identified by the specified identifier.
PersonaWithSessions	loadPersonaWithSessions(String personaId) Retrieves the persona identified by the specified identifier and all its associated sessions
Session	loadSession(String sessionId, Date dateHint) Retrieves the session identified by the specified identifier.
boolean	matchCondition(Condition condition, Profile profile, Session session) Checks whether the specified profile and/or session satisfy the specified condition.
Profile	mergeProfiles(Profile masterProfile, List<Profile> profilesToMerge) Merges the specified profiles into the provided so-called master profile, merging properties according to the PropertyMergeStrategyType specified on their PropertyType.
void	purgeMonthlyItems(int existsNumberOfMonths) Purge (delete) monthly indices by removing old indices
void	purgeProfiles(int inactiveNumberOfDays, int existsNumberOfDays) Purge (delete) profiles example: Purge profile inactive since 10 days only: purgeProfiles(10, 0); example: Purge profile created since 30 days only: purgeProfiles(0, 30);
void	refresh() Forces a refresh of the profile service, to load data from persistence immediately instead of waiting for scheduled tasks to execute.
ProfileAlias	removeAliasFromProfile(String profileID, String alias, String clientID) Removes the alias from the profile.
void	removeProfileSessions(String profileId) Removes all sessions of the specified profile
Profile	save(Profile profile) Saves the specified profile in the context server.
Profile	saveOrMerge(Profile profile) Merge the specified profile properties in an existing profile,or save new profile if it does not exist yet
Persona	savePersona(Persona persona) Persists the specified Persona in the context server.
PersonaWithSessions	savePersonaWithSessions(PersonaWithSessions personaToSave) Save a persona with its sessions.
Session	saveSession(Session session) Saves the specified session.
<T extends Profile> PartialList<T>	search(Query query, Class<T> clazz) Retrieves profiles or personas matching the specified query.
PartialList<Session>	searchSessions(Query query) Retrieves sessions matching the specified query.
boolean	setPropertyType(PropertyType property) Persists the specified property type in the context server.
void	setPropertyTypeTarget(URL predefinedPropertyTypeURL, PropertyType propertyType) This function will try to set the target on the property type if not set already, based on the file URL

Field Detail

PERSONAL_IDENTIFIER_TAG_NAME

static final String PERSONAL_IDENTIFIER_TAG_NAME

See Also:

Constant Field Values

Method Detail

getAllProfilesCount

long getAllProfilesCount()

Retrieves the number of unique profiles.

Returns:

the number of unique profiles.

search

<T extends Profile> PartialList<T> search(Query query,
                                          Class<T> clazz)

Retrieves profiles or personas matching the specified query.

Type Parameters:

T - the specific sub-type of Profile to retrieve

Parameters:

query - a Query specifying which elements to retrieve

clazz - the class of elements to retrieve

Returns:

a PartialList of T instances matching the specified query

searchSessions

PartialList<Session> searchSessions(Query query)

Retrieves sessions matching the specified query.

Parameters:

query - a Query specifying which elements to retrieve

Returns:

a PartialList of sessions matching the specified query

exportProfilesPropertiesToCsv

String exportProfilesPropertiesToCsv(Query query)

Creates a String containing comma-separated values (CSV) formatted version of profiles matching the specified query.

Parameters:

query - the query specifying which profiles to export

Returns:

a CSV-formatted String version of the profiles matching the specified query

findProfilesByPropertyValue

PartialList<Profile> findProfilesByPropertyValue(String propertyName,
                                                 String propertyValue,
                                                 int offset,
                                                 int size,
                                                 String sortBy)

Find profiles which have the specified property with the specified value, ordered according to the specified sortBy String and paged: only size of them are retrieved, starting with the offset-th one. TODO: replace with version using a query instead of separate parameters TODO: remove as it's unused?

Parameters:

propertyName - the name of the property we're interested in

propertyValue - the value of the property we want profiles to have

offset - zero or a positive integer specifying the position of the first profile in the total ordered collection of matching profiles

size - a positive integer specifying how many matching profiles should be retrieved or -1 if all of them should be retrieved

sortBy - an optional (null if no sorting is required) String of comma (,) separated property names on which ordering should be performed, ordering elements according to the property order in the String, considering each in turn and moving on to the next one in case of equality of all preceding ones. Each property name is optionally followed by a column (:) and an order specifier: asc or desc.

Returns:

a PartialList of matching profiles

mergeProfiles

Profile mergeProfiles(Profile masterProfile,
                      List<Profile> profilesToMerge)

Merges the specified profiles into the provided so-called master profile, merging properties according to the PropertyMergeStrategyType specified on their PropertyType.

Parameters:

masterProfile - the profile into which the specified profiles will be merged

profilesToMerge - the list of profiles to merge into the specified master profile

Returns:

the merged profile

load

Profile load(String profileId)

Retrieves the profile identified by the specified identifier.

Parameters:

profileId - the identifier of the profile to retrieve

Returns:

the profile identified by the specified identifier or null if no such profile exists

save

Profile save(Profile profile)

Saves the specified profile in the context server.

Parameters:

profile - the profile to be saved

Returns:

the newly saved profile

addAliasToProfile

void addAliasToProfile(String profileID,
                       String alias,
                       String clientID)

Adds the alias to the profile.

Parameters:

profileID - the identifier of the profile

alias - the alias which should be linked with of the profile

clientID - the identifier of the client

removeAliasFromProfile

ProfileAlias removeAliasFromProfile(String profileID,
                                    String alias,
                                    String clientID)

Removes the alias from the profile.

Parameters:

profileID - the identifier of the profile

alias - the alias which should be unlinked from the profile

clientID - the identifier of the client

findProfileAliases

PartialList<ProfileAlias> findProfileAliases(String profileId,
                                             int offset,
                                             int size,
                                             String sortBy)

Find profile aliases which have the specified property with the specified value, ordered according to the specified sortBy String and paged: only size of them are retrieved, starting with the offset-th one.

Parameters:

profileId - the identifier of the profile

offset - zero or a positive integer specifying the position of the first profile in the total ordered collection of matching profiles

size - a positive integer specifying how many matching profiles should be retrieved or -1 if all of them should be retrieved

sortBy - an optional (null if no sorting is required) String of comma (,) separated property names on which ordering should be performed, ordering elements according to the property order in the String, considering each in turn and moving on to the next one in case of equality of all preceding ones. Each property name is optionally followed by a column (:) and an order specifier: asc or desc.

Returns:

a PartialList of matching profiles

saveOrMerge

Profile saveOrMerge(Profile profile)

Merge the specified profile properties in an existing profile,or save new profile if it does not exist yet

Parameters:

profile - the profile to be saved

Returns:

the newly saved or merged profile or null if the save or merge operation failed.

delete

void delete(String profileId,
            boolean persona)

Removes the profile (or persona if the persona parameter is set to true) identified by the specified identifier.

Parameters:

profileId - the identifier of the profile or persona to delete

persona - true if the specified identifier is supposed to refer to a persona, false if it is supposed to refer to a profile

getProfileSessions

PartialList<Session> getProfileSessions(String profileId,
                                        String query,
                                        int offset,
                                        int size,
                                        String sortBy)

Retrieves the sessions associated with the profile identified by the specified identifier that match the specified query (if specified), ordered according to the specified sortBy String and and paged: only size of them are retrieved, starting with the offset-th one. TODO: use a Query object instead of distinct parameter

Parameters:

profileId - the identifier of the profile we want to retrieve sessions from

query - a String of text used for fulltext filtering which sessions we are interested in or null (or an empty String) if we want to retrieve all sessions

offset - zero or a positive integer specifying the position of the first session in the total ordered collection of matching sessions

size - a positive integer specifying how many matching sessions should be retrieved or -1 if all of them should be retrieved

sortBy - an optional (null if no sorting is required) String of comma (,) separated property names on which ordering should be performed, ordering elements according to the property order in the String, considering each in turn and moving on to the next one in case of equality of all preceding ones. Each property name is optionally followed by a column (:) and an order specifier: asc or desc.

Returns:

a PartialList of matching sessions

loadSession

Session loadSession(String sessionId,
                    Date dateHint)

Retrieves the session identified by the specified identifier.

Parameters:

sessionId - the identifier of the session to be retrieved

dateHint - a Date helping in identifying where the item is located

Returns:

the session identified by the specified identifier

saveSession

Session saveSession(Session session)

Saves the specified session.

Parameters:

session - the session to be saved

Returns:

the newly saved session

findProfileSessions

PartialList<Session> findProfileSessions(String profileId)

Retrieves sessions associated with the profile identified by the specified identifier.

Parameters:

profileId - the profile id for which we want to retrieve the sessions

Returns:

a PartialList of the profile's sessions

removeProfileSessions

void removeProfileSessions(String profileId)

Removes all sessions of the specified profile

Parameters:

profileId - identifier of the profile that we want to remove it's sessions

matchCondition

boolean matchCondition(Condition condition,
                       Profile profile,
                       Session session)

Checks whether the specified profile and/or session satisfy the specified condition.

Parameters:

condition - the condition we're testing against which might or might not have profile- or session-specific sub-conditions

profile - the profile we're testing

session - the session we're testing

Returns:

true if the profile and/or sessions match the specified condition, false otherwise

batchProfilesUpdate

void batchProfilesUpdate(BatchUpdate update)

Update all profiles in batch according to the specified BatchUpdate

Parameters:

update - the batch update specification

loadPersona

Persona loadPersona(String personaId)

Retrieves the persona identified by the specified identifier.

Parameters:

personaId - the identifier of the persona to retrieve

Returns:

the persona associated with the specified identifier or null if no such persona exists.

savePersona

Persona savePersona(Persona persona)

Persists the specified Persona in the context server.

Parameters:

persona - the persona to persist

Returns:

the newly persisted persona

loadPersonaWithSessions

PersonaWithSessions loadPersonaWithSessions(String personaId)

Retrieves the persona identified by the specified identifier and all its associated sessions

Parameters:

personaId - the identifier of the persona to retrieve

Returns:

a PersonaWithSessions instance with the persona identified by the specified identifier and all its associated sessions

createPersona

Persona createPersona(String personaId)

Creates a persona with the specified identifier and automatically creates an associated session with it.

Parameters:

personaId - the identifier to use for the new persona

Returns:

the newly created persona

getPersonaSessions

PartialList<Session> getPersonaSessions(String personaId,
                                        int offset,
                                        int size,
                                        String sortBy)

Retrieves the sessions associated with the persona identified by the specified identifier, ordered according to the specified sortBy String and and paged: only size of them are retrieved, starting with the offset-th one.

Parameters:

personaId - the persona id

offset - zero or a positive integer specifying the position of the first session in the total ordered collection of matching sessions

size - a positive integer specifying how many matching sessions should be retrieved or -1 if all of them should be retrieved

sortBy - an optional (null if no sorting is required) String of comma (,) separated property names on which ordering should be performed, ordering elements according to the property order in the String, considering each in turn and moving on to the next one in case of equality of all preceding ones. Each property name is optionally followed by a column (:) and an order specifier: asc or desc.

Returns:

a PartialList of sessions for the persona identified by the specified identifier

savePersonaWithSessions

PersonaWithSessions savePersonaWithSessions(PersonaWithSessions personaToSave)

Save a persona with its sessions.

Parameters:

personaToSave - the persona object containing all the persona information and sessions

Returns:

the persona with sessions

getTargetPropertyTypes

Collection<PropertyType> getTargetPropertyTypes(String target)

Retrieves all the property types associated with the specified target. TODO: move to a different class

Parameters:

target - the target for which we want to retrieve the associated property types

Returns:

a collection of all the property types associated with the specified target

getTargetPropertyTypes

Map<String,Collection<PropertyType>> getTargetPropertyTypes()

Retrieves all known property types. TODO: move to a different class TODO: use Map instead of HashMap

Returns:

a Map associating targets as keys to related PropertyTypes

getPropertyTypeByTag

Set<PropertyType> getPropertyTypeByTag(String tag)

Retrieves all property types with the specified tag TODO: move to a different class

Parameters:

tag - the tag name marking property types we want to retrieve

Returns:

a Set of the property types with the specified tag

getPropertyTypeBySystemTag

Set<PropertyType> getPropertyTypeBySystemTag(String tag)

Retrieves all property types with the specified system tag TODO: move to a different class

Parameters:

tag - the system tag name marking property types we want to retrieve

Returns:

a Set of the property types with the specified system tag

getPropertyTypeMapping

String getPropertyTypeMapping(String fromPropertyTypeId)

TODO

Parameters:

fromPropertyTypeId - fromPropertyTypeId

Returns:

property type mapping

getPropertyTypeByMapping

Collection<PropertyType> getPropertyTypeByMapping(String propertyName)

TODO

Parameters:

propertyName - the property name

Returns:

list of property types

getPropertyType

PropertyType getPropertyType(String id)

Retrieves the property type identified by the specified identifier. TODO: move to a different class

Parameters:

id - the identifier of the property type to retrieve

Returns:

the property type identified by the specified identifier or null if no such property type exists

setPropertyType

boolean setPropertyType(PropertyType property)

Persists the specified property type in the context server. TODO: move to a different class

Parameters:

property - the property type to persist

Returns:

true if the property type was properly created, false otherwise (for example, if the property type already existed

setPropertyTypeTarget

void setPropertyTypeTarget(URL predefinedPropertyTypeURL,
                           PropertyType propertyType)

This function will try to set the target on the property type if not set already, based on the file URL

Parameters:

predefinedPropertyTypeURL - the URL to extract the target from if the target is not yet. By default it will use the 5's part after a "/" character

propertyType - the property type to register

deletePropertyType

boolean deletePropertyType(String propertyId)

Deletes the property type identified by the specified identifier. TODO: move to a different class

Parameters:

propertyId - the identifier of the property type to delete

Returns:

true if the property type was properly deleted, false otherwise

getExistingProperties

Set<PropertyType> getExistingProperties(String tag,
                                        String itemType)

Retrieves the existing property types for the specified type as defined by the Item subclass public field ITEM_TYPE and with the specified tag. TODO: move to a different class

Parameters:

tag - the tag we're interested in

itemType - the String representation of the item type we want to retrieve the count of, as defined by its class' ITEM_TYPE field

Returns:

all property types defined for the specified item type and with the specified tag

getExistingProperties

Set<PropertyType> getExistingProperties(String tag,
                                        String itemType,
                                        boolean systemTag)

Retrieves the existing property types for the specified type as defined by the Item subclass public field ITEM_TYPE and with the specified tag (system or regular) TODO: move to a different class

Parameters:

tag - the tag we're interested in

itemType - the String representation of the item type we want to retrieve the count of, as defined by its class' ITEM_TYPE field

systemTag - whether the specified is a system tag or a regular one

Returns:

all property types defined for the specified item type and with the specified tag

refresh

void refresh()

Forces a refresh of the profile service, to load data from persistence immediately instead of waiting for scheduled tasks to execute. Warning : this may have serious impacts on performance so it should only be used in specific scenarios such as integration tests.

purgeProfiles

void purgeProfiles(int inactiveNumberOfDays,
                   int existsNumberOfDays)

Purge (delete) profiles example: Purge profile inactive since 10 days only: purgeProfiles(10, 0); example: Purge profile created since 30 days only: purgeProfiles(0, 30);

Parameters:

inactiveNumberOfDays - will purge profiles with no visits since this number of days (0 or negative value, will have no effect)

existsNumberOfDays - will purge profiles created since this number of days (0 or negative value, will have no effect)

purgeMonthlyItems

void purgeMonthlyItems(int existsNumberOfMonths)

Purge (delete) monthly indices by removing old indices

Parameters:

existsNumberOfMonths - used to remove monthly indices older than this number of months