net.sourceforge.phpeclipse/src/net/sourceforge/phpdt/core/dom/MethodRef.java

   1 /*******************************************************************************
   2  * Copyright (c) 2004, 2008 IBM Corporation and others.
   3  * All rights reserved. This program and the accompanying materials
   4  * are made available under the terms of the Eclipse Public License v1.0
   5  * which accompanies this distribution, and is available at
   6  * http://www.eclipse.org/legal/epl-v10.html
   7  *
   8  * Contributors:
   9  *     IBM Corporation - initial API and implementation
  10  *******************************************************************************/
  11
  12 package net.sourceforge.phpdt.core.dom;
  13
  14 import java.util.ArrayList;
  15 import java.util.List;
  16
  17 /**
  18  * AST node for a method or constructor reference within a doc comment
  19  * ({@link Javadoc}). The principal uses of these are in "@see" and "@link"
  20  * tag elements, for references to method and constructor members.
  21  * <pre>
  22  * MethodRef:
  23  *     [ Name ] <b>#</b> Identifier
  24  *         <b>(</b> [ MethodRefParameter | { <b>,</b> MethodRefParameter } ] <b>)</b>
  25  * </pre>
  26  *
  27  * @see Javadoc
  28  * @since 3.0
  29  * @noinstantiate This class is not intended to be instantiated by clients.
  30  */
  31 public class MethodRef extends ASTNode implements IDocElement {
  32
  33         /**
  34          * The "qualifier" structural property of this node type.
  35          * @since 3.0
  36          */
  37         public static final ChildPropertyDescriptor QUALIFIER_PROPERTY =
  38                 new ChildPropertyDescriptor(MethodRef.class, "qualifier", Name.class, OPTIONAL, NO_CYCLE_RISK); //$NON-NLS-1$
  39
  40         /**
  41          * The "name" structural property of this node type.
  42          * @since 3.0
  43          */
  44         public static final ChildPropertyDescriptor NAME_PROPERTY =
  45                 new ChildPropertyDescriptor(MethodRef.class, "name", SimpleName.class, MANDATORY, NO_CYCLE_RISK); //$NON-NLS-1$
  46
  47         /**
  48          * The "parameters" structural property of this node type.
  49          * @since 3.0
  50          */
  51         public static final ChildListPropertyDescriptor PARAMETERS_PROPERTY =
  52                 new ChildListPropertyDescriptor(MethodRef.class, "parameters", MethodRefParameter.class, NO_CYCLE_RISK); //$NON-NLS-1$
  53
  54         /**
  55          * A list of property descriptors (element type:
  56          * {@link StructuralPropertyDescriptor}),
  57          * or null if uninitialized.
  58          */
  59         private static final List PROPERTY_DESCRIPTORS;
  60
  61         static {
  62                 List properyList = new ArrayList(4);
  63                 createPropertyList(MethodRef.class, properyList);
  64                 addProperty(QUALIFIER_PROPERTY, properyList);
  65                 addProperty(NAME_PROPERTY, properyList);
  66                 addProperty(PARAMETERS_PROPERTY, properyList);
  67                 PROPERTY_DESCRIPTORS = reapPropertyList(properyList);
  68         }
  69
  70         /**
  71          * Returns a list of structural property descriptors for this node type.
  72          * Clients must not modify the result.
  73          *
  74          * @param apiLevel the API level; one of the AST.JLS* constants
  75          * @return a list of property descriptors (element type:
  76          * {@link StructuralPropertyDescriptor})
  77          * @since 3.0
  78          */
  79         public static List propertyDescriptors(int apiLevel) {
  80                 return PROPERTY_DESCRIPTORS;
  81         }
  82
  83         /**
  84          * The optional qualifier; <code>null</code> for none; defaults to none.
  85          */
  86         private Name optionalQualifier = null;
  87
  88         /**
  89          * The method name; lazily initialized; defaults to a unspecified,
  90          * legal Java method name.
  91          */
  92         private SimpleName methodName = null;
  93
  94         /**
  95          * The parameter declarations
  96          * (element type: <code>MethodRefParameter</code>).
  97          * Defaults to an empty list.
  98          */
  99         private ASTNode.NodeList parameters =
 100                 new ASTNode.NodeList(PARAMETERS_PROPERTY);
 101
 102
 103         /**
 104          * Creates a new AST node for a method reference owned by the given
 105          * AST. By default, the method reference is for a method with an
 106          * unspecified, but legal, name; no qualifier; and an empty parameter
 107          * list.
 108          * <p>
 109          * N.B. This constructor is package-private; all subclasses must be
 110          * declared in the same package; clients are unable to declare
 111          * additional subclasses.
 112          * </p>
 113          *
 114          * @param ast the AST that is to own this node
 115          */
 116         MethodRef(AST ast) {
 117                 super(ast);
 118         }
 119
 120         /* (omit javadoc for this method)
 121          * Method declared on ASTNode.
 122          */
 123         final List internalStructuralPropertiesForType(int apiLevel) {
 124                 return propertyDescriptors(apiLevel);
 125         }
 126
 127         /* (omit javadoc for this method)
 128          * Method declared on ASTNode.
 129          */
 130         final ASTNode internalGetSetChildProperty(ChildPropertyDescriptor property, boolean get, ASTNode child) {
 131                 if (property == QUALIFIER_PROPERTY) {
 132                         if (get) {
 133                                 return getQualifier();
 134                         } else {
 135                                 setQualifier((Name) child);
 136                                 return null;
 137                         }
 138                 }
 139                 if (property == NAME_PROPERTY) {
 140                         if (get) {
 141                                 return getName();
 142                         } else {
 143                                 setName((SimpleName) child);
 144                                 return null;
 145                         }
 146                 }
 147                 // allow default implementation to flag the error
 148                 return super.internalGetSetChildProperty(property, get, child);
 149         }
 150
 151         /* (omit javadoc for this method)
 152          * Method declared on ASTNode.
 153          */
 154         final List internalGetChildListProperty(ChildListPropertyDescriptor property) {
 155                 if (property == PARAMETERS_PROPERTY) {
 156                         return parameters();
 157                 }
 158                 // allow default implementation to flag the error
 159                 return super.internalGetChildListProperty(property);
 160         }
 161
 162         /* (omit javadoc for this method)
 163          * Method declared on ASTNode.
 164          */
 165         final int getNodeType0() {
 166                 return METHOD_REF;
 167         }
 168
 169         /* (omit javadoc for this method)
 170          * Method declared on ASTNode.
 171          */
 172         ASTNode clone0(AST target) {
 173                 MethodRef result = new MethodRef(target);
 174                 result.setSourceRange(this.getStartPosition(), this.getLength());
 175                 result.setQualifier((Name) ASTNode.copySubtree(target, getQualifier()));
 176                 result.setName((SimpleName) ASTNode.copySubtree(target, getName()));
 177                 result.parameters().addAll(
 178                         ASTNode.copySubtrees(target, parameters()));
 179                 return result;
 180         }
 181
 182         /* (omit javadoc for this method)
 183          * Method declared on ASTNode.
 184          */
 185         final boolean subtreeMatch0(ASTMatcher matcher, Object other) {
 186                 // dispatch to correct overloaded match method
 187                 return matcher.match(this, other);
 188         }
 189
 190         /* (omit javadoc for this method)
 191          * Method declared on ASTNode.
 192          */
 193         void accept0(ASTVisitor visitor) {
 194                 boolean visitChildren = visitor.visit(this);
 195                 if (visitChildren) {
 196                         // visit children in normal left to right reading order
 197                         acceptChild(visitor, getQualifier());
 198                         acceptChild(visitor, getName());
 199                         acceptChildren(visitor, this.parameters);
 200                 }
 201                 visitor.endVisit(this);
 202         }
 203
 204         /**
 205          * Returns the qualifier of this method reference, or
 206          * <code>null</code> if there is none.
 207          *
 208          * @return the qualifier name node, or <code>null</code> if there is none
 209          */
 210         public Name getQualifier() {
 211                 return this.optionalQualifier;
 212         }
 213
 214         /**
 215          * Sets or clears the qualifier of this method reference.
 216          *
 217          * @param name the qualifier name node, or <code>null</code> if
 218          *    there is none
 219          * @exception IllegalArgumentException if:
 220          * <ul>
 221          * <li>the node belongs to a different AST</li>
 222          * <li>the node already has a parent</li>
 223          * </ul>
 224          */
 225         public void setQualifier(Name name) {
 226                 ASTNode oldChild = this.optionalQualifier;
 227                 preReplaceChild(oldChild, name, QUALIFIER_PROPERTY);
 228                 this.optionalQualifier = name;
 229                 postReplaceChild(oldChild, name, QUALIFIER_PROPERTY);
 230         }
 231
 232         /**
 233          * Returns the name of the referenced method or constructor.
 234          *
 235          * @return the method or constructor name node
 236          */
 237         public SimpleName getName() {
 238                 if (this.methodName == null) {
 239                         // lazy init must be thread-safe for readers
 240                         synchronized (this) {
 241                                 if (this.methodName == null) {
 242                                         preLazyInit();
 243                                         this.methodName = new SimpleName(this.ast);
 244                                         postLazyInit(this.methodName, NAME_PROPERTY);
 245                                 }
 246                         }
 247                 }
 248                 return this.methodName;
 249         }
 250
 251         /**
 252          * Sets the name of the referenced method or constructor to the
 253          * given name.
 254          *
 255          * @param name the new method or constructor name node
 256          * @exception IllegalArgumentException if:
 257          * <ul>
 258          * <li>the name is <code>null</code></li>
 259          * <li>the node belongs to a different AST</li>
 260          * <li>the node already has a parent</li>
 261          * </ul>
 262          */
 263         public void setName(SimpleName name) {
 264                 if (name == null) {
 265                         throw new IllegalArgumentException();
 266                 }
 267                 ASTNode oldChild = this.methodName;
 268                 preReplaceChild(oldChild, name, NAME_PROPERTY);
 269                 this.methodName = name;
 270                 postReplaceChild(oldChild, name, NAME_PROPERTY);
 271         }
 272
 273         /**
 274          * Returns the live ordered list of method parameter references for this
 275          * method reference.
 276          *
 277          * @return the live list of method parameter references
 278          *    (element type: <code>MethodRefParameter</code>)
 279          */
 280         public List parameters() {
 281                 return this.parameters;
 282         }
 283
 284         /**
 285          * Resolves and returns the binding for the entity referred to by
 286          * this method reference.
 287          * <p>
 288          * Note that bindings are generally unavailable unless requested when the
 289          * AST is being built.
 290          * </p>
 291          *
 292          * @return the binding, or <code>null</code> if the binding cannot be
 293          *    resolved
 294          */
 295         public final IBinding resolveBinding() {
 296                 return this.ast.getBindingResolver().resolveReference(this);
 297         }
 298
 299         /* (omit javadoc for this method)
 300          * Method declared on ASTNode.
 301          */
 302         int memSize() {
 303                 return BASE_NODE_SIZE + 3 * 4;
 304         }
 305
 306         /* (omit javadoc for this method)
 307          * Method declared on ASTNode.
 308          */
 309         int treeSize() {
 310                 return
 311                         memSize()
 312                         + (this.optionalQualifier == null ? 0 : getQualifier().treeSize())
 313                         + (this.methodName == null ? 0 : getName().treeSize())
 314                         + this.parameters.listSize();
 315         }
 316 }
 317