001: /*******************************************************************************
002: * Copyright (c) 2000, 2007 IBM Corporation and others.
003: * All rights reserved. This program and the accompanying materials
004: * are made available under the terms of the Eclipse Public License v1.0
005: * which accompanies this distribution, and is available at
006: * http://www.eclipse.org/legal/epl-v10.html
007: *
008: * Contributors:
009: * IBM Corporation - initial API and implementation
010: *******************************************************************************/package org.eclipse.jdt.core;
011:
012: import org.eclipse.core.runtime.IProgressMonitor;
013:
014: /**
015: * Represents an entire binary type (single <code>.class</code> file).
016: * A class file has a single child of type <code>IType</code>.
017: * Class file elements need to be opened before they can be navigated.
018: * If a class file cannot be parsed, its structure remains unknown. Use
019: * <code>IJavaElement.isStructureKnown</code> to determine whether this is the
020: * case.
021: * <p>
022: * Note: <code>IClassFile</code> extends <code>ISourceReference</code>.
023: * Source can be obtained for a class file if and only if source has been attached to this
024: * class file. The source associated with a class file is the source code of
025: * the compilation unit it was (nominally) generated from.
026: * </p>
027: * <p>
028: * This interface is not intended to be implemented by clients.
029: * </p>
030: *
031: * @see IPackageFragmentRoot#attachSource(org.eclipse.core.runtime.IPath, org.eclipse.core.runtime.IPath, IProgressMonitor)
032: */
033:
034: public interface IClassFile extends ITypeRoot {
035:
036: /**
037: * Changes this class file handle into a working copy. A new {@link IBuffer} is
038: * created using the given owner. Uses the primary owner if <code>null</code> is
039: * specified.
040: * <p>
041: * When switching to working copy mode, problems are reported to the given
042: * {@link IProblemRequestor}. Note that once in working copy mode, the given
043: * {@link IProblemRequestor} is ignored. Only the original {@link IProblemRequestor}
044: * is used to report subsequent problems.
045: * </p>
046: * <p>
047: * Once in working copy mode, changes to this working copy or its children are done in memory.
048: * Only the new buffer is affected.
049: * </p>
050: * <p>
051: * Using {@link ICompilationUnit#commitWorkingCopy(boolean, IProgressMonitor)} on the working copy
052: * will throw a <code>JavaModelException</code> as a class file is implicetly read-only.
053: * </p>
054: * <p>
055: * If this class file was already in working copy mode, an internal counter is incremented and no
056: * other action is taken on this working copy. To bring this working copy back into the original mode
057: * (where it reflects the underlying resource), {@link ICompilationUnit#discardWorkingCopy} must be call as many
058: * times as {@link #becomeWorkingCopy(IProblemRequestor, WorkingCopyOwner, IProgressMonitor)}.
059: * </p>
060: * <p>
061: * The primary compilation unit of a class file's working copy does not exist if the class file is not
062: * in working copy mode (<code>classFileWorkingCopy.getPrimary().exists() == false</code>).
063: * </p>
064: * <p>
065: * The resource of a class file's working copy is <code>null</code> if the class file is in an external jar file.
066: * </p>
067: *
068: * @param problemRequestor a requestor which will get notified of problems detected during
069: * reconciling as they are discovered. The requestor can be set to <code>null</code> indicating
070: * that the client is not interested in problems.
071: * @param owner the given {@link WorkingCopyOwner}, or <code>null</code> for the primary owner
072: * @param monitor a progress monitor used to report progress while opening this compilation unit
073: * or <code>null</code> if no progress should be reported
074: * @return a working copy for this class file
075: * @throws JavaModelException if this compilation unit could not become a working copy.
076: * @see ICompilationUnit#discardWorkingCopy()
077: * @since 3.2
078: * @deprecated Use {@link ITypeRoot#getWorkingCopy(WorkingCopyOwner, IProgressMonitor)} instead.
079: * Note that if this deprecated method is used, problems will be reported to the given problem requestor
080: * as well as the problem requestor returned by the working copy owner (if not null).
081: */
082: ICompilationUnit becomeWorkingCopy(
083: IProblemRequestor problemRequestor, WorkingCopyOwner owner,
084: IProgressMonitor monitor) throws JavaModelException;
085:
086: /**
087: * Returns the bytes contained in this class file.
088: *
089: * @return the bytes contained in this class file
090: *
091: * @exception JavaModelException if this element does not exist or if an
092: * exception occurs while accessing its corresponding resource
093: * @since 3.3
094: */
095: byte[] getBytes() throws JavaModelException;
096:
097: /**
098: * Returns the type contained in this class file.
099: * This is a handle-only method. The type may or may not exist.
100: *
101: * @return the type contained in this class file
102: */
103: IType getType();
104:
105: /**
106: * Returns a working copy on the source associated with this class file using the given
107: * factory to create the buffer, or <code>null</code> if there is no source associated
108: * with the class file.
109: * <p>
110: * The buffer will be automatically initialized with the source of the class file
111: * upon creation.
112: * <p>
113: * The only valid operations on this working copy are <code>getBuffer()</code> or <code>getOriginalElement</code>.
114: *
115: * @param monitor a progress monitor used to report progress while opening this compilation unit
116: * or <code>null</code> if no progress should be reported
117: * @param factory the factory that creates a buffer that is used to get the content of the working copy
118: * or <code>null</code> if the internal factory should be used
119: * @return a a working copy on the source associated with this class file
120: * @exception JavaModelException if the source of this class file can
121: * not be determined. Reasons include:
122: * <ul>
123: * <li> This class file does not exist (ELEMENT_DOES_NOT_EXIST)</li>
124: * </ul>
125: * @since 2.0
126: * @deprecated Use {@link ITypeRoot#getWorkingCopy(WorkingCopyOwner, IProgressMonitor)} instead
127: */
128: IJavaElement getWorkingCopy(IProgressMonitor monitor,
129: IBufferFactory factory) throws JavaModelException;
130:
131: /**
132: * Returns whether this type represents a class. This is not guaranteed to be
133: * instantaneous, as it may require parsing the underlying file.
134: *
135: * @return <code>true</code> if the class file represents a class.
136: *
137: * @exception JavaModelException if this element does not exist or if an
138: * exception occurs while accessing its corresponding resource
139: */
140: boolean isClass() throws JavaModelException;
141:
142: /**
143: * Returns whether this type represents an interface. This is not guaranteed to
144: * be instantaneous, as it may require parsing the underlying file.
145: *
146: * @return <code>true</code> if the class file represents an interface.
147: *
148: * @exception JavaModelException if this element does not exist or if an
149: * exception occurs while accessing its corresponding resource
150: */
151: boolean isInterface() throws JavaModelException;
152: }
|