TenantExport.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;


import java.io.InputStream;
import java.util.List;
import net.metanotion.web.HttpValues;

/** This interface, along with TenantUsers, is designed to be provided by tenant Instance implementations via their
lookupInterface method to allow an administrative app to control the instance. Unlike TenantUsers, since these
operations are likely to be very application specific, only the interface is provided and no default implementation. */
public interface TenantExport {
	/** This class represents information about an export file the tenant instance is storing. */
	public static final class Entry {
		public long fileId;
		public String filename;
		public String description;
		public int offset;
	}

	/** This class represents the status response of pending export operations. */
	public static final class Status {
		public final boolean blocking;
		public final List<String> messages;
		/** Create a new export status object.
			@param blocking True if attempts to start another "blocking" operation will fail.
			@param messages A list of messages about the progress of the current blocking operation (if there are any messages).
		*/
		public Status(final boolean blocking, final List<String> messages) {
			this.blocking = blocking;
			this.messages = messages;
		}
	}

	/** Have this instance start the process of generating an export.
		@return The status of any pending operations.
	*/
	public Status initiateExport();

	/** Return the current status of any potentially "blocking" export operations. The potentially blocking operations
	are: {@link #resetInstance()}, {@link #initiateImport(long)}, {@link #initiateExport()}.
		@return The status of any pending operations.
	*/
	public Status status();

	/** Have this instance copy an externally supplied export file into it's backup set.
		@param filename The original filename of the file.
		@param mimeType The mime type of the file.
		@param in An input stream to read the file from.
	*/
	public void storeExternalExport(String filename, String mimeType, InputStream in);

	/** Reset this instance to some "clean" initial state.
		@return The status of any pending operations.
	*/
	public Status resetInstance();

	/** Retrieve a list of export files the tenant instance is currently storing.
		@param offset The offset to start listing the files in storage.
		@param count The maximum number of files to retrieve in this list.
		@return A list of exports the tenant instance is storing.
	*/
	public List<Entry> listExports(int offset, int count);

	/** Remove the export file identified from server storage.
		@param fileId The identifier of the export file to remove.
	*/
	public void deleteExport(long fileId);

	/** Retrieve the export file identified for transport over HTTP.
		@param fileId The identifier of hte export file to download.
		@return An Http response representing the file.
	*/
	public HttpValues getExport(long fileId);

	/** Restore the tenant instance using the export file identified. This operation will potentially also reset the
		tenant instance before starting the import. The appropriate semantics are dependent on the instance to
		determine.
		@param fileId The identifier of the file to use to import into the instance.
		@return The status of any pending operations.
	*/
	public Status initiateImport(long fileId);
}