InstanceUsersApi.java

/***************************************************************************
   Copyright 2015 Emily Estes

   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 net.metanotion.multitenant.adminapp;


import java.util.List;
import javax.inject.Named;

import net.metanotion.authident.UserToken;
import net.metanotion.json.JsonObject;
import net.metanotion.multitenant.TenantAccount;
import net.metanotion.util.Json;
import net.metanotion.util.Service;
import net.metanotion.web.HttpGet;
import net.metanotion.web.HttpPost;
import net.metanotion.web.Param;
import net.metanotion.web.Request;
import net.metanotion.web.RequestReader;

/** This is the API for managing the users within a tenant instance. */
@Named public interface InstanceUsersApi {
	/** Retrieve the JSON description of this API endpoint.
		@param tenantId The tenant instance identifier.
		@return A JSON object describing the API.
		@throws Exception if there is an error retrieving some of the information for the endpoint.
	*/
	@HttpGet @Json public JsonObject usersApi(@Named(Constants.TENANT_ID) long tenantId) throws Exception;

	/** HTTP Response for returning a list of users as a JSON object. */
	public static final class UserList {
		/** The list of users. */
		public final List<TenantAccount> users;
		/** Create a new user list object.
			@param users list of users.
		*/
		public UserList(final List<TenantAccount> users) { this.users = users; }
	}

	/** Retrieve a paginated list of the current users in the tenant instance.
		@param tenantId The tenant instance identifier.
		@param count The maximum number of user accounts to return.
		@param offset The starting offset of the user accounts to return.
		@return A list of user accounts in the tenant instance specified.
		@throws Exception if the operation could not be performed.
	*/
	@HttpGet @Json public UserList listUsers(@Named(Constants.TENANT_ID) long tenantId,
		@Named("count") int count,
		@Named("offset") int offset) throws Exception;

	/** Add a user to a tenant instance.
		@param tenantId The tenant instance identifier.
		@param uid The currently authenticated user.
		@param username The email address of the new user.
		@return The Json object "{ \"success\": true }" if successful.
		@throws Exception if the operation could not be performed.
	*/
	@HttpPost @Json public Object addUser(@Named(Constants.TENANT_ID) long tenantId,
		@Named("uid") @Service UserToken uid,
		@Named(Constants.USERNAME) String username) throws Exception;

	/** Update the roles assigned to a tenant user.
		@param tenantId The tenant instance identifier.
		@param uid The currently authenticated user.
		@param data The updated role set for the userId specified(any roles not in the set will be removed).
		@return The Json object "{ \"success\": true }" if successful.
		@throws Exception if the operation could not be performed.
	*/
	@Request(@Param(name="mime", value="application/json"))
	@HttpPost @Json public Object updateUserRoles(@Named(Constants.TENANT_ID) long tenantId,
		@Named("uid") @Service UserToken uid,
		@Named(Constants.ROLES) @Json @RequestReader TenantAccount data) throws Exception;

	/** Update the list of emails/username a tenant user can use for authentication.
		@param tenantId The tenant instance identifier.
		@param uid The currently authenticated user.
		@param data The updated list of email addresses/usernames the userId specified(any usernames not in the set will be
			removed).
		@return The Json object "{ \"success\": true }" if successful.
		@throws Exception if the operation could not be performed.
	*/
	@Request(@Param(name="mime", value="application/json"))
	@HttpPost @Json public Object updateUserEmails(@Named(Constants.TENANT_ID) long tenantId,
		@Named("uid") @Service UserToken uid,
		@Named(Constants.EMAILS) @Json @RequestReader TenantAccount data) throws Exception;

	/** Delete a user from a tenant instance.
		@param tenantId The tenant instance identifier.
		@param uid The currently authenticated user.
		@param userId The identifier of the user.
		@return The Json object "{ \"success\": true }" if successful.
		@throws Exception if the operation could not be performed.
	*/
	@HttpPost @Json public Object removeUser(@Named(Constants.TENANT_ID) long tenantId,
		@Named("uid") @Service UserToken uid,
		@Named(Constants.USER_ID) long userId) throws Exception;

	/** This class represent an list of email accounts posted to the importUsers method. */
	public static final class AccountList {
		public List<String> accounts;
		/** The no argument constructor so that reflection can create instances and set instance variables directly. */
		public AccountList() { }
		/** Create a new account list object.
			@param accounts List of accounts.
		*/
		public AccountList(final List<String> accounts) { this.accounts = accounts; }
	}

	/** Bulk import a list of users to a tenant instance.
		@param tenantId The tenant instance identifier.
		@param uid The currently authenticated user.
		@param emails A JSON object providing a list of email accounts/usernames for the users to add.
		@return A list of usernames that could not be added.
		@throws Exception if the operation could not be performed. (This is not the same as the operation being unable
			to add any user accounts.)
	*/
	@Request(@Param(name="mime", value="application/json"))
	@HttpPost @Json public AccountList importUsers(@Named(Constants.TENANT_ID) long tenantId,
		@Named("uid") @Service UserToken uid,
		@Named("Emails") @Json @RequestReader AccountList emails) throws Exception;
}