org.bonitasoft.engine.api.ProfileAPI Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of bonita-common Show documentation
Show all versions of bonita-common Show documentation
Bonita Common is the useful layer common to bonita-client and bonita-server
/**
* Copyright (C) 2019 Bonitasoft S.A.
* Bonitasoft, 32 rue Gustave Eiffel - 38000 Grenoble
* This library is free software; you can redistribute it and/or modify it under the terms
* of the GNU Lesser General Public License as published by the Free Software Foundation
* version 2.1 of the License.
* This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
* without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
* See the GNU Lesser General Public License for more details.
* You should have received a copy of the GNU Lesser General Public License along with this
* program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth
* Floor, Boston, MA 02110-1301, USA.
**/
package org.bonitasoft.engine.api;
import java.util.List;
import java.util.Map;
import org.bonitasoft.engine.exception.AlreadyExistsException;
import org.bonitasoft.engine.exception.CreationException;
import org.bonitasoft.engine.exception.DeletionException;
import org.bonitasoft.engine.exception.SearchException;
import org.bonitasoft.engine.profile.Profile;
import org.bonitasoft.engine.profile.ProfileCriterion;
import org.bonitasoft.engine.profile.ProfileMember;
import org.bonitasoft.engine.profile.ProfileMemberCreator;
import org.bonitasoft.engine.profile.ProfileNotFoundException;
import org.bonitasoft.engine.search.SearchOptions;
import org.bonitasoft.engine.search.SearchResult;
/**
* Profiles are a notion used in Bonita Portal to give and control access to some specific features of the Bonita suite.
* Profiles are associated to Bonita Identity / Organization notions: users, groups, roles, memberships.
* ProfileAPI gives access to some of the
* profile administration: adding / removing members to / from a profile, retrieving / searching for profiles.
* Full control on profiles is part of Subscription editions of Bonita suite.
*
* @author Celine Souchet
* @author Matthieu Chaffotte
* @see SearchResult SearchResult for general knowledege on Search mechanism in Bonita.
*/
public interface ProfileAPI {
/**
* Retrieves the profile.
*
* @param id
* The identifier of the profile
* @return the searched profile
* @throws ProfileNotFoundException
* If the identifier does not refer to an existing profile
* @throws org.bonitasoft.engine.exception.RetrieveException
* If an exception occurs during the profile retrieving
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If the session is invalid (expired, unknown, ...)
* @since 6.0
*/
Profile getProfile(long id) throws ProfileNotFoundException;
/**
* Retrieves the profiles of the user.
*
* @param userId
* The identifier of the user
* @param startIndex
* The index of the first result (starting from 0).
* @param maxResults
* The maximum number of elements to get per page.
* @param criterion
* The criterion for sorting the items over pages.
* @return The paginated and ordered profiles of the user
* @throws org.bonitasoft.engine.exception.RetrieveException
* If an exception occurs during the profile retrieving
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If the session is invalid (expired, unknown, ...)
* @since 6.3.2
*/
List getProfilesForUser(long userId, int startIndex, int maxResults, ProfileCriterion criterion);
/**
* Searches for {@link Profile}s with specific search criteria. Use
* {@link org.bonitasoft.engine.profile.ProfileSearchDescriptor} to
* know the available filters.
*
* @param options
* The search criteria
* @return a {@link SearchResult} containing the list of {@code Profile}s matching the search criteria.
* @throws SearchException
* If an exception occurs during the profile searching
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If the session is invalid (expired, unknown, ...)
* @since 6.0
* @see Profile
* @see org.bonitasoft.engine.profile.ProfileSearchDescriptor
* @see SearchResult
*/
SearchResult searchProfiles(SearchOptions options) throws SearchException;
/**
* Retrieves the number of profile members for the profiles. The map contains the couples
* profileId/numberOfProfileMembers.
*
* If a profile does not exist, no exception is thrown and no value is added in the map.
*
*
* @param profileIds
* The identifiers of the profiles
* @return the number of profile members for the profiles
* @throws org.bonitasoft.engine.exception.RetrieveException
* If an exception occurs during the profile retrieving
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If the session is invalid (expired, unknown, ...)
* @since 6.0
*/
Map getNumberOfProfileMembers(List profileIds);
/**
* Searches for {@link ProfileMember}s with specific search criteria. Use
* {@link org.bonitasoft.engine.profile.ProfileMemberSearchDescriptor} to
* know the available filters.
*
* @param memberType
* The member type, it can be: user, role, group, roleAndGroup.
* @param options
* The search criteria
* @return a {@link SearchResult} containing the list of {@code ProfileMember}s matching the search criteria.
* @throws SearchException
* If an exception occurs during the profile searching
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If the session is invalid (expired, unknown, ...)
* @since 6.0
* @see ProfileMember
* @see org.bonitasoft.engine.profile.ProfileMemberSearchDescriptor
* @see SearchResult
*/
SearchResult searchProfileMembers(String memberType, SearchOptions options) throws SearchException;
/**
* Creates a profile member.
*
* @param profileId
* The identifier of the profile
* @param userId
* The identifier of the user
* @param groupId
* The identifier of the group
* @param roleId
* The identifier of the role
* @return the created profile member
* @throws AlreadyExistsException
* If the tuple profileId/userId/roleId/groupId is already taken by an existing profile member
* @throws CreationException
* If an exception occurs during the profile member creation
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If the session is invalid (expired, unknown, ...)
* @since 6.0
*/
ProfileMember createProfileMember(Long profileId, Long userId, Long groupId, Long roleId)
throws CreationException, AlreadyExistsException;
/**
* Creates a profile member.
*
* It takes the values of the creator in order to create the profile member.
*
*
* @param creator
* The profile member to create
* @return the created profile member
* @throws AlreadyExistsException
* If the tuple profileId/userId/roleId/groupId is already taken by an existing profile member
* @throws CreationException
* If an exception occurs during the profile member creation
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If the session is invalid (expired, unknown, ...)
* @since 6.0
*/
ProfileMember createProfileMember(ProfileMemberCreator creator) throws CreationException, AlreadyExistsException;
/**
* Deletes the profile member.
*
* @param id
* The identifier of the profile member
* @throws DeletionException
* If an exception occurs during the profile member deletion
* @throws org.bonitasoft.engine.session.InvalidSessionException
* If the session is invalid (expired, unknown, ...)
* @since 6.0
*/
void deleteProfileMember(Long id) throws DeletionException;
}