org.craftercms.profile.api.services

Interface ProfileService

public interface ProfileService

Service for handling profiles.

Author:

avasquez

Method Summary

Methods

Modifier and Type	Method and Description
ProfileAttachment	addProfileAttachment(String profileId, String attachmentName, InputStream file) Saves a Profile Attachment
Profile	addRoles(String profileId, Collection<String> roles, String... attributesToReturn) Assigns roles to the profile.
Profile	changePassword(String resetTokenId, String newPassword, String... attributesToReturn) Changes a profile's password, after a reset request has been sent.
Profile	createProfile(String tenantName, String username, String password, String email, boolean enabled, Set<String> roles, Map<String,Object> attributes, String verificationUrl) Creates a new profile for a specific tenant name.
VerificationToken	createVerificationToken(String profileId) Creates a token that can be sent to the user in an email as a link.
void	deleteProfile(String profileId) Deletes a profile.
void	deleteVerificationToken(String tokenId) Deletes a verification token when it's not needed anymore (not necessary to call if verifyProfile(String, String...) or changePassword(String, String, String...), since they already delete the token.
Profile	disableProfile(String profileId, String... attributesToReturn) Disables a profile.
Profile	enableProfile(String profileId, String... attributesToReturn) Enables a profile.
Map<String,Object>	getAttributes(String profileId, String... attributesToReturn) Returns the attributes of a profile.
Profile	getProfile(String profileId, String... attributesToReturn) Returns the profile for the specified ID.
InputStream	getProfileAttachment(String attachmentId, String profileId) Given the Attachment Id and the Profile Id, gets the Actual Attachment.
ProfileAttachment	getProfileAttachmentInformation(String profileId, String attachmentId) Gets Profile attachment Information.
List<ProfileAttachment>	getProfileAttachments(String profileId) List all Attachments for the given profile.
Profile	getProfileByQuery(String tenantName, String query, String... attributesToReturn) Returns the single profile that matches the specified query
Profile	getProfileByTicket(String ticketId, String... attributesToReturn) Returns the profile for the specified ticket.
Profile	getProfileByUsername(String tenantName, String username, String... attributesToReturn) Returns the user for the specified tenant and username
long	getProfileCount(String tenantName) Returns the number of profiles of the specified tenant.
long	getProfileCountByQuery(String tenantName, String query) Returns the number of profiles that match the query for the specified tenant.
List<Profile>	getProfileRange(String tenantName, String sortBy, SortOrder sortOrder, Integer start, Integer count, String... attributesToReturn) Returns a range of profiles for the specified tenant.
List<Profile>	getProfilesByAttributeValue(String tenantName, String attributeName, String attributeValue, String sortBy, SortOrder sortOrder, String... attributesToReturn) Returns the list of profiles that have the given attribute with the given value.
List<Profile>	getProfilesByExistingAttribute(String tenantName, String attributeName, String sortBy, SortOrder sortOrder, String... attributesToReturn) Returns the list of profiles that have the given attribute, with any value
List<Profile>	getProfilesByIds(List<String> profileIds, String sortBy, SortOrder sortOrder, String... attributesToReturn) Returns a list of profiles for the specified list of IDs.
List<Profile>	getProfilesByQuery(String tenantName, String query, String sortBy, SortOrder sortOrder, Integer start, Integer count, String... attributesToReturn) Returns the profiles that match the specified query.
List<Profile>	getProfilesByRole(String tenantName, String role, String sortBy, SortOrder sortOrder, String... attributesToReturn) Returns a list of profiles for a specific role and tenant.
VerificationToken	getVerificationToken(String tokenId) Returns the verification token that corresponds to the given ID.
Profile	removeAttributes(String profileId, Collection<String> attributeNames, String... attributesToReturn) Removes a list of attributes of a profile.
Profile	removeRoles(String profileId, Collection<String> roles, String... attributesToReturn) Removes assigned roles from a profile.
Profile	resetPassword(String profileId, String resetPasswordUrl, String... attributesToReturn) Sends an email to the profile's user to indicate that the password needs to be reset.
Profile	setFailedAttempts(String profileId, int failedAttempts, String... attributesToReturn)
Profile	setLastFailedLogging(String profileId, Date lastFailedLogging, String... attributesToReturn)
Profile	updateAttributes(String profileId, Map<String,Object> attributes, String... attributesToReturn) Updates the attributes of a profile, by merging the specified attributes with the existing attributes.
Profile	updateProfile(String profileId, String username, String password, String email, Boolean enabled, Set<String> roles, Map<String,Object> attributes, String... attributesToReturn) Updates the profile's info.
Profile	verifyProfile(String verificationTokenId, String... attributesToReturn) Sets the profile as verified if the verification token is valid.

Method Detail

createProfile

Profile createProfile(String tenantName,
                    String username,
                    String password,
                    String email,
                    boolean enabled,
                    Set<String> roles,
                    Map<String,Object> attributes,
                    String verificationUrl)
                      throws ProfileException

Creates a new profile for a specific tenant name.

Parameters:

tenantName - the name of the tenant to add the profile to

username - the profile's username

password - the profile's password

email - the profile's email

enabled - if the profile should be enabled or not

roles - the profile's roles (optional)

attributes - the additional attributes to add to the profile (optional)

verificationUrl - the URL (sans token) the user needs to go in case it needs to verify the created profile (verification depends on tenant) (optional).

Returns:

the newly created profile

Throws:

ProfileException

updateProfile

Profile updateProfile(String profileId,
                    String username,
                    String password,
                    String email,
                    Boolean enabled,
                    Set<String> roles,
                    Map<String,Object> attributes,
                    String... attributesToReturn)
                      throws ProfileException

Updates the profile's info.

Parameters:

profileId - the profile's ID

username - the new username for the profile, or null if it shouldn't be updated

password - the new password for the profile, or null if it shouldn't be updated

email - the new email for the profile, or null if it shouldn't be updated

enabled - if the profile should be enabled or not, or null if it shouldn't be updated

roles - the new roles for the profile, or null if the roles shouldn't be updated

attributes - the attributes to update, or null if no attribute should be updated

attributesToReturn - the names of the attributes to return (null to return all attributes)

Returns:

the updated profile

Throws:

ProfileException

verifyProfile

Profile verifyProfile(String verificationTokenId,
                    String... attributesToReturn)
                      throws ProfileException

Sets the profile as verified if the verification token is valid.

Parameters:

verificationTokenId - the verification token ID

attributesToReturn - the names of the attributes to return with the profile (null to return all attributes)

Returns:

the updated profile associated to the token

Throws:

ProfileException

enableProfile

Profile enableProfile(String profileId,
                    String... attributesToReturn)
                      throws ProfileException

Enables a profile.

Parameters:

profileId - the profile's ID

attributesToReturn - the names of the attributes to return with the profile (null to return all attributes)

Returns:

the updated profile

Throws:

ProfileException

setLastFailedLogging

Profile setLastFailedLogging(String profileId,
                           Date lastFailedLogging,
                           String... attributesToReturn)
                             throws ProfileException

Throws:

ProfileException

setFailedAttempts

Profile setFailedAttempts(String profileId,
                        int failedAttempts,
                        String... attributesToReturn)
                          throws ProfileException

Throws:

ProfileException

disableProfile

Profile disableProfile(String profileId,
                     String... attributesToReturn)
                       throws ProfileException

Disables a profile.

Parameters:

profileId - the profile's ID

attributesToReturn - the names of the attributes to return with the profile (null to return all attributes)

Returns:

the updated profile

Throws:

ProfileException

addRoles

Profile addRoles(String profileId,
               Collection<String> roles,
               String... attributesToReturn)
                 throws ProfileException

Assigns roles to the profile.

Parameters:

profileId - the profile's ID

roles - the roles to assign

attributesToReturn - the names of the attributes to return with the profile (null to return all attributes)

Returns:

the updated profile

Throws:

ProfileException

removeRoles

Profile removeRoles(String profileId,
                  Collection<String> roles,
                  String... attributesToReturn)
                    throws ProfileException

Removes assigned roles from a profile.

Parameters:

profileId - the profile's ID

roles - the roles to remove

attributesToReturn - the names of the attributes to return with the profile (null to return all attributes)

Returns:

the updated profile

Throws:

ProfileException

getAttributes

Map<String,Object> getAttributes(String profileId,
                               String... attributesToReturn)
                                 throws ProfileException

Returns the attributes of a profile.

Parameters:

profileId - the profile's ID

attributesToReturn - the names of the attributes to return (null to return all attributes)

Returns:

the profile's attributes

Throws:

ProfileException

updateAttributes

Profile updateAttributes(String profileId,
                       Map<String,Object> attributes,
                       String... attributesToReturn)
                         throws ProfileException

Updates the attributes of a profile, by merging the specified attributes with the existing attributes.

Parameters:

profileId - the profile's ID

attributes - the new attributes

attributesToReturn - the names of the attributes to return withe the profile (null to return all attributes)

Returns:

the updated profile

Throws:

ProfileException

removeAttributes

Profile removeAttributes(String profileId,
                       Collection<String> attributeNames,
                       String... attributesToReturn)
                         throws ProfileException

Removes a list of attributes of a profile.

Parameters:

profileId - the profile's ID

attributeNames - the names of the attributes to remove

attributesToReturn - the names of the attributes to return withe the profile (null to return all attributes)

Returns:

the updated profile

Throws:

ProfileException

deleteProfile

void deleteProfile(String profileId)
                   throws ProfileException

Deletes a profile.

Parameters:

profileId - the profile's ID

Throws:

ProfileException

getProfileByQuery

Profile getProfileByQuery(String tenantName,
                        String query,
                        String... attributesToReturn)
                          throws ProfileException

Returns the single profile that matches the specified query

Parameters:

tenantName - the tenant's name

query - the Mongo query used to search for the profiles. Must not contain the $where operator, the tenant's name (already specified) or any non-readable attribute by the application

attributesToReturn - the names of the attributes to return with the profile (null to return all attributes)

Returns:

the profile, or null if not found

Throws:

ProfileException

getProfile

Profile getProfile(String profileId,
                 String... attributesToReturn)
                   throws ProfileException

Returns the profile for the specified ID.

Parameters:

profileId - the profile's ID

attributesToReturn - the names of the attributes to return with the profile (null to return all attributes)

Returns:

the profile, or null if not found

Throws:

ProfileException

getProfileByUsername

Profile getProfileByUsername(String tenantName,
                           String username,
                           String... attributesToReturn)
                             throws ProfileException

Returns the user for the specified tenant and username

Parameters:

tenantName - the tenant's name

username - the profile's username

attributesToReturn - the names of the attributes to return with the profile (null to return all attributes)

Returns:

the profile, or null if not found

Throws:

ProfileException

getProfileByTicket

Profile getProfileByTicket(String ticketId,
                         String... attributesToReturn)
                           throws ProfileException

Returns the profile for the specified ticket.

Parameters:

ticketId - the ID ticket of the authenticated profile

attributesToReturn - the names of the attributes to return with the profile (null to return all attributes)

Returns:

the profile, or null if not found

Throws:

ProfileException

getProfileCount

long getProfileCount(String tenantName)
                     throws ProfileException

Returns the number of profiles of the specified tenant.

Parameters:

tenantName - the tenant's name

Returns:

the number of profiles of the specified tenant

Throws:

ProfileException

getProfileCountByQuery

long getProfileCountByQuery(String tenantName,
                          String query)
                            throws ProfileException

Returns the number of profiles that match the query for the specified tenant.

Parameters:

tenantName - the tenant's name

query - the Mongo query used to search for the profiles. Must not contain the $where operator, the tenant's name (already specified) or any non-readable attribute by the application

Returns:

the number of profiles of the specified tenant

Throws:

ProfileException

getProfilesByQuery

List<Profile> getProfilesByQuery(String tenantName,
                               String query,
                               String sortBy,
                               SortOrder sortOrder,
                               Integer start,
                               Integer count,
                               String... attributesToReturn)
                                 throws ProfileException

Returns the profiles that match the specified query.

Parameters:

tenantName - the tenant's name

query - the Mongo query used to search for the profiles. Must not contain the $where operator, the tenant's name (already specified) or any non-readable attribute by the application

sortBy - profile attribute to sort the list by (optional)

sortOrder - the sort order (either ASC or DESC) (optional)

start - from the entire list of results, the position where the actual results should start (useful for pagination) (optional)

count - the number of profiles to return (optional)

attributesToReturn - the names of the attributes to return with the profile (null to return all attributes)

Returns:

the list of profiles found, or null if none match the query

Throws:

ProfileException

getProfilesByIds

List<Profile> getProfilesByIds(List<String> profileIds,
                             String sortBy,
                             SortOrder sortOrder,
                             String... attributesToReturn)
                               throws ProfileException

Returns a list of profiles for the specified list of IDs.

Parameters:

profileIds - the IDs of the profiles to look for

sortBy - profile attribute to sort the list by (optional)

sortOrder - the sort order (either ASC or DESC) (optional)

attributesToReturn - the names of the attributes to return for each profile (null to return all attributes)

Returns:

the list of profiles (can be smaller than the list of ids if some where not found)

Throws:

ProfileException

getProfileRange

List<Profile> getProfileRange(String tenantName,
                            String sortBy,
                            SortOrder sortOrder,
                            Integer start,
                            Integer count,
                            String... attributesToReturn)
                              throws ProfileException

Returns a range of profiles for the specified tenant.

Parameters:

tenantName - the tenant's name

sortBy - profile attribute to sort the list by (optional)

sortOrder - the sort order (either ASC or DESC) (optional)

start - from the entire list of results, the position where the actual results should start (useful for pagination) (optional)

count - the number of profiles to return (optional)

attributesToReturn - the names of the attributes to return for each profile (null to return all attributes)

Returns:

the list of profiles

Throws:

ProfileException

getProfilesByRole

List<Profile> getProfilesByRole(String tenantName,
                              String role,
                              String sortBy,
                              SortOrder sortOrder,
                              String... attributesToReturn)
                                throws ProfileException

Returns a list of profiles for a specific role and tenant.

Parameters:

tenantName - the tenant's name

role - the role's name

sortBy - profile attribute to sort the list by (optional)

sortOrder - the sort order (either ASC or DESC) (optional)

attributesToReturn - the names of the attributes to return for each profile (null to return all attributes)

Returns:

the list of profiles

Throws:

ProfileException

getProfilesByExistingAttribute

List<Profile> getProfilesByExistingAttribute(String tenantName,
                                           String attributeName,
                                           String sortBy,
                                           SortOrder sortOrder,
                                           String... attributesToReturn)
                                             throws ProfileException

Returns the list of profiles that have the given attribute, with any value

Parameters:

tenantName - the tenant's name

attributeName - the name of the attribute profiles must have

sortBy - profile attribute to sort the list by (optional)

sortOrder - the sort order (either ASC or DESC) (optional)

attributesToReturn - the names of the attributes to return for each profile (null to return all attributes)

Returns:

the list of profiles

Throws:

ProfileException

getProfilesByAttributeValue

List<Profile> getProfilesByAttributeValue(String tenantName,
                                        String attributeName,
                                        String attributeValue,
                                        String sortBy,
                                        SortOrder sortOrder,
                                        String... attributesToReturn)
                                          throws ProfileException

Returns the list of profiles that have the given attribute with the given value.

Parameters:

tenantName - the tenant's name

attributeName - the name of the attribute profiles must have

attributeValue - the value of the attribute profiles must have

sortBy - profile attribute to sort the list by (optional)

sortOrder - the sort order (either ASC or DESC) (optional)

attributesToReturn - the names of the attributes to return for each profile (null to return all attributes)

Returns:

the list of profiles

Throws:

ProfileException

resetPassword

Profile resetPassword(String profileId,
                    String resetPasswordUrl,
                    String... attributesToReturn)
                      throws ProfileException

Sends an email to the profile's user to indicate that the password needs to be reset.

Parameters:

profileId - the profile's ID

resetPasswordUrl - the base URL to use to build the final URL the profile will use to reset their password.

attributesToReturn - the names of the attributes to return with the profile (null to return all attributes)

Returns:

the updated profile

Throws:

ProfileException

changePassword

Profile changePassword(String resetTokenId,
                     String newPassword,
                     String... attributesToReturn)
                       throws ProfileException

Changes a profile's password, after a reset request has been sent.

Parameters:

resetTokenId - the reset token ID

newPassword - the new password

attributesToReturn - the names of the attributes to return with the profile (null to return all attributes)

Returns:

the updated profile

Throws:

ProfileException

createVerificationToken

VerificationToken createVerificationToken(String profileId)
                                          throws ProfileException

Creates a token that can be sent to the user in an email as a link. After the user clicks the link, the token then can be passed to verifyProfile(String, String...) or changePassword(String, String, String...) to verify that the user agrees.

Parameters:

profileId - the profile ID of the user that needs to be contacted

Returns:

the created token

Throws:

ProfileException

getVerificationToken

VerificationToken getVerificationToken(String tokenId)
                                       throws ProfileException

Returns the verification token that corresponds to the given ID.

Parameters:

tokenId - the token ID

Returns:

the verification token, or null if not found

Throws:

ProfileException

deleteVerificationToken

void deleteVerificationToken(String tokenId)
                             throws ProfileException

Deletes a verification token when it's not needed anymore (not necessary to call if verifyProfile(String, String...) or changePassword(String, String, String...), since they already delete the token.

Parameters:

tokenId - the ID of the token to delete

Throws:

ProfileException

addProfileAttachment

ProfileAttachment addProfileAttachment(String profileId,
                                     String attachmentName,
                                     InputStream file)
                                       throws ProfileException

Saves a Profile Attachment

Parameters:

profileId - Id of the profile owner of the attachment.

attachmentName - File name of the Attachment;

file - Actual File to be Attach.

Returns:

A Profile Attachment Contains all the information of the Actual Attachment (including the id);

Throws:

ProfileException - If attachment can not be saved;

getProfileAttachmentInformation

ProfileAttachment getProfileAttachmentInformation(String profileId,
                                                String attachmentId)
                                                  throws ProfileException

Gets Profile attachment Information.

Parameters:

profileId - Profile owner of the Attachment.

attachmentId - Attachment Id.

Returns:

Null if Attachment Id does not exist or does not belong to the user.

Throws:

ProfileException - If Attachment cannot be found.

getProfileAttachment

InputStream getProfileAttachment(String attachmentId,
                               String profileId)
                                 throws ProfileException

Given the Attachment Id and the Profile Id, gets the Actual Attachment.

Parameters:

attachmentId - Attachment Id to get.

profileId - Profile Owner of the Attachment.

Returns:

Null If Attachment Id does no exist or does not belong to the given profile. InputStream of the actual File.

Throws:

ProfileService - If unable to get the Attachment.

ProfileException

getProfileAttachments

List<ProfileAttachment> getProfileAttachments(String profileId)
                                              throws ProfileException

List all Attachments for the given profile.

Parameters:

profileId - Profile to get all Attachments

Returns:

The List of attachments that the profile has ,never null.

Throws:

ProfileException - If unable to get Profile attachments.