TenantsApi.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.util.Json;
import net.metanotion.util.SecureString;
import net.metanotion.util.Service;
import net.metanotion.web.HttpGet;
import net.metanotion.web.HttpPost;

/** This interface represents the HTTP API for controlling and access tenant instances. */
@Named public interface TenantsApi {
	/** Retrieve the JSON description of this API endpoint.
		@return A JSON object describing the API.
	*/
	@HttpGet @Json public Object api();

	/** HTTP Response for returning a list of instances as a JSON object. */
	public final class InstanceList {
		/** The list of instances. */
		public final List<InstanceInfo> instances;
		/** Create a new instance list object.
			@param instances The list of instances.
		*/
		public InstanceList(final List<InstanceInfo> instances) { this.instances = instances; }
	}

	/** Retrieve a list of all tenant isntances a user is either an administrator or owner of.
		@param uid The currently authenticated user.
		@return A list of the tenant instances this user has access to.
		@throws Exception if the operation could not be performed.
	*/
	@HttpGet @Json public InstanceList listInstances(@Service @Named("uid") UserToken uid) throws Exception;

	/** Create a new tenant instance.
		@param uid The currently authenticated user. This user will be the tenant instance owner.
		@param title The admin web app "human friendly" name the tenant instance will be identified by.
		@return The instance info for the newly created tenant.
		@throws Exception if the instance could not be created.
	*/
	@HttpPost @Json public InstanceInfo createInstance(@Service @Named("uid") UserToken uid,
		@Named(Constants.TITLE) String title) throws Exception;

	/** Delete an instance.
		@param uid The currently authenticated user.
		@param password The password for the currently authenticated user (To re-check to verify the operation.)
		@param tenantId The tenant instance identifier.
		@return The Json object "{ \"success\": true }" if successful.
		@throws Exception if the operation could not be performed.
	*/
	@HttpPost @Json public Object removeInstance(@Service @Named("uid") UserToken uid,
		@Named(Constants.PASSWORD) SecureString password,
		@Named(Constants.TENANT_ID) long tenantId) throws Exception;

	/** Reassign the owner of a tenant instance.
		@param uid The currently authenticated user.
		@param password The password for the currently authenticated user (To re-check to verify the operation.)
		@param tenantId The tenant instance identifier.
		@param newOwnerEmail The email address of the new tenant owner.
		@return A list of either 0 or 1 instances. If 0 instances, then the current user is no longer able to access
			the tenant instance as an admin, if an instance is in the list, it is the updated information for the
			instance.
		@throws Exception if the operation could not be performed. Reasons include the authentication check fails, uid
			doesn't match the tenant instance owner, there is no user account associated with the newOwnerEmail, the
			title clashes with the titles in the new owner's tenant list.
	*/
	@HttpPost @Json public InstanceList reassignOwner(@Named("uid") @Service UserToken uid,
		@Named(Constants.PASSWORD) SecureString password,
		@Named(Constants.TENANT_ID) long tenantId,
		@Named(Constants.NEW_OWNER_EMAIL) String newOwnerEmail) throws Exception;

	/** Update the title of the tenant instance.
		@param uid The currently authenticated user.
		@param tenantId The tenant instance identifier.
		@param title The new title of the instance.
		@return The instance info for the updated tenant.
		@throws Exception if the operation could not be performed.
	*/
	@HttpPost @Json public InstanceInfo updateTitle(@Service @Named("uid") UserToken uid,
		@Named(Constants.TENANT_ID) long tenantId,
		@Named(Constants.TITLE) String title) throws Exception;

	/** Pause the specified instance from being available. Note: at the moment, this will also remove the instance from
		the pool of instances that can be managed using tenant instance API's like
		{@link net.metanotion.multitenant.TenantExport} and {@link net.metanotion.multitenant.TenantUsers}.
		@param uid The currently authenticated user.
		@param tenantId The tenant instance identifier.
		@return The instance info for the updated tenant.
		@throws Exception if the operation could not be performed.
	*/
	@HttpPost @Json public InstanceInfo stopInstance(@Named("uid") @Service UserToken uid,
		@Named(Constants.TENANT_ID) long tenantId) throws Exception;

	/** Resume the availability of the specified instance.
		@param uid The currently authenticated user.
		@param tenantId The tenant instance identifier.
		@return The instance info for the updated tenant.
		@throws Exception if the operation could not be performed.
	*/
	@HttpPost @Json public InstanceInfo startInstance(@Named("uid") @Service UserToken uid,
		@Named(Constants.TENANT_ID) long tenantId) throws Exception;
}