/*******************************************************************************
* 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();
}