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

/** This is the API for managing per tenant instance export controls. */
@Named public interface InstanceExportApi {
	/** 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 exportsApi(@Named(Constants.TENANT_ID) long tenantId) throws Exception;

	/** HTTP Response for returning a list of export entries as a JSON object. */
	public static final class EntryList {
		/** The list of tenant export entries. */
		public final List<TenantExport.Entry> entries;
		/** Create a new entry list object.
			@param entries list of export entries.
		*/
		public EntryList(final List<TenantExport.Entry> entries) { this.entries = entries; }
	}

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

	/** Retrieve the status of any pending tenant export related operations.
		@param tenantId The tenant instance identifier.
		@return The status of any pending tenant instance export operations. If the "blocking" flag is set true,
			clients should not initiate exports, imports, or resets.
		@throws Exception if the operation could not be performed.
	*/
	@HttpGet @Json public TenantExport.Status exportStatusPoll(@Named(Constants.TENANT_ID) long tenantId) throws Exception;

	/** Request that a tenant instance begin the process of generating an export of the tenant's state.
		@param tenantId The tenant instance identifier.
		@return The status of any pending tenant instance export operations. If the "blocking" flag is set true,
			clients should not initiate exports, imports, or resets.
		@throws Exception if the operation could not be performed.
	*/
	@HttpPost @Json public TenantExport.Status startExport(@Named(Constants.TENANT_ID) long tenantId) throws Exception;

	/** Request that a tenant instance begin the process of reseting it's state to a "clean slate". The interpretation
			of "clean slate" is beyond the definition of the admin web app.
		@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.)
		@return The status of any pending tenant instance export operations. If the "blocking" flag is set true,
			clients should not initiate exports, imports, or resets.
		@throws Exception if the operation could not be performed.
	*/
	@HttpPost @Json public TenantExport.Status resetInstance(@Named(Constants.TENANT_ID) long tenantId,
		@Named("uid") @Service UserToken uid,
		@Named(Constants.PASSWORD) SecureString password) throws Exception;

	/** Upload an export file to store in the tenant instance.
		@param tenantId The tenant instance identifier.
		@param responseTag The identifier to use for notifications in the response for the iframeFormManager.js lib.
		@param file The file to store.
		@return A web page with a JS payload notifying the iframeFormManager.js lib that the file was uploaded successfully.
		@throws Exception if the operation could not be performed.
	*/
	@HttpPost public String uploadExport(@Named(Constants.TENANT_ID) long tenantId,
		@Named(Constants.FILE_RESPONSE_ID) String responseTag,
		@Named("import") FileUpload file) throws Exception;

	/** Download an export file from a tenant instance.
		@param tenantId The tenant instance identifier.
		@param exportId The instance provided identifier for the export file to download.
		@return The HTTP response to send the file.
		@throws Exception if the operation could not be performed.
	*/
	@HttpGet public HttpValues getExport(@Named(Constants.TENANT_ID) long tenantId,
		@Named(Constants.FILE_ID) long exportId) throws Exception;

	/** Request that a tenant instance begin the process of "clearing" itself and using the specified export file to
		restore itself to the state specified by the export.
		@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 exportId The instance provided identifier for the export file to restore from.
		@return The status of any pending tenant instance export operations. If the "blocking" flag is set true,
			clients should not initiate exports, imports, or resets.
		@throws Exception if the operation could not be performed.
	*/
	@HttpPost @Json public TenantExport.Status startImport(@Named(Constants.TENANT_ID) long tenantId,
		@Named("uid") @Service UserToken uid,
		@Named(Constants.PASSWORD) SecureString password,
		@Named(Constants.FILE_ID) long exportId) throws Exception;

	/** Remove an export file from tenant instance storage.
		@param tenantId The tenant instance identifier.
		@param exportId The instance provided identifier for the export file to delete.
		@return The Json object "{ \"success\": true }" if successful.
		@throws Exception if the operation could not be performed.
	*/
	@HttpPost @Json public Object removeExport(@Named(Constants.TENANT_ID) long tenantId,
		@Named(Constants.FILE_ID) long exportId) throws Exception;
}