InstanceAdminsApi.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.sql.Connection;
import java.util.List;
import javax.inject.Named;

import net.metanotion.authident.UserToken;
import net.metanotion.json.JsonObject;
import net.metanotion.util.Json;
import net.metanotion.util.SecureString;
import net.metanotion.util.Service;
import net.metanotion.web.HttpGet;
import net.metanotion.web.HttpPost;

/** This is the API for managing the users within the multitenant administrative control panel who are authorized to
perform administrative actions on the tenant instance. */
@Named public interface InstanceAdminsApi {
	/** 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 adminsApi(@Named(Constants.TENANT_ID) long tenantId) throws Exception;

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

	/** Retrieve a list of the administrator accounts for the provided instance.
		@param conn Database connection for admin instance.
		@param tenantId The tenant instance identifier.
		@return A list of all of the current tenant instance administrator accounts.
		@throws Exception if the operation could not be performed.
	*/
	@HttpGet @Json public AdminList listAdmins(@Named("conn") Connection conn,
		@Named(Constants.TENANT_ID) long tenantId) throws Exception;

	/** Add a new administrator to a tenant instance.
		@param conn Database connection for admin instance.
		@param tenantId The tenant instance identifier.
		@param uid The currently authenticated user.
		@param password The password for the currently authenticated user (To re-check to verify the operation.)
		@param email The email address of the new administrator.
		@return The information for the new administrator.
		@throws Exception if the operation could not be performed.
	*/
	@HttpPost @Json public AdminAccount addAdmin(@Named("conn") Connection conn,
		@Named(Constants.TENANT_ID) long tenantId,
		@Named("uid") @Service UserToken uid,
		@Named(Constants.PASSWORD) SecureString password,
		@Named(Constants.EMAIL) String email) throws Exception;

	/** Delete an administrator from a tenant instance.
		@param conn Database connection for admin instance.
		@param tenantId The tenant instance identifier.
		@param uid The currently authenticated user.
		@param password The password for the currently authenticated user (To re-check to verify the operation.)
		@param email The email address of the administrator to delete.
		@return The Json object "{ \"success\": true }" if successful.
		@throws Exception if the operation could not be performed.
	*/
	@HttpPost @Json public Object removeAdmin(@Named("conn") Connection conn,
		@Named(Constants.TENANT_ID) long tenantId,
		@Named("uid") @Service UserToken uid,
		@Named(Constants.PASSWORD) SecureString password,
		@Named(Constants.EMAIL) String email) throws Exception;
}