core/plugins/org.eclipse.dltk.core/model/org/eclipse/dltk/core/ISourceModule.java

/*******************************************************************************
 * Copyright (c) 2005, 2016 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
 *
 *******************************************************************************/
package org.eclipse.dltk.core;

import org.eclipse.core.runtime.IProgressMonitor;

/**
 * Represents an entire source module (source file). Source module elements need
 * to be opened before they can be navigated or manipulated.
 * 
 * The children are of type {@link IPackageDeclaration},
 * {@link IImportContainer}, {@link IType}, {@link IMethod} and {@link IField}
 * and appear in the order in which they are declared in the source.
 * 
 * The children appear in the order in which they are declared in the source. If
 * a file cannot be parsed, its structure remains unknown. Use
 * {@link IModelElement#isStructureKnown} to determine whether this is the case.
 * <p>
 * This interface is not intended to be implemented by clients.
 * </p>
 */
public interface ISourceModule extends IModule, ISourceReference,
		ISourceManipulation, ICodeAssist {
	/**
	 * Commits the contents of this working copy to its underlying resource.
	 * 
	 * <p>
	 * It is possible that the contents of the original resource have changed
	 * since this working copy was created, in which case there is an update
	 * conflict. The value of the <code>force</code> parameter effects the
	 * resolution of such a conflict:
	 * <ul>
	 * <li> <code>true</code> - in this case the contents of this working copy
	 * are applied to the underlying resource even though this working copy was
	 * created before a subsequent change in the resource</li>
	 * <li> <code>false</code> - in this case a {@link ModelException} is thrown</li>
	 * </ul>
	 * <p>
	 * A working copy can be created on a not-yet existing compilation unit. In
	 * particular, such a working copy can then be committed in order to create
	 * the corresponding compilation unit.
	 * </p>
	 * 
	 * @param force
	 *            a flag to handle the cases when the contents of the original
	 *            resource have changed since this working copy was created
	 * @param monitor
	 *            the given progress monitor
	 * @throws ModelException
	 *             if this working copy could not commit. Reasons include:
	 *             <ul>
	 *             <li>A {@link org.eclipse.core.runtime.CoreException} occurred
	 *             while updating an underlying resource
	 *             <li>This element is not a working copy
	 *             (INVALID_ELEMENT_TYPES)
	 *             <li>A update conflict (described above) (UPDATE_CONFLICT)
	 *             </ul>
	 * 
	 */
	void commitWorkingCopy(boolean force, IProgressMonitor monitor)
			throws ModelException;

	/**
	 * Changes this compilation unit handle into a working copy. A new
	 * {@link IBuffer} is created using this compilation unit handle's owner.
	 * Uses the primary owner is none was specified when this compilation unit
	 * handle was created.
	 * <p>
	 * When switching to working copy mode, problems are reported to given
	 * {@link IProblemRequestor}. Note that once in working copy mode, the given
	 * {@link IProblemRequestor} is ignored. Only the original
	 * {@link IProblemRequestor} is used to report subsequent problems.
	 * </p>
	 * <p>
	 * Once in working copy mode, changes to this compilation unit or its
	 * children are done in memory. Only the new buffer is affected. Using
	 * {@link #commitWorkingCopy(boolean, IProgressMonitor)} will bring the
	 * underlying resource in sync with this compilation unit.
	 * </p>
	 * <p>
	 * If this compilation unit was already in working copy mode, an internal
	 * counter is incremented and no other action is taken on this compilation
	 * unit. To bring this compilation unit back into the original mode (where
	 * it reflects the underlying resource), {@link #discardWorkingCopy} must be
	 * call as many times as
	 * {@link #becomeWorkingCopy(IProblemRequestor, IProgressMonitor)}.
	 * </p>
	 * 
	 * @param problemRequestor
	 *            a requestor which will get notified of problems detected
	 *            during reconciling as they are discovered. The requestor can
	 *            be set to <code>null</code> indicating that the client is not
	 *            interested in problems.
	 * @param monitor
	 *            a progress monitor used to report progress while opening this
	 *            compilation unit or <code>null</code> if no progress should be
	 *            reported
	 * @throws ModelException
	 *             if this compilation unit could not become a working copy.
	 * @see #discardWorkingCopy()
	 * 
	 */
	void becomeWorkingCopy(IProblemRequestor problemRequestor,
			IProgressMonitor monitor) throws ModelException;

	/**
	 * Changes this compilation unit in working copy mode back to its original
	 * mode.
	 * <p>
	 * This has no effect if this compilation unit was not in working copy mode.
	 * </p>
	 * <p>
	 * If {@link #becomeWorkingCopy} was called several times on this
	 * compilation unit, {@link #discardWorkingCopy} must be called as many
	 * times before it switches back to the original mode.
	 * </p>
	 * 
	 * @throws ModelException
	 *             if this working copy could not return in its original mode.
	 * @see #becomeWorkingCopy(IProblemRequestor, IProgressMonitor)
	 */
	void discardWorkingCopy() throws ModelException;

	/**
	 * Returns the source code associated with this element. This extracts the
	 * substring from the source buffer containing this source element. This
	 * corresponds to the source range that would be returned by
	 * <code>getSourceRange</code>.
	 * 
	 * @return the source code, or <code>null</code> if this element has no
	 *         associated source code
	 * @exception ModelException
	 *                if an exception occurs while accessing its corresponding
	 *                resource
	 */
	@Override
	String getSource() throws ModelException;

	/**
	 * Returns the source code associated with this element. This extracts the
	 * substring from the source buffer containing this source element. This
	 * corresponds to the source range that would be returned by
	 * <code>getSourceRange</code>.
	 * 
	 * @return the source code, or <code>null</code> if this element has no
	 *         associated source code
	 * @exception ModelException
	 *                if an exception occurs while accessing its corresponding
	 *                resource
	 */
	char[] getSourceAsCharArray() throws ModelException;

	/**
	 * Returns a new working copy of this compilation unit if it is a primary
	 * compilation unit, or this compilation unit if it is already a non-primary
	 * working copy.
	 * <p>
	 * Note: if intending to share a working copy amongst several clients, then
	 * {@link #getWorkingCopy(WorkingCopyOwner, IProblemRequestor, IProgressMonitor)}
	 * should be used instead.
	 * </p>
	 * <p>
	 * When the working copy instance is created, an ADDED IModelElementDelta is
	 * reported on this working copy.
	 * </p>
	 * <p>
	 * Once done with the working copy, users of this method must discard it
	 * using {@link #discardWorkingCopy()}.
	 * </p>
	 * <p>
	 * A working copy can be created on a not-yet existing compilation unit. In
	 * particular, such a working copy can then be committed in order to create
	 * the corresponding compilation unit.
	 * </p>
	 * 
	 * @param monitor
	 *            a progress monitor used to report progress while opening this
	 *            compilation unit or <code>null</code> if no progress should be
	 *            reported
	 * @throws ModelException
	 *             if the contents of this element can not be determined.
	 * @return a new working copy of this element if this element is not a
	 *         working copy, or this element if this element is already a
	 *         working copy
	 */
	ISourceModule getWorkingCopy(IProgressMonitor monitor)
			throws ModelException;

	ISourceModule getWorkingCopy(WorkingCopyOwner owner,
			IProblemRequestor problemRequestor, IProgressMonitor monitor)
			throws ModelException;

	/**
	 * Reconciles the contents of this working copy, sends out a model delta
	 * notification indicating the nature of the change of the working copy
	 * since the last time it was either reconciled or made consistent (
	 * {@link IOpenable#makeConsistent(IProgressMonitor)}), and returns a
	 * compilation unit AST if requested.
	 * <p>
	 * It performs the reconciliation by locally caching the contents of the
	 * working copy, updating the contents, then creating a delta over the
	 * cached contents and the new contents, and finally firing this delta.
	 * <p>
	 * The boolean argument allows to force problem detection even if the
	 * working copy is already consistent.
	 * </p>
	 * <p>
	 * This functionality allows to specify a working copy owner which is used
	 * during problem detection. All references contained in the working copy
	 * are resolved against other units; for which corresponding owned working
	 * copies are going to take precedence over their original compilation
	 * units. If <code>null</code> is passed in, then the primary working copy
	 * owner is used.
	 * </p>
	 * <p>
	 * Compilation problems found in the new contents are notified through the
	 * {@link IProblemRequestor} interface which was passed at creation, and no
	 * longer as transient markers.
	 * </p>
	 * <p>
	 * Note: added/removed/changed inner types generate change deltas.
	 * </p>
	 * <p>
	 * If requested, a DOM AST representing the compilation unit is returned.
	 * Its bindings are computed only if the problem requestor is active, or if
	 * the problem detection is forced. This method returns <code>null</code> if
	 * the creation of the DOM AST was not requested, or if the requested level
	 * of AST API is not supported, or if the working copy was already
	 * consistent.
	 * </p>
	 * 
	 * @param astLevel
	 *            either {@link #NO_AST} if no AST is wanted, or the of the AST
	 *            if one is wanted
	 * @param forceProblemDetection
	 *            boolean indicating whether problem should be recomputed even
	 *            if the source hasn't changed
	 * @param owner
	 *            the owner of working copies that take precedence over the
	 *            original compilation units, or <code>null</code> if the
	 *            primary working copy owner should be used
	 * @param monitor
	 *            a progress monitor
	 * @return the compilation unit AST or <code>null</code> if not requested,
	 *         or if the requested level of AST API is not supported, or if the
	 *         working copy was consistent
	 * @throws ModelException
	 *             if the contents of the original element cannot be accessed.
	 *             Reasons include:
	 *             <ul>
	 *             <li>The original script element does not exist
	 *             (ELEMENT_DOES_NOT_EXIST)</li>
	 *             </ul>
	 */
	void reconcile(boolean forceProblemDetection, WorkingCopyOwner owner,
			IProgressMonitor monitor) throws ModelException;

	/**
	 * Returns the primary compilation unit (whose owner is the primary owner)
	 * this working copy was created from, or this compilation unit if this a
	 * primary compilation unit.
	 * <p>
	 * Note that the returned primary compilation unit can be in working copy
	 * mode.
	 * </p>
	 * 
	 * @return the primary compilation unit this working copy was created from,
	 *         or this compilation unit if it is primary
	 */
	public ISourceModule getPrimary();

	/**
	 * Returns the smallest element within this compilation unit that includes
	 * the given source position (that is, a method, field, etc.), or
	 * <code>null</code> if there is no element other than the compilation unit
	 * itself at the given position, or if the given position is not within the
	 * source range of this compilation unit.
	 * 
	 * @param position
	 *            a source position inside the compilation unit
	 * @return the innermost script element enclosing a given source position or
	 *         <code>null</code> if none (excluding the compilation unit).
	 * @throws ModelException
	 *             if the compilation unit does not exist or if an exception
	 *             occurs while accessing its corresponding resource
	 */
	IModelElement getElementAt(int position) throws ModelException;

	/**
	 * Returns the working copy owner of this working copy. Returns null if it
	 * is not a working copy or if it has no owner.
	 * 
	 * @return WorkingCopyOwner the owner of this working copy or
	 *         <code>null</code>
	 * 
	 */
	WorkingCopyOwner getOwner();

	/**
	 * Returns whether this element is a working copy.
	 * 
	 * @return true if this element is a working copy, false otherwise
	 * 
	 */
	boolean isWorkingCopy();

	/**
	 * Returns the top-level type declared in this compilation unit with the
	 * given simple type name. The type name has to be a valid compilation unit
	 * name. This is a handle-only method. The type may or may not exist.
	 * 
	 * @param name
	 *            the simple name of the requested type in the compilation unit
	 * @return a handle onto the corresponding type. The type may or may not
	 *         exist.
	 */
	IType getType(String name);

	/**
	 * Returns the top-level types declared in this compilation unit in the
	 * order in which they appear in the source.
	 * 
	 * @return the top-level types declared in this compilation unit
	 * @throws ModelException
	 *             if this element does not exist or if an exception occurs
	 *             while accessing its corresponding resource
	 */
	IType[] getTypes() throws ModelException;

	IType[] getAllTypes() throws ModelException;

	/**
	 * Read only source module. From external resources.
	 */
	@Override
	boolean isReadOnly();

	boolean isPrimary();

	/**
	 * Returns the first package declaration in this compilation unit with the
	 * given package name (there normally is at most one package declaration).
	 * This is a handle-only method. The package declaration may or may not
	 * exist.
	 * 
	 * @param name
	 *            the name of the package declaration as defined by JLS2 7.4.
	 *            (For example, <code>"java.lang"</code>)
	 * @return the first package declaration in this compilation unit with the
	 *         given package name
	 */
	IPackageDeclaration getPackageDeclaration(String name);

	/**
	 * Returns the package declarations in this compilation unit in the order in
	 * which they appear in the source. There normally is at most one package
	 * declaration.
	 * 
	 * @return an array of package declaration (normally of size one)
	 * 
	 * @throws ModelException
	 *             if this element does not exist or if an exception occurs
	 *             while accessing its corresponding resource
	 */
	IPackageDeclaration[] getPackageDeclarations() throws ModelException;

	/**
	 * Returns the method with the specified name and parameter types in this
	 * type (for example, <code>"foo", {"I", "QString;"}</code>). To get the
	 * handle for a constructor, the name specified must be the simple name of
	 * the enclosing type. This is a handle-only method. The method may or may
	 * not be present.
	 * <p>
	 * The type signatures may be either unresolved (for source types) or
	 * resolved (for binary types), and either basic (for basic types) or rich
	 * (for parameterized types).
	 * </p>
	 * 
	 * @param name
	 *            the given name
	 * @return the method with the specified name and parameter types in this
	 *         type
	 */
	IMethod getMethod(String name);

	IField getField(String string);

	IField[] getFields() throws ModelException;

	boolean isBuiltin();

	/**
	 * @since 2.0
	 */
	boolean isBinary();
}