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