/*******************************************************************************
 * Copyright (c) 2000, 2004 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
 *******************************************************************************/
package org.eclipse.jdt.core;

import org.eclipse.core.runtime.IProgressMonitor;

/**
 * Represents an entire binary type (single <code>.class</code> file). 
 * A class file has a single child of type <code>IType</code>.
 * Class file elements need to be opened before they can be navigated.
 * If a class file cannot be parsed, its structure remains unknown. Use 
 * <code>IJavaElement.isStructureKnown</code> to determine whether this is the
 * case.
 * <p>
 * Note: <code>IClassFile</code> extends <code>ISourceReference</code>.
 * Source can be obtained for a class file if and only if source has been attached to this
 * class file. The source associated with a class file is the source code of
 * the compilation unit it was (nominally) generated from.
 * </p>
 * <p>
 * This interface is not intended to be implemented by clients.
 * </p>
 *
 * @see IPackageFragmentRoot#attachSource(org.eclipse.core.runtime.IPath, org.eclipse.core.runtime.IPath, IProgressMonitor)
 */
 
public interface IClassFile extends IJavaElement, IParent, IOpenable, ISourceReference, ICodeAssist {
	
/**
 * Changes this class file handle into a working copy. A new {@link IBuffer} is
 * created using the given owner. Uses the primary owner if <code>null</code> is
 * specified.
 * <p>
 * When switching to working copy mode, problems are reported to the 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 working copy or its children are done in memory.
 * Only the new buffer is affected. 
 * </p>
 * </p>
 * Using {@link ICompilationUnit#commitWorkingCopy(boolean, IProgressMonitor)} on the working copy
 * will throw a <code>JavaModelException</code> as a class file is implicetly read-only.
 * </p>
 * <p>
 * If this class file was already in working copy mode, an internal counter is incremented and no
 * other action is taken on this working copy. To bring this working copy back into the original mode 
 * (where it reflects the underlying resource), {@link ICompilationUnit#discardWorkingCopy} must be call as many 
 * times as {@link #becomeWorkingCopy(IProblemRequestor, WorkingCopyOwner, IProgressMonitor)}.
 * </p>
 * <p>
 * The primary compilation unit of a class file's working copy does not exist if the class file is not
 * in working copy mode (<code>classFileWorkingCopy.getPrimary().exists() == false</code>).
 * </p>
 * <p>
 * The resource of a class file's working copy is <code>null</code> if the class file is in an external jar file.
 * </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 owner the given {@link WorkingCopyOwner}, or <code>null</code> for the primary owner
 * @param monitor a progress monitor used to report progress while opening this compilation unit
 * 	or <code>null</code> if no progress should be reported 
 * @return a working copy for this class file
 * @throws JavaModelException if this compilation unit could not become a working copy.
 * @see ICompilationUnit#discardWorkingCopy()
 * @since 3.2
 */
ICompilationUnit becomeWorkingCopy(IProblemRequestor problemRequestor, WorkingCopyOwner owner, IProgressMonitor monitor) throws JavaModelException;

/**
 * Returns the smallest element within this class file that 
 * includes the given source position (a method, field, etc.), or
 * <code>null</code> if there is no element other than the class file
 * itself at the given position, or if the given position is not
 * within the source range of this class file.
 *
 * @param position a source position inside the class file
 * @return the innermost Java element enclosing a given source position or <code>null</code>
 *  if none (excluding the class file).
 *
 * @exception JavaModelException if this element does not exist or if an
 *      exception occurs while accessing its corresponding resource
 */
IJavaElement getElementAt(int position) throws JavaModelException;
/**
 * Returns the type contained in this class file.
 *
 * @return the type contained in this class file
 *
 * @exception JavaModelException if this element does not exist or if an
 *      exception occurs while accessing its corresponding resource
 */
IType getType() throws JavaModelException;
/**
 * Returns a working copy on the source associated with this class file using the given 
 * owner to create the buffer, or <code>null</code> if there is no source associated
 * with the class file.
 * <p>
 * The buffer will be automatically initialized with the source of the class file
 * upon creation.
 * <p>
 * The only valid operations on this working copy are <code>getBuffer()</code> or <code>getPrimary()</code>.
 *
 * @param owner the owner that creates a buffer that is used to get the content of the working copy
 *                 or <code>null</code> if the primary owner should be used
 * @param monitor a progress monitor used to report progress while opening this compilation unit
 *                 or <code>null</code> if no progress should be reported 
 * @return a  a working copy on the source associated with this class file
 * @exception JavaModelException if the source of this class file can
 *   not be determined. Reasons include:
 * <ul>
 * <li> This class file does not exist (ELEMENT_DOES_NOT_EXIST)</li>
 * </ul>
 * @since 3.0
 */
ICompilationUnit getWorkingCopy(WorkingCopyOwner owner, IProgressMonitor monitor) throws JavaModelException;
/**
 * Returns a working copy on the source associated with this class file using the given 
 * factory to create the buffer, or <code>null</code> if there is no source associated
 * with the class file.
 * <p>
 * The buffer will be automatically initialized with the source of the class file
 * upon creation.
 * <p>
 * The only valid operations on this working copy are <code>getBuffer()</code> or <code>getOriginalElement</code>.
 *
 * @param monitor a progress monitor used to report progress while opening this compilation unit
 *                 or <code>null</code> if no progress should be reported 
 * @param factory the factory that creates a buffer that is used to get the content of the working copy
 *                 or <code>null</code> if the internal factory should be used
 * @return a  a working copy on the source associated with this class file
 * @exception JavaModelException if the source of this class file can
 *   not be determined. Reasons include:
 * <ul>
 * <li> This class file does not exist (ELEMENT_DOES_NOT_EXIST)</li>
 * </ul>
 * @since 2.0
 * @deprecated Use getWorkingCopy(WorkingCopyOwner, IProgressMonitor) instead
 */
IJavaElement getWorkingCopy(IProgressMonitor monitor, IBufferFactory factory) throws JavaModelException;
/**
 * Returns whether this type represents a class. This is not guaranteed to be
 * instantaneous, as it may require parsing the underlying file.
 *
 * @return <code>true</code> if the class file represents a class.
 *
 * @exception JavaModelException if this element does not exist or if an
 *      exception occurs while accessing its corresponding resource
 */
boolean isClass() throws JavaModelException;
/**
 * Returns whether this type represents an interface. This is not guaranteed to
 * be instantaneous, as it may require parsing the underlying file. 
 *
 * @return <code>true</code> if the class file represents an interface.
 *
 * @exception JavaModelException if this element does not exist or if an
 *      exception occurs while accessing its corresponding resource
 */
boolean isInterface() throws JavaModelException;
}