001: /*******************************************************************************
002: * Copyright (c) 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.ui;
011:
012: import org.eclipse.core.runtime.IProgressMonitor;
013:
014: import org.eclipse.jdt.core.ITypeRoot;
015: import org.eclipse.jdt.core.dom.AST;
016: import org.eclipse.jdt.core.dom.ASTNode;
017: import org.eclipse.jdt.core.dom.CompilationUnit;
018: import org.eclipse.jdt.core.dom.rewrite.ASTRewrite;
019:
020: import org.eclipse.jdt.internal.ui.JavaPlugin;
021:
022: /**
023: * The {@link SharedASTProvider} provides access to the {@link CompilationUnit AST root} used by
024: * the current active Java editor.
025: *
026: * <p>For performance reasons, not more than one AST should be kept in memory at a time. Therefore, clients must
027: * not keep any references to the shared AST or its nodes or bindings.
028: * </p>
029: * <p>Clients can make the following assumptions about the AST:
030: * <dl>
031: * <li>the AST has a {@link ITypeRoot} as source: {@link CompilationUnit#getTypeRoot()} is not null.</li>
032: * <li>the {@link AST#apiLevel() AST API level} is {@link AST#JLS3 API level 3} or higher</li>
033: * <li>the AST has bindings resolved ({@link AST#hasResolvedBindings()})</li>
034: * <li>{@link AST#hasStatementsRecovery() statement} and {@link AST#hasBindingsRecovery() bindings}
035: * recovery are enabled
036: * </li>
037: * </dl>
038: * It is possible that in the future a higher API level is used, or that future options will be enabled.
039: * </p>
040: * <p>
041: * The returned AST is shared. It is marked as {@link ASTNode#PROTECT} and must not be modified. Clients are advised to use
042: * the non-modifying {@link ASTRewrite} to get update scripts.
043: * </p>
044: *
045: * @since 3.4
046: */
047: public final class SharedASTProvider {
048:
049: /**
050: * Wait flag class.
051: */
052: public static final class WAIT_FLAG {
053:
054: private String fName;
055:
056: private WAIT_FLAG(String name) {
057: fName = name;
058: }
059:
060: /*
061: * @see java.lang.Object#toString()
062: */
063: public String toString() {
064: return fName;
065: }
066: }
067:
068: /**
069: * Wait flag indicating that a client requesting an AST
070: * wants to wait until an AST is ready.
071: * <p>
072: * An AST will be created by this AST provider if the shared
073: * AST is not for the given Java element.
074: * </p>
075: */
076: public static final WAIT_FLAG WAIT_YES = new WAIT_FLAG("wait yes"); //$NON-NLS-1$
077:
078: /**
079: * Wait flag indicating that a client requesting an AST
080: * only wants to wait for the shared AST of the active editor.
081: * <p>
082: * No AST will be created by the AST provider.
083: * </p>
084: */
085: public static final WAIT_FLAG WAIT_ACTIVE_ONLY = new WAIT_FLAG(
086: "wait active only"); //$NON-NLS-1$
087:
088: /**
089: * Wait flag indicating that a client requesting an AST
090: * only wants the already available shared AST.
091: * <p>
092: * No AST will be created by the AST provider.
093: * </p>
094: */
095: public static final WAIT_FLAG WAIT_NO = new WAIT_FLAG("don't wait"); //$NON-NLS-1$
096:
097: /**
098: * Returns a compilation unit AST for the given Java element. If the element is the input of the active
099: * Java editor, the AST is the shared AST.
100: * <p>
101: * Clients are not allowed to modify the AST and must not keep any references.
102: * </p>
103: *
104: * @param element
105: * the {@link ITypeRoot}, must not be <code>null</code>
106: * @param waitFlag
107: * {@link #WAIT_YES}, {@link #WAIT_NO} or {@link #WAIT_ACTIVE_ONLY}
108: * @param progressMonitor
109: * the progress monitor or <code>null</code>
110: * @return
111: * the AST or <code>null</code>.
112: * <dl><li>if {@link #WAIT_NO} has been specified <code>null</code> is returned if the element is not
113: * input of the current Java editor or no AST is available</li>
114: * <li>if {@link #WAIT_ACTIVE_ONLY} has been specified <code>null</code> is returned if the element is not
115: * input of the current Java editor</li>
116: * <li>if {@link #WAIT_YES} has been specified either the shared AST is returned or a new AST is created.</li>
117: * </dl>
118: */
119: public static CompilationUnit getAST(ITypeRoot element,
120: WAIT_FLAG waitFlag, IProgressMonitor progressMonitor) {
121: return JavaPlugin.getDefault().getASTProvider().getAST(element,
122: waitFlag, progressMonitor);
123: }
124:
125: private SharedASTProvider() {
126: // Prevent instantiation.
127: }
128:
129: }
|