/*******************************************************************************
 * Copyright (c) 2001, 2009 IBM Corporation and others.
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 *
 * Contributors:
 *     IBM Corporation - initial API and implementation
 *     Jens Lukowski/Innoopract - initial renaming/restructuring
 *     
 *******************************************************************************/
package org.eclipse.wst.sse.core.internal.provisional;

import java.io.IOException;
import java.io.InputStream;
import java.io.UnsupportedEncodingException;
import java.util.Enumeration;

import org.eclipse.core.resources.IFile;
import org.eclipse.core.runtime.CoreException;
import org.eclipse.jface.text.IDocument;
import org.eclipse.wst.sse.core.internal.encoding.EncodingRule;
import org.eclipse.wst.sse.core.internal.provisional.exceptions.ResourceAlreadyExists;
import org.eclipse.wst.sse.core.internal.provisional.exceptions.ResourceInUse;
import org.eclipse.wst.sse.core.internal.provisional.text.IStructuredDocument;
import org.eclipse.wst.sse.core.internal.util.URIResolver;

/**
 * <p>
 * Provides APIs for managing (get, release, save, and save as) SSE Structured
 * Models.
 * </p>
 * <p>
 * Structured Models created from an implementor of this interface can be
 * either managed or unmanaged. Managed models are shared using reference
 * counts, so until that count has been decremented to zero, the model will
 * continue to exist in memory. When managed, models can be looked up using
 * their IDs or their IStructuredDocuments, which can be advantageous when
 * building on APIs that aren't specifically designed for SSE (such as those
 * revolving around IDocuments). Unmanaged models offer no such features, and
 * are largely used for tasks where their contents are ephemeral, such as for
 * populating a source viewer with the right syntax colors.
 * </p>
 * <p>
 * There are two types of access used when retrieving a model from the model
 * manager: read or edit. The contents of the model can be modified regardless
 * of which access type is used, but any client who gets a model for edit is
 * explicitly declaring that they are interested in saving those changed
 * contents. The edit and read reference counts are visible to everyone, as
 * are convenience methods for determining whether a managed model is shared
 * among multiple clients accessing it for read or edit.
 * </p>
 * <p>
 * Managed models whose contents are "dirty" with read and edit counts above
 * zero will be reverted to the on-disk content if the edit count drops to
 * zero while the read count remains above zero.
 * </p>
 * <p>
 * 
 * @noimplement This interface is not intended to be implemented by clients.
 *              </p>
 *              <p>
 * @see StructuredModelManger</p>
 */
public interface IModelManager {

	/**
	 * A fixed ID used for models which were created as duplicates of existing
	 * models
	 */
	public final static String DUPLICATED_MODEL = "org.eclipse.wst.sse.core.IModelManager.DUPLICATED_MODEL"; //$NON-NLS-1$

	/**
	 * A fixed ID used for unmanaged models
	 */
	public final static String UNMANAGED_MODEL = "org.eclipse.wst.sse.core.IModelManager.UNMANAGED_MODEL"; //$NON-NLS-1$

	/**
	 * Calculate id provides a common way to determine the id from the input
	 * ... needed to get and save the model. It is a simple class utility, but
	 * is an instance method so can be accessed via interface.
	 */
	public String calculateId(IFile file);

	/**
	 * Copies a model with the old id 
	 * @param oldId - the old model's ID
	 * @param newId - the new model's ID
	 * @return the new model
	 * @throws ResourceInUse if the given new ID is already in use by a managed model
	 */
	IStructuredModel copyModelForEdit(String oldId, String newId) throws ResourceInUse;

	/**
	 * Creates a new, but empty, unmanaged model of the same kind as the one
	 * given. For a managed model with the same contents, use "copy".
	 * 
	 * @param model
	 * @return
	 * @throws IOException
	 */
	public IStructuredModel createNewInstance(IStructuredModel model) throws IOException;

	/**
	 * Factory method, since a proper IStructuredDocument must have a proper
	 * parser assigned. If the resource does already exist, then
	 * createStructuredDocumentFor is the right API to use.
	 * 
	 * @param iFile
	 * @return
	 * @throws ResourceAlreadyExists
	 *             if the IFile already exists
	 * @throws IOException
	 * @throws CoreException
	 */
	IStructuredDocument createNewStructuredDocumentFor(IFile iFile) throws ResourceAlreadyExists, IOException, CoreException;

	/**
	 * Factory method, since a proper IStructuredDocument must have a proper
	 * parser assigned. Note: clients should verify IFile exists before using
	 * this method. If this IFile does not exist, then
	 * createNewStructuredDocument is the correct API to use.
	 */
	IStructuredDocument createStructuredDocumentFor(IFile iFile) throws IOException, CoreException;

	/**
	 * Convenience method, since a proper IStructuredDocument must have a
	 * proper parser assigned. It should only be used when an empty
	 * structuredDocument is needed. Otherwise, use IFile form.
	 * 
	 * @param contentTypeId
	 * @return a structured document with the correct parsing setup for the
	 *         given content type, or null if one could not be created
	 */
	IStructuredDocument createStructuredDocumentFor(String contentTypeId);

	/**
	 * @deprecated -- I marked as deprecated to discouage use of this method.
	 *             It does not really work for JSP fragments, since JSP
	 *             Fragments need an IFile to correctly look up the content
	 *             settings. Use IFile form instead. Note: some confustion
	 *             with it and the form for HTPP encoding, so once a null arg
	 *             is allowed in that API ... we can remove this one. (after
	 *             verifying again with Tom/Linksbuild)
	 */
	IStructuredDocument createStructuredDocumentFor(String filename, InputStream inputStream, URIResolver resolver) throws IOException;

	/**
	 * @deprecated - clients should convert the InputStream into text themselves
	 *             and then use the version of this method taking a String for its
	 *             content
	 */
	IStructuredDocument createStructuredDocumentFor(String filename, InputStream inputStream, URIResolver resolver, String ianaEncodingName) throws IOException;

	/**
	 * @param filename
	 * @param content
	 * @param resolver
	 * @return a structured document with the correct parsing setup for the
	 *         given filename, or null if one could not be created
	 * @throws IOException
	 */
	IStructuredDocument createStructuredDocumentFor(String filename, String content, URIResolver resolver) throws IOException;

	/**
	 * Creates and returns an unmanaged model populated with the given IFile's
	 * contents
	 * 
	 * @param iFile
	 * @return a structured model, or null if one could not be created
	 * @throws IOException
	 * @throws CoreException
	 */
	IStructuredModel createUnManagedStructuredModelFor(IFile iFile) throws IOException, CoreException;

	/**
	 * Convenience method. It depends on the loader's newModel method to return
	 * an appropriate StrucuturedModel appropriately initialized.
	 * 
	 * @param contentTypeId
	 * @return a structured model for the given content type, or null if one could not be created
	 */
	IStructuredModel createUnManagedStructuredModelFor(String contentTypeId);

	/**
	 * @deprecated
	 */
	IStructuredModel createUnManagedStructuredModelFor(String contentTypeId, URIResolver resolver);

	/**
	 * Note: callers of this method must still release the model when finished.
	 * 
	 * @param document
	 * @return the structured model containing the give document, incrementing
	 *         its edit count, or null if there is not a model corresponding
	 *         to this document.
	 */
	IStructuredModel getExistingModelForEdit(IDocument document);

	/**
	 * @param file
	 * @return the structured model for the given file, incrementing its edit
	 *         count, or null if one does not already exist for this file.
	 */
	IStructuredModel getExistingModelForEdit(IFile file);

	/**
	 * @param id
	 * @return the structured model with the given ID, incrementing its edit
	 *         count, or null if one does not already exist for this ID
	 */
	public IStructuredModel getExistingModelForEdit(Object id);

	/**
	 * Note: callers of this method must still release the model when finished.
	 * 
	 * @param document
	 * @return the structured model containing the give document, incrementing
	 *         its read count, or null if there is not a model corresponding
	 *         to this document.
	 */
	IStructuredModel getExistingModelForRead(IDocument document);

	/**
	 * @param file
	 * @return the structured model for the given file, incrementing its read
	 *         count, or null if one does not already exist for this file.
	 */
	public IStructuredModel getExistingModelForRead(IFile iFile);

	/**
	 * @param id
	 * @return the structured model with the given ID, incrementing its edit
	 *         count, or null if one does not already exist for this ID
	 */
	public IStructuredModel getExistingModelForRead(Object id);

	/**
	 * @deprecated - internal information
	 */
	public Enumeration getExistingModelIds();

	/**
	 * Returns a structured model for the given file. If one does not already
	 * exists, one will be created with an edit count of 1. If one already
	 * exists, its edit count will be incremented before it is returned.
	 * 
	 * @param iFile
	 * @return a structured model for the given file, or null if one could not
	 *         be found or created
	 */
	public IStructuredModel getModelForEdit(IFile iFile) throws IOException, CoreException;

	/**
	 * @deprecated - encoding is handled automatically based on the file's
	 *             contents or user preferences
	 */
	public IStructuredModel getModelForEdit(IFile iFile, EncodingRule encodingRule) throws UnsupportedEncodingException, IOException, CoreException;

	/**
	 * @deprecated - Encoding and the line delimiter used are handled
	 *             automatically based on the file's contents or user
	 *             preferences.
	 */
	public IStructuredModel getModelForEdit(IFile iFile, String encoding, String lineDelimiter) throws UnsupportedEncodingException, IOException, CoreException;

	/**
	 * Returns a structured model for the given document. If one does not
	 * already exists, one will be created with an edit count of 1. If one
	 * already exists, its edit count will be incremented before it is
	 * returned. This method is intended only to interact with documents
	 * contained within File Buffers.
	 * 
	 * @param textFileBufferDocument
	 * @return a structured model for the given document, or null if there is
	 *         insufficient information known about the document instance to
	 *         do so
	 */
	public IStructuredModel getModelForEdit(IStructuredDocument textFileBufferDocument);

	/*
	 * @deprecated - a URI resolver should be automatically created when
	 *             needed
	 */
	public IStructuredModel getModelForEdit(String id, InputStream inStream, URIResolver resolver) throws UnsupportedEncodingException, IOException;

	/**
	 * Returns a structured model for the given file. If one does not already
	 * exists, one will be created with a read count of 1. If one already
	 * exists, its read count will be incremented before it is returned.
	 * 
	 * @param iFile
	 * @return a structured model for the given file, or null if one could not
	 *         be found or created
	 */
	public IStructuredModel getModelForRead(IFile iFile) throws IOException, CoreException;

	/**
	 * @deprecated - encoding is handled automatically based on the file's
	 *             contents or user preferences
	 */
	public IStructuredModel getModelForRead(IFile iFile, EncodingRule encodingRule) throws UnsupportedEncodingException, IOException, CoreException;

	/**
	 * @deprecated - Encoding and the line delimiter used are handled
	 *             automatically based on the file's contents or user
	 *             preferences.
	 */
	public IStructuredModel getModelForRead(IFile iFile, String encoding, String lineDelimiter) throws UnsupportedEncodingException, IOException, CoreException;

	/**
	 * Returns a structured model for the given document. If one does not
	 * already exists, one will be created with a read count of 1. If one
	 * already exists, its read count will be incremented before it is
	 * returned. This method is intended only to interact with documents
	 * contained within File Buffers.
	 * 
	 * @param textFileBufferDocument
	 * @return a structured model for the given document, or null if there is
	 *         insufficient information known about the document instance to
	 *         do so
	 */
	public IStructuredModel getModelForRead(IStructuredDocument textFileBufferDocument);

	/**
	 * @deprecated - a URI resolver should be automatically created when
	 *             needed
	 */
	public IStructuredModel getModelForRead(String filename, InputStream inStream, URIResolver resolver) throws UnsupportedEncodingException, IOException;

	/**
	 * This method will not create a new model if it already exists ... if
	 * force is false. The idea is that a client should call this method once
	 * with force set to false. If the exception is thrown, then prompt client
	 * if they want to overwrite.
	 */
	IStructuredModel getNewModelForEdit(IFile iFile, boolean force) throws ResourceAlreadyExists, ResourceInUse, IOException, CoreException;

	/**
	 * This method will not create a new model if it already exists ... if
	 * force is false. The idea is that a client should call this method once
	 * with force set to false. If the exception is thrown, then prompt client
	 * if they want to overwrite.
	 */
	IStructuredModel getNewModelForRead(IFile iFile, boolean force) throws ResourceAlreadyExists, ResourceInUse, IOException, CoreException;

	/**
	 * This function returns the reference count of underlying model.
	 * 
	 * @param id
	 *            Object The id of the model TODO: try to refine the design
	 *            not to use this function
	 * @deprecated - internal information that can be obtained from the model itself
	 */
	int getReferenceCount(Object id);

	/**
	 * This function returns the reference count of underlying model.
	 * 
	 * @param id
	 *            Object The id of the model TODO: try to refine the design
	 *            not to use this function
	 * @deprecated - internal information that can be obtained from the model itself
	 */
	int getReferenceCountForEdit(Object id);

	/**
	 * This function returns the reference count of underlying model.
	 * 
	 * @param id
	 *            Object The id of the model TODO: try to refine the design
	 *            not to use this function
	 * @deprecated - internal information that can be obtained from the model itself
	 */
	int getReferenceCountForRead(Object id);

	/**
	 * This function returns true if there are other references to the
	 * underlying model.
	 * 
	 * @param id
	 *            Object The id of the model
	 */
	boolean isShared(Object id);

	/**
	 * This function returns true if there are other references to the
	 * underlying model.
	 * 
	 * @param id
	 *            Object The id of the model
	 */
	boolean isSharedForEdit(Object id);

	/**
	 * This function returns true if there are other references to the
	 * underlying model.
	 * 
	 * @param id
	 *            Object The id of the model
	 */
	boolean isSharedForRead(Object id);

	/**
	 * @deprecated - not granular enough
	 * 
	 * This method can be called to determine if the model manager is within a
	 * "aboutToChange" and "changed" sequence.
	 */
	public boolean isStateChanging();

	/**
	 * This method changes the id of the model. TODO: try to refine the design
	 * not to use this function
	 * 
	 * @deprecated
	 */
	void moveModel(Object oldId, Object newId);

	/**
	 * This method can be called when the content type of a model changes. It's
	 * assumed the contentType has already been changed, and this method uses
	 * the text of the old one, to repopulate the text of the new one. In
	 * theory, the actual instance could change, (e.g. using 'saveAs' to go
	 * from xml to dtd), but in practice, the intent of this API is to return
	 * the same instance, just using different handlers, adapter factories,
	 * etc.
	 */
	IStructuredModel reinitialize(IStructuredModel model) throws IOException;

	/**
	 * This is similar to the getModel method, except this method does not use
	 * the cached version, but forces the cached version to be replaced with a
	 * fresh, unchanged version. Note: this method does not change any
	 * reference counts. Also, if there is not already a cached version of the
	 * model, then this call is essentially ignored (that is, it does not put
	 * a model in the cache) and returns null.
	 * 
	 * @deprecated
	 */
	IStructuredModel reloadModel(Object id, InputStream inStream) throws UnsupportedEncodingException;

	void saveStructuredDocument(IStructuredDocument structuredDocument, IFile iFile) throws UnsupportedEncodingException, IOException, CoreException;

}