/*******************************************************************************
 * Copyright (c) 2006, 2012 Oracle. 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:
 *     Oracle - initial API and implementation
 ******************************************************************************/
package org.eclipse.jpt.jpa.core;

import org.eclipse.core.resources.IFile;
import org.eclipse.core.resources.IProject;
import org.eclipse.core.resources.IResourceDelta;
import org.eclipse.core.runtime.IPath;
import org.eclipse.jdt.core.ElementChangedEvent;
import org.eclipse.jdt.core.IJavaProject;
import org.eclipse.jpt.common.core.resource.java.JavaResourceAbstractType;
import org.eclipse.jpt.common.core.resource.java.JavaResourceCompilationUnit;
import org.eclipse.jpt.common.core.resource.java.JavaResourcePackage;
import org.eclipse.jpt.common.core.resource.java.JavaResourcePackageFragmentRoot;
import org.eclipse.jpt.common.core.resource.java.JavaResourceTypeCache;
import org.eclipse.jpt.common.core.utility.command.JobCommand;
import org.eclipse.jpt.common.utility.ExceptionHandler;
import org.eclipse.jpt.common.utility.command.ExtendedCommandExecutor;
import org.eclipse.jpt.jpa.core.context.JpaRootContextNode;
import org.eclipse.jpt.jpa.core.resource.xml.JpaXmlResource;
import org.eclipse.jpt.jpa.db.Catalog;
import org.eclipse.jpt.jpa.db.ConnectionProfile;
import org.eclipse.jpt.jpa.db.Schema;
import org.eclipse.jpt.jpa.db.SchemaContainer;
import org.eclipse.wst.validation.internal.provisional.core.IMessage;
import org.eclipse.wst.validation.internal.provisional.core.IReporter;

/**
 * A JPA project is associated with an {@link IProject Eclipse project}
 * (and its corresponding  {@link IJavaProject Java project}).
 * It holds the <em>resource</em> model that corresponds to the 
 * various JPA-related resources (the <code>persistence.xml</code> file, its
 * mapping files [<code>orm.xml</code>], and the Java source files). It also
 * holds the <em>context</em> model that represents
 * the JPA metadata, as derived from spec-defined defaults, Java source code
 * annotations, and XML descriptors.
 * <p>
 * To retrieve the JPA project corresponding to an Eclipse project:
 * <pre>
 * IProject project = ResourcesPlugin.getWorkspace().getRoot().getProject("Foo Project");
 * JpaProject jpaProject = (JpaProject) project.getAdapter(JpaProject.class);
 * </pre>
 * This is a non-blocking call; and as a result it will return <code>null</code>
 * if the JPA project is currently under construction. Use a {@link
 * Reference JPA project reference} to retrieve a JPA project in a blocking
 * fashion that will return a JPA project once it has been constructed.
 * <p>
 * See <code>org.eclipse.jpt.jpa.core/plugin.xml</code>.
 * <p>
 * Provisional API: This interface is part of an interim API that is still
 * under development and expected to change significantly before reaching
 * stability. It is available at this early stage to solicit feedback from
 * pioneering adopters on the understanding that any code that uses this API
 * will almost certainly be broken (repeatedly) as the API evolves.
 * 
 * @version 3.0
 * @since 2.0
 * 
 * @see Reference
 * @see org.eclipse.jpt.jpa.core.internal.ProjectAdapterFactory
 */
public interface JpaProject
	extends JpaNode
{

	// ********** general **********

	/**
	 * Return the JPA project manager.
	 */
	Manager getManager();

	/**
	 * Return the JPA project's name, which is the same as the associated
	 * Eclipse project's name.
	 */
	String getName();

	/**
	 * Return the Eclipse project associated with the JPA project.
	 */
	IProject getProject();

	/**
	 * Return the Java project associated with the JPA project.
	 */
	IJavaProject getJavaProject();

	/**
	 * Return the vendor-specific JPA platform that builds the JPA project
	 * and its contents.
	 */
	JpaPlatform getJpaPlatform();

	/**
	 * Return the root of the JPA project's context model.
	 */
	JpaRootContextNode getRootContextNode();

	/**
	 * The JPA project has been removed from the JPA model. Clean up any
	 * hooks to external resources etc.
	 */
	void dispose();


	// ********** JPA files **********

	/** 
	 * ID string used when the JPA project's collection of JPA files changes.
	 * @see #addCollectionChangeListener(String, org.eclipse.jpt.common.utility.model.listener.CollectionChangeListener)
	 */
	String JPA_FILES_COLLECTION = "jpaFiles"; //$NON-NLS-1$

	/**
	 * Return the JPA project's JPA files.
	 */
	Iterable<JpaFile> getJpaFiles();

	/**
	 * Return the size of the JPA project's JPA files.
	 */
	int getJpaFilesSize();

	/**
	 * Return the JPA file corresponding to the specified file.
	 * Return null if there is no JPA file associated with the specified file.
	 */
	JpaFile getJpaFile(IFile file);


	// ********** external Java resource compilation units **********

	/** 
	 * ID string used when the JPA project's collection of external Java
	 * resource compilation units changes.
	 * @see #addCollectionChangeListener(String, org.eclipse.jpt.common.utility.model.listener.CollectionChangeListener)
	 */
	String EXTERNAL_JAVA_RESOURCE_COMPILATION_UNITS_COLLECTION = "externalJavaResourceCompilationUnits"; //$NON-NLS-1$

	/**
	 * Return the JPA project's external Java resource compilation units.
	 */
	Iterable<JavaResourceCompilationUnit> getExternalJavaResourceCompilationUnits();

	/**
	 * Return the size of the JPA project's external Java resource compilation units.
	 */
	int getExternalJavaResourceCompilationUnitsSize();


	// ********** external Java resource persistent types **********

	/**
	 * Return the JPA project's external Java resource type cache.
	 */
	JavaResourceTypeCache getExternalJavaResourceTypeCache();


	// ********** XML resources **********
	
	/**
	 * Return the XML resource model corresponding to the file with runtime path
	 * <code>META-INF/persistence.xml</code> if that file has the persistence content type
	 * (<code>"org.eclipse.jpt.jpa.core.content.persistence"</code>).
	 * 
	 * @see JptJpaCorePlugin#DEFAULT_PERSISTENCE_XML_RUNTIME_PATH
	 * @see JptJpaCorePlugin#PERSISTENCE_XML_CONTENT_TYPE
	 */
	JpaXmlResource getPersistenceXmlResource();
	
	/**
	 * Return the XML resource model corresponding to the file with the specified
	 * runtime path if that file has the mapping file content type
	 * (<code>"org.eclipse.jpt.jpa.core.content.mappingFile"</code>)
	 * 
	 * @see JptJpaCorePlugin#MAPPING_FILE_CONTENT_TYPE
	 */
	JpaXmlResource getMappingFileXmlResource(IPath runtimePath);

	/**
	 * Return the XML resource model corresponding to the file
	 * <code>META-INF/orm.xml</code> if that file has the mapping file content type.
	 * 
	 * @see JptJpaCorePlugin#DEFAULT_ORM_XML_RUNTIME_PATH
	 */
	JpaXmlResource getDefaultOrmXmlResource();
	
	
	// ********** Java resources **********

	/**
	 * Return the names of the JPA project's annotated Java classes
	 * (ignoring classes in JARs referenced in the <code>persistence.xml</code>).
	 */
	Iterable<String> getAnnotatedJavaSourceClassNames();
	
	/**
	 * Return only the names of those valid <em>mapped</em> (i.e. annotated with
	 * <code>@Entity</code>, <code>@Embeddable</code>, etc.) Java resource
	 * persistent types that are directly part of the JPA project, ignoring
	 * those in JARs referenced in <code>persistence.xml</code>.
	 */
	Iterable<String> getMappedJavaSourceClassNames();

	Iterable<String> getTypeMappingAnnotationNames();

	/**
	 * Return the Java resource type for the fully qualified type name.
	 * Return null if invalid or absent.
	 */
	JavaResourceAbstractType getJavaResourceType(String typeName);

	/**
	 * Return the {@link JavaResourceAbstractType} with the fully qualified type name and kind.
	 * Return null if invalid or absent or if the kind does not match.
	 */
	JavaResourceAbstractType getJavaResourceType(String typeName, JavaResourceAbstractType.Kind kind);

	/**
	 * Return the Java resource package for the specified package.
	 * Return null if invalid or absent.
	 */
	JavaResourcePackage getJavaResourcePackage(String packageName);

	/**
	 * Return the Java resource packages for the project.
	 * Return null if invalid or absent.
	 */
	Iterable<JavaResourcePackage> getJavaResourcePackages();

	/**
	 * Return the Java resource package fragement root for the specified JAR.
	 * Return null if absent.
	 */
	JavaResourcePackageFragmentRoot getJavaResourcePackageFragmentRoot(String jarFileName);

	/**
	 * Return the JPA project's JPA files for jars.
	 */
	Iterable<JpaFile> getJarJpaFiles();


	// ********** external events **********

	/**
	 * Synchronize the JPA project with the specified project resource
	 * delta, watching for added and removed files in particular.
	 */
	void projectChanged(IResourceDelta delta);

	/**
	 * Synchronize the JPA project with the specified Java change.
	 */
	void javaElementChanged(ElementChangedEvent event);


	// ********** synchronize context model with resource model **********

	/**
	 * Should only be used by [incorrectly written] tests....
	 * [The tests would be more valid if they modified the source code
	 * directly allowing resource/Java change events to <em>synchronize</em>
	 * the context model....]
	 */
	void synchronizeContextModel();


	// ********** utility **********

	/**
	 * Return an {@link IFile} that best represents the given runtime location
	 */
	IFile getPlatformFile(IPath runtimePath);


	// ********** validation **********

	/**
	 * Return JPA project's validation messages.
	 */
	Iterable<IMessage> getValidationMessages(IReporter reporter);


	// ********** database **********

	/**
	 * Return the data source the JPA project is mapped to.
	 */
	JpaDataSource getDataSource();

	/**
	 * Return the JPA project's connection.
	 * The connection profile is null if the JPA project's connection profile
	 * name does not match the name of a DTP connection profile.
	 */
	ConnectionProfile getConnectionProfile();

	/**
	 * Return the JPA project's default database schema container;
	 * which is either the JPA project's default catalog or the JPA project's
	 * database, depending on how the DTP model is implemented.
	 */
	SchemaContainer getDefaultDbSchemaContainer();

	/**
	 * Return the JPA project's default catalog; which is either the user
	 * override catalog or the database's default catalog.
	 */
	String getDefaultCatalog();

	/**
	 * Return the JPA project's default database catalog.
	 * @see #getDefaultCatalog()
	 */
	Catalog getDefaultDbCatalog();

	/**
	 * Return the JPA project's default schema; which can be one of the
	 * following:<ul>
	 * <li>the user override schema
	 * <li>the default catalog's default schema
	 * <li>the database's default schema (if catalogs are not supported)
	 * </ul>
	 */
	String getDefaultSchema();

	/**
	 * Return the JPA project's default database schema.
	 * @see #getDefaultSchema()
	 * @see #getDefaultDbSchemaContainer()
	 */
	Schema getDefaultDbSchema();


	// ********** user override default catalog **********

	/** 
	 * ID string used when the JPA project's user override default catalog changes.
	 * @see #addPropertyChangeListener(String, org.eclipse.jpt.common.utility.model.listener.PropertyChangeListener)
	 */
	String USER_OVERRIDE_DEFAULT_CATALOG_PROPERTY = "userOverrideDefaultCatalog"; //$NON-NLS-1$

	/**
	 * Return the <em>identifier</em> of the catalog to be used as a default
	 * for the JPA project instead of the one that is associated by default
	 * with the connection profile.
	 * @return The catalog identifier. May be null (implying the connection profile
	 * default catalog should be used).
	 */
	String getUserOverrideDefaultCatalog();

	/**
	 * Set the <em>identifier</em> of the catalog to be used as a default
	 * for the JPA project instead of the one that is associated by default
	 * with the connection profile.
	 * @parameter catalog The catalog identifier. May be null (implying the connection profile
	 * default catalog should be used).
	 */
	void setUserOverrideDefaultCatalog(String catalog);


	// ********** user override default schema **********

	/** 
	 * ID string used when the JPA project's user override default schema changes.
	 * @see #addPropertyChangeListener(String, org.eclipse.jpt.common.utility.model.listener.PropertyChangeListener)
	 */
	String USER_OVERRIDE_DEFAULT_SCHEMA_PROPERTY = "userOverrideDefaultSchema"; //$NON-NLS-1$

	/**
	 * Return the <em>identifier</em> of the schema to be used as a default
	 * for the JPA project instead of the one that is associated by default
	 * with the connection profile.
	 * @return The schema identifier. May be null (implying the connection profile
	 * default schema should be used).
	 */
	String getUserOverrideDefaultSchema();

	/**
	 * Set the <em>identifier</em> of the schema to be used as a default
	 * for the JPA project instead of the one that is associated by default
	 * with the connection profile.
	 * @parameter schema The schema identifier. May be null (implying the connection profile
	 * default schema should be used).
	 */
	void setUserOverrideDefaultSchema(String schema);


	// ********** discover annotated classes **********

	/** 
	 * ID string used when discoversAnnotatedClasses property is changed.
	 * @see #addPropertyChangeListener(String, org.eclipse.jpt.common.utility.model.listener.PropertyChangeListener)
	 */
	String DISCOVERS_ANNOTATED_CLASSES_PROPERTY = "discoversAnnotatedClasses"; //$NON-NLS-1$

	/**
	 * Return whether the JPA project will not generate error messages for any
	 * annotated classes that are not listed in the <code>persistence.xml</code>
	 * file or one of its mapping files. If this flag is set to
	 * <code>false</code>, error messages will be generated for all of the
	 * annotated classes that are not explicitly listed. The JPA project
	 * <em>always</em> "discovers" annotated classes and allows the user to
	 * reference them throughout the model; this flag simply controls whether
	 * the error messages are generated during validation.
	 * <p>
	 * This is a user-specified preference that is probably
	 * only helpful when deploying to a JavaSE environment. The JPA spec
	 * says annotated classes are to be discovered automatically in a JavaEE
	 * environment; while the managed persistence classes must be explicitly
	 * listed in a JavaSE environment: "A list of all named managed persistence
	 * classes must be specified in Java SE environments to insure portability".
	 * This flag allows Dali to behave consistently with the user's JPA
	 * implementation, which may allow "discovery" in a JavaSE environment
	 * (e.g. EclipseLink). This setting can also be used when the user wants
	 * to explicitly list classes, even when the classes are "discovered"
	 * by the JPA implementation.
	 */
	boolean discoversAnnotatedClasses();

	/**
	 * Set whether the JPA project will not generate error messages for any
	 * annotated classes that are not listed in the <code>persistence.xml</code>
	 * file or one of its mapping files.
	 * @see #discoversAnnotatedClasses()
	 */
	void setDiscoversAnnotatedClasses(boolean discoversAnnotatedClasses);


	// ********** manager **********

	/**
	 * The JPA project manager provides behavior to be used by all the JPA
	 * projects
	 */
	interface Manager {

		// ********** commands **********

		/**
		 * Execute the specified command, possibly asynchronously, synchronizing
		 * with all the other stuff manipulating the JPA projects
		 * (e.g. resource change events).
		 * If, once the command comes up for execution, the specified JPA project
		 * is no longer present, the command will <em>not</em> be executed by the
		 * JPA project manager.
		 */
		void execute(JobCommand command, String jobName, JpaProject jpaProject);


		// ********** modifying shared documents **********

		/**
		 * Return the project-wide implementation of the
		 * {@link ExtendedCommandExecutor} interface.
		 */
		ExtendedCommandExecutor getModifySharedDocumentCommandExecutor();


		// ********** logging **********

		/**
		 * Log the specified message.
		 */
		void log(String msg);

		/**
		 * Log the specified exception/error.
		 */
		void log(Throwable throwable);

		/**
		 * Log the specified message and exception/error.
		 */
		void log(String msg, Throwable throwable);

		/**
		 * Return an exception handler that can be used by the JPA model.
		 */
		ExceptionHandler getExceptionHandler();
	}


	// ********** construction config **********

	/**
	 * The settings used to construct a JPA project.
	 */
	interface Config {
		/**
		 * Return the JPA platform to be associated with the new JPA project.
		 */
		Manager getJpaProjectManager();

		/**
		 * Return the Eclipse project to be associated with the new JPA project.
		 */
		IProject getProject();

		/**
		 * Return the JPA platform to be associated with the new JPA project.
		 */
		JpaPlatform getJpaPlatform();

		/**
		 * Return the name of the connection profile to be associated
		 * with the new JPA project. (This connection profile wraps a DTP
		 * connection profile.)
		 */
		String getConnectionProfileName();

		/**
		 * Return the catalog to use instead of the connection profile's
		 * default catalog.
		 * May be null.
		 */
		String getUserOverrideDefaultCatalog();

		/**
		 * Return the name of the schema to use instead of the default schema
		 * of the connection profile.
		 * May be null.
		 */
		String getUserOverrideDefaultSchema();

		/**
		 * Return whether the new JPA project is to "discover" annotated
		 * classes.
		 */
		boolean discoverAnnotatedClasses();
	}


	// ********** reference **********

	/**
	 * Standard adapter for "synchronously" retrieving a
	 * {@link JpaProject JPA project}
	 * (i.e. if necessary, wait for the JPA project to be constructed;
	 * thus the {@link InterruptedException}):
	 * <pre>
	 * IProject project = ResourcesPlugin.getWorkspace().getRoot().getProject("Foo Project");
	 * JpaProject.Reference jpaProjectRef = (JpaProject.Reference) project.getAdapter(JpaProject.Reference.class);
	 * JpaProject jpaProject = jpaProjectRef.getValue();
	 * </pre>
	 * See <code>org.eclipse.jpt.jpa.core/plugin.xml</code>.
	 * @see org.eclipse.jpt.jpa.core.internal.ProjectAdapterFactory
	 */
	interface Reference {
		/**
		 * Return the JPA project corresponding to the reference's Eclipse project.
		 * Return <code>null</code> if unable to associate the Eclipse
		 * project with a JPA project. This method can be long-running.
		 */
		JpaProject getValue() throws InterruptedException;

		/**
		 * The JPA settings associated with the reference's Eclipse project
		 * have changed in such a way as to require the associated
		 * JPA project to be completely rebuilt
		 * (e.g. when the user changes a project's JPA platform).
		 * Return the new JPA project.
		 */
		JpaProject rebuild() throws InterruptedException;

		/**
		 * Build the JPA validation messages for the reference's
		 * Eclipse project.
		 */
		Iterable<IMessage> buildValidationMessages(IReporter reporter) throws InterruptedException;
	}
}