| /* |
| * |
| * Licensed to the Apache Software Foundation (ASF) under one or more |
| * contributor license agreements. See the NOTICE file distributed with |
| * this work for additional information regarding copyright ownership. |
| * The ASF licenses this file to You under the Apache License, Version 2.0 |
| * (the "License"); you may not use this file except in compliance with |
| * the License. You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| * |
| */ |
| |
| package org.apache.flex.compiler.definitions; |
| |
| import java.util.List; |
| |
| import org.apache.flex.compiler.common.ASModifier; |
| import org.apache.flex.compiler.common.ModifiersSet; |
| import org.apache.flex.compiler.definitions.metadata.IDeprecationInfo; |
| import org.apache.flex.compiler.definitions.metadata.IMetaTag; |
| import org.apache.flex.compiler.definitions.references.INamespaceReference; |
| import org.apache.flex.compiler.definitions.references.IReference; |
| import org.apache.flex.compiler.projects.ICompilerProject; |
| import org.apache.flex.compiler.scopes.IASScope; |
| import org.apache.flex.compiler.tree.as.IClassNode; |
| import org.apache.flex.compiler.tree.as.IDefinitionNode; |
| import org.apache.flex.compiler.tree.metadata.IMetaTagNode; |
| |
| /** |
| * The base class for all definitions. |
| * <p> |
| * A definition is something in source code that can be referred to by name: |
| * a package, namespace, class, interface, function, getter, setter, |
| * parameter, variable, constant, event, style, or effect. |
| * <p> |
| * <p> |
| * Each definition has |
| * <ul> |
| * <li>a source location;</li> |
| * <li>an optional list of metadata annotations;</li> |
| * <li>a namespace reference indicating its visibility, |
| * such as <code>public</code>;</li> |
| * <li>a set of flags indicating modifiers such as <code>static</code> |
| * or <code>override</code>;</li> |
| * <li>a base, or unqualified, name;</li> |
| * <li>a type reference (which may be <code>null</code> |
| * for some types of definitions.</li> |
| * </ul> |
| * Specific types of definitions of course store additional information. |
| * For example, a class definition stores a reference to the class it extends |
| * and references to the interfaces that it implements. |
| * <p> |
| * Definitions refer to other definitions indirectly, by name, |
| * using an <code>IReference</code>. See the <code>references</code> |
| * subpackage for an explanation of this design. |
| */ |
| public interface IDefinition |
| { |
| /** |
| * Gets the local source path of the entire definition (not just the name). |
| * It is normalized. |
| * |
| * @return An <code>String<code> for the path. |
| */ |
| String getSourcePath(); |
| |
| /** |
| * Gets the local starting offset of the entire definition (not just the |
| * name). It is zero-based. |
| * |
| * @return An <code>int</code> for the offset. |
| */ |
| int getStart(); |
| |
| /** |
| * Gets the local ending offset of this entire definition (not just the |
| * name). It is zero-based. |
| * |
| * @return An <code>int</code> for the offset. |
| */ |
| int getEnd(); |
| |
| /** |
| * Gets the local line number of this entire definition (not just the name). |
| * It is zero-based. |
| * |
| * @return An <code>int</code> for the line number. |
| */ |
| int getLine(); |
| |
| /** |
| * Gets the local column number of the entire definition (not just the |
| * name). It is zero-based. |
| * |
| * @return An <code>int</code> for the column number. |
| */ |
| int getColumn(); |
| |
| /** |
| * Gets the absolute starting offset of the entire definition (not just the |
| * name). It is zero-based. |
| * |
| * @return An <code>int</code> for the offset. |
| */ |
| int getAbsoluteStart(); |
| |
| /** |
| * Gets the absolute ending offset of the entire definition (not just the |
| * name). It is zero-based. |
| * |
| * @return An <code>int</code> for the offset. |
| */ |
| int getAbsoluteEnd(); |
| |
| /** |
| * Gets the base (i.e., unqualified) name of this definition. |
| * <p> |
| * For example, the base name of the class definition |
| * for the class <code>flash.display.Sprite</code> |
| * is <code>"Sprite"</code>. |
| * |
| * @return The base name as a String. |
| */ |
| String getBaseName(); |
| |
| /** |
| * Gets the fully-qualified package name for this definition. |
| * <p> |
| * For example, the backage name of the class definition |
| * for the class <code>flash.display.Sprite</code> |
| * is <code>"flash.display"</code> |
| * |
| * @return The fully-qualified package name as a String. |
| */ |
| String getPackageName(); |
| |
| /** |
| * Gets the fully-qualified name of this definition. |
| * <p> |
| * For example, the fully-qualified name of the class definition |
| * for the class <code>flash.display.Sprite</code> is |
| * <code>"flash.display.Sprite"</code>. |
| * |
| * @return The fully-qualified name as a String. |
| */ |
| String getQualifiedName(); |
| |
| /** |
| * Gets the local starting offset of the name of this definition. It is |
| * zero-based. |
| * |
| * @return An <code>int</code> for the offset. |
| */ |
| int getNameStart(); |
| |
| /** |
| * Gets the local ending offset of the name of this definition. It is |
| * zero-based. |
| * |
| * @return An <code>int</code> for the offset. |
| */ |
| int getNameEnd(); |
| |
| /** |
| * Gets the local line number of the name of this definition. It is |
| * zero-based. |
| * |
| * @return An <code>int</code> for the line number. |
| */ |
| int getNameLine(); |
| |
| /** |
| * Gets the local column number of the name of this definition. It is |
| * zero-based. |
| * |
| * @return An <code>int</code> for the column number. |
| */ |
| int getNameColumn(); |
| |
| /** |
| * Gets the scope in which this definition exists. |
| * |
| * @return An IASScope for the containing scope, or <code>null</code> if |
| * this definition has not yet been added to a scope. |
| */ |
| IASScope getContainingScope(); |
| |
| /** |
| * Gets the parent definition of this definition. |
| * |
| * @return An IDefinition for the parent, or <code>null</code> if there is |
| * no parent. |
| */ |
| IDefinition getParent(); |
| |
| /** |
| * Gets an ancestor definition of this definition. |
| * <p> |
| * This method walks up the chain of parent definitions and returns the |
| * first one having the specified type. |
| * |
| * @param ancestorType A Class specifying the desired type of ancestor. |
| * @return An IDefinition for the ancestor. |
| */ |
| IDefinition getAncestorOfType(Class<? extends IDefinition> ancestorType); |
| |
| /** |
| * Gets the file path in which this definition is defined. |
| * |
| * @return A String for the file path. |
| */ |
| String getContainingFilePath(); |
| |
| /** |
| * Gets the source file path in which this definition is defined. |
| * <p> |
| * For definitions from a source file (like *.as), the result is the same as |
| * {@link #getContainingFilePath()}. |
| * <p> |
| * If the definition is from a SWC library, and the library source path was |
| * set, the result is the file path in the source directory. If the source |
| * path was not set, the result is null. |
| * |
| * @param project the containing project |
| * @return A String for the file path. |
| */ |
| String getContainingSourceFilePath(ICompilerProject project); |
| |
| /** |
| * Is this definition marked as <code>dynamic</code>? |
| * |
| * @return <code>true</code> if the definition is <code>dynamic</code>. |
| */ |
| boolean isDynamic(); |
| |
| /** |
| * Is this definition marked as <code>final</code>? |
| * |
| * @return <code>true</code> if the definition is <code>final</code>. |
| */ |
| boolean isFinal(); |
| |
| /** |
| * Is this definition marked as <code>native</code>? |
| * |
| * @return <code>true</code> if the definition is <code>native</code>. |
| */ |
| boolean isNative(); |
| |
| /** |
| * Is this definition marked as <code>override</code>? |
| * |
| * @return <code>true</code> if the definition is <code>override</code>. |
| */ |
| boolean isOverride(); |
| |
| /** |
| * Is this definition marked as <code>static</code>? |
| * |
| * @return <code>true</code> if the definition is <code>static</code>. |
| */ |
| boolean isStatic(); |
| |
| /** |
| * Determines whether the specified modifier is present on this definition. |
| * See {@link ASModifier} for the list of modifiers. |
| * |
| * @return <code>true</code> if the modifier is present. |
| */ |
| boolean hasModifier(ASModifier modifier); |
| |
| ModifiersSet getModifiers(); |
| |
| /** |
| * Determines whether the specified namespace is present on this definition. |
| * <p> |
| * Namespaces include <code>public</code>, <code>private</code>, |
| * <code>protected</code>, and <code>internal</code>, plus any custom |
| * namespaces available in the definition's scope. |
| * <p> |
| * The namespace is specified by an INamespaceReference, which can represent |
| * not only a custom namespace like <code>ns1</code> but also |
| * <code>ns1::ns2</code>, <code>(ns1::ns2)::ns3</code>, etc. |
| * |
| * @param namespace An INamespaceReference specifying the namespace to check |
| * for. |
| * @return <code>true</code> if the namespace is present. |
| */ |
| boolean hasNamespace(INamespaceReference namespace, ICompilerProject project); |
| |
| /** |
| * Gets the namespace that this definition belongs to. |
| * |
| * @return An INamespaceReference representing the namespace. For some |
| * built-in namespaces, you can: |
| * <code>== NamespaceDefinition.getPublic()</code>, |
| * <code>instanceof IPublicNamespaceDefinition</code>, |
| * <code>instanceof IProtectedNamespaceDefinition</code>, or For a custom |
| * namespace, the INamespaceReference will represent an expression of the |
| * form <code>ns1</code>, <code>ns1::ns2</code>, |
| * <code>(ns1::ns2)::ns3</code>, etc. |
| */ |
| INamespaceReference getNamespaceReference(); |
| |
| /** |
| * Resolves the namespace specified for this definition to its |
| * INamespaceDefinition. Built-in namespaces will return <code>null</code>. |
| * |
| * @return An {@link INamespaceDefinition} or <code>null</code>. |
| */ |
| INamespaceDefinition resolveNamespace(ICompilerProject project); |
| |
| /** |
| * Determines whether this definition is in a public namespace. |
| * |
| * @return <code>true</code> if it is. |
| */ |
| boolean isPublic(); |
| |
| /** |
| * Determines whether this definition is in a private namespace. |
| * |
| * @return <code>true</code> if it is. |
| */ |
| boolean isPrivate(); |
| |
| /** |
| * Determines whether this definition is in a protected namespace. |
| * |
| * @return <code>true</code> if it is. |
| */ |
| boolean isProtected(); |
| |
| /** |
| * Determines whether this definition is in an internal namespace. |
| * |
| * @return <code>true</code> if it is. |
| */ |
| boolean isInternal(); |
| |
| /** |
| * Gets a reference to the type of this definition. |
| * <p> |
| * For a constant, variable, parameter, getter, or setter definition, |
| * the type reference is determined by the type annotation. |
| * For example, for a variable declaration like <code>var i:int</code>, |
| * the type reference is a reference to the <code>int</code> class. |
| * (For a setter, the relevant type annotation is on the parameter, |
| * not the return type, which is supposed to be <code>void</code>.) |
| * If the type annotation is missing, the reference is <code>null</code>. |
| * <p> |
| * For a function definition, the type reference is always |
| * to the <code>Function</code> class. You must use the |
| * <code>getReturnTypeReference()</code> method of |
| * <code>FunctionDefinition</code> to get the function's return type. |
| * <p> |
| * For a rest parameter, the type reference is always |
| * to the <code>Array</code> class. |
| * <p> |
| * For a package, class, or interface definition, |
| * the type reference is <code>null</code>. |
| * <p> |
| * For style and event definitions, the type reference |
| * is determined by the <code>type</code> attribute in the metadata. |
| * |
| * @return An {@link IReference} to a class or interface. |
| */ |
| IReference getTypeReference(); |
| |
| /** |
| * Resolves the type of this definition to an {@link ITypeDefinition}. |
| * |
| * @param project The {@link ICompilerProject} within which references are |
| * to be resolved. |
| * @return An {@link ITypeDefinition} or <code>null</code> |
| */ |
| ITypeDefinition resolveType(ICompilerProject project); |
| |
| /** |
| * Converts this definition's type reference to a human-readable String. |
| * <p> |
| * If the definition does not have a type reference, |
| * this method returns the empty string. |
| * <p> |
| * This method should only be used for displaying types in problems, |
| * and not for making semantic decisions. |
| * |
| * @return The result of calling {@link IReference#getDisplayString}() |
| * on the {@link IReference} returned by {@link #getTypeReference}(). |
| */ |
| String getTypeAsDisplayString(); |
| |
| /** |
| * Is this definition an implicit definition that doesn't actually appear in |
| * the source file? Examples include <code>this</code>, <code>super</code>, |
| * default constructors, and cast functions. |
| */ |
| boolean isImplicit(); |
| |
| /** |
| * Gets all the {@link IMetaTagNode} objects that match the given name |
| * |
| * @param name the name to match, such as Event, Style, IconFile, etc |
| * @return an array of {@link IMetaTagNode} objects, or empty array (never |
| * null) |
| */ |
| IMetaTag[] getMetaTagsByName(String name); |
| |
| /** |
| * Returns all the {@link IMetaTagNode} objects as an array |
| * |
| * @return an array of objects, or an empty array |
| */ |
| IMetaTag[] getAllMetaTags(); |
| |
| /** |
| * Determines if a specific {@link IMetaTagNode} exists in this collection |
| * |
| * @param name the name of the tag |
| * @return true if it exists |
| */ |
| boolean hasMetaTagByName(String name); |
| |
| /** |
| * Returns the first {@link IMetaTagNode} matching the given name |
| * |
| * @param name the name to search for |
| * @return an {@link IMetaTagNode} or null |
| */ |
| IMetaTag getMetaTagByName(String name); |
| |
| /** |
| * Returns the {@link IDefinitionNode} from which this definition was |
| * created, if the definition came from the AST for a source file. |
| * <p> |
| * This method may require the AST to be reloaded or regenerated and |
| * therefore may be slow. |
| * <p> |
| * More specific definition interfaces such as {@link IClassDefinition} |
| * redeclare this method to return a more specific node interface such as |
| * {@link IClassNode}. |
| */ |
| IDefinitionNode getNode(); |
| |
| /** |
| * Whether this definition was specified as "Bindable" in its metadata |
| * |
| * @return true if this definition is Bindable. |
| */ |
| boolean isBindable(); |
| |
| /** |
| * @return a collection of Bindable event names, if any were specified in |
| * the metadata |
| */ |
| List<String> getBindableEventNames(); |
| |
| /** |
| * @return true if this definition has metadata [Bindable(style="true")] |
| */ |
| boolean isBindableStyle(); |
| |
| /** |
| * @return true if contingent definition |
| */ |
| boolean isContingent(); |
| |
| /** |
| * @return <code>true</code> if this definition is for an auto-generated |
| * embed class (i.e., one created for a <code>var</code> with |
| * <code>[Embed(...)]</code> metadata). |
| */ |
| boolean isGeneratedEmbedClass(); |
| |
| /** |
| * Check if the contingent definition is needed |
| * |
| * @param project |
| * @return true is the contingent definition is needed |
| */ |
| boolean isContingentNeeded(ICompilerProject project); |
| |
| /** |
| * Checks if this definition is deprecated. |
| * |
| * @return <code>true</code> if it has <code>[Deprecated]</code> metadata. |
| */ |
| boolean isDeprecated(); |
| |
| /** |
| * Gets the information in the definition's <code>[Deprecated]</code> metadata. |
| * |
| * @return An {@link IDeprecationInfo} object. |
| */ |
| IDeprecationInfo getDeprecationInfo(); |
| |
| /** |
| * Debugging method that can be used to assert that a definition is a specified project. |
| * @param project |
| * @return true if this definition is in the specified project. |
| */ |
| boolean isInProject(ICompilerProject project); |
| } |