org.xlcloud.service.api.UsersApi Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of xms-api Show documentation
The newest version!
/*
 * Copyright 2012 AMG.lab, a Bull Group Company
 * 
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 * 
 *    http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.xlcloud.service.api;

import java.util.List;

import org.xlcloud.rest.exception.ObjectNotFoundException;
import org.xlcloud.rest.exception.ValidationException;
import org.xlcloud.service.AccessTokens;
import org.xlcloud.service.Entitlement;
import org.xlcloud.service.Entitlements;
import org.xlcloud.service.Groups;
import org.xlcloud.service.Projects;
import org.xlcloud.service.ScopeType;
import org.xlcloud.service.User;
import org.xlcloud.service.Users;

/**
 * Interface for API that allows to manage {@link User}'s and related resources.
 * 
 * @author Tomek Adamczewski, AMG.net
 * @author Ksiazczyk Grzegorz, AMG.net
 * @author Konrad Król, AMG.net
 */
public interface UsersApi {

    /**
     * Returns the {@link Users} list.
     * @return users list wrapped into {@link Users} object
     */
    Users getUsers();

    /**
     * Returns the {@link User} with the specified id
     * 
     * @param userId id of the requested {@link User}
     * @return {@link User} with the specified id
     * @throws ObjectNotFoundException if a user with the specified id does not exist
     */
    User getUser(Long userId) throws ObjectNotFoundException;

    /**
     * Creates a new {@link User}.
     * 
     * @param user
     *  {@link User} to be created
     * @return created user
     * @throws ValidationException if user validation fails
     */
    User createUser(User user) throws ValidationException;

    
    /**
     * Removes the {@link User} with the specified id.
     * 
     * @param userId
     *  id of the {@link User} to be removed
     * @throws ObjectNotFoundException if a user with the specified id does not exist
     */
    void removeUser(Long userId)throws ObjectNotFoundException;

    /**
     * Updates the {@link User} with the specified id.
     * 
     * @param userId
     *  id of the {@link User} to be updated
     * @param user
     *  {@link User} to be updated
     * 
     * @return updated user
     * 
     * @throws ObjectNotFoundException if a user with the specified id does not exist
     */
    User updateUser(Long userId, User user) throws ObjectNotFoundException;

    /**
     * Returns the list of {@link User} {@link Entitlements}.
     * 
     * @param userId
     *  id of the {@link User}
     * @return list of user entitlements wrapped into {@link Entitlements} object
     * @throws ObjectNotFoundException if a user with the specified id does not exist
     */
    Entitlements getUserEntitlements(Long userId) throws ObjectNotFoundException;

    /**
     * Creates an entitlement for the user with a specified id.
     * 
     * @param userId id of the requested user
     * @param entitlement entitlement to be created
     * @return created entitlement
     * @throws ObjectNotFoundException if a user with the specified id does not exist
     */
    Entitlement createUserEntitlement(Long userId, Entitlement entitlement) throws ObjectNotFoundException;

    /**
     * Removes the entitlement for requested user.
     * 
     * @param userId
     *  id of the requested {@link User}
     * @param entitlementId
     *  id of the {@link Entitlement} to be removed
     * @throws ObjectNotFoundException if a user or entitlement with the specified id does not exist
     */
    void removeUserEntitlement(Long userId, Long entitlementId) throws ObjectNotFoundException;

    /**
     * Returns the list of {@link User} {@link Groups}.
     * @param userId
     *  id of the requested {@link User}
     * @return list of groups wrapped into {@link Groups} object
     * @throws ObjectNotFoundException if a user with the specified id does not exist
     */
    Groups getUserGroups(Long userId) throws ObjectNotFoundException;

    /**
     * Returns the list of {@link User}'s {@link AccessTokens}, filtered by scope.
     * 
     * @param userId requested {@link User} id
     * @param scope scope of access tokens
     * 
     * @return list of user access tokens wrapped into {@link AccessTokens}
     * 
     * @throws ObjectNotFoundException if a user with the specified id does not exist
     */
    AccessTokens getUserAccessTokens(Long userId, List scope) throws ObjectNotFoundException;

    /**
     * Updates the user entitelments list.
     * Note that old entitlements are removed and replaced with a new collection.
     * 
     * @param userId requested user id
     * @param entitlements entitelments to be updated
     * 
     * @return updated entitlements
     * 
     * @throws ObjectNotFoundException if a user with the specified id does not exist
     * @throws ValidationException if entitlements validation fails
     */
    Entitlements updateUserEntitlements(Long userId, Entitlements entitlements) throws ObjectNotFoundException, ValidationException;
    
    /**
     * Returns the list of user projects.
     * 
     * @param userId
     *            id of the requested user
     * @return list of projects wrapped into {@link Projects} object
     * @throws ObjectNotFoundException
     *             if a user with the specified id does not exist
     */
    Projects getUserProjects(Long userId) throws ObjectNotFoundException;

}