langtools/src/share/classes/com/sun/source/util/TreePath.java
author jjg
Wed, 25 Jun 2014 19:04:52 -0700
changeset 25287 d2440361b323
parent 20612 4761f3ff7afb
permissions -rw-r--r--
8046614: Fill in missing doc comments Reviewed-by: darcy
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
10
06bc494ca11e Initial load
duke
parents:
diff changeset
     1
/*
25287
d2440361b323 8046614: Fill in missing doc comments
jjg
parents: 20612
diff changeset
     2
 * Copyright (c) 2006, 2014, Oracle and/or its affiliates. All rights reserved.
10
06bc494ca11e Initial load
duke
parents:
diff changeset
     3
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
06bc494ca11e Initial load
duke
parents:
diff changeset
     4
 *
06bc494ca11e Initial load
duke
parents:
diff changeset
     5
 * This code is free software; you can redistribute it and/or modify it
06bc494ca11e Initial load
duke
parents:
diff changeset
     6
 * under the terms of the GNU General Public License version 2 only, as
5520
86e4b9a9da40 6943119: Rebrand source copyright notices
ohair
parents: 3149
diff changeset
     7
 * published by the Free Software Foundation.  Oracle designates this
10
06bc494ca11e Initial load
duke
parents:
diff changeset
     8
 * particular file as subject to the "Classpath" exception as provided
5520
86e4b9a9da40 6943119: Rebrand source copyright notices
ohair
parents: 3149
diff changeset
     9
 * by Oracle in the LICENSE file that accompanied this code.
10
06bc494ca11e Initial load
duke
parents:
diff changeset
    10
 *
06bc494ca11e Initial load
duke
parents:
diff changeset
    11
 * This code is distributed in the hope that it will be useful, but WITHOUT
06bc494ca11e Initial load
duke
parents:
diff changeset
    12
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
06bc494ca11e Initial load
duke
parents:
diff changeset
    13
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
06bc494ca11e Initial load
duke
parents:
diff changeset
    14
 * version 2 for more details (a copy is included in the LICENSE file that
06bc494ca11e Initial load
duke
parents:
diff changeset
    15
 * accompanied this code).
06bc494ca11e Initial load
duke
parents:
diff changeset
    16
 *
06bc494ca11e Initial load
duke
parents:
diff changeset
    17
 * You should have received a copy of the GNU General Public License version
06bc494ca11e Initial load
duke
parents:
diff changeset
    18
 * 2 along with this work; if not, write to the Free Software Foundation,
06bc494ca11e Initial load
duke
parents:
diff changeset
    19
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
06bc494ca11e Initial load
duke
parents:
diff changeset
    20
 *
5520
86e4b9a9da40 6943119: Rebrand source copyright notices
ohair
parents: 3149
diff changeset
    21
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
86e4b9a9da40 6943119: Rebrand source copyright notices
ohair
parents: 3149
diff changeset
    22
 * or visit www.oracle.com if you need additional information or have any
86e4b9a9da40 6943119: Rebrand source copyright notices
ohair
parents: 3149
diff changeset
    23
 * questions.
10
06bc494ca11e Initial load
duke
parents:
diff changeset
    24
 */
06bc494ca11e Initial load
duke
parents:
diff changeset
    25
06bc494ca11e Initial load
duke
parents:
diff changeset
    26
package com.sun.source.util;
06bc494ca11e Initial load
duke
parents:
diff changeset
    27
14258
8d2148961366 8000663: clean up langtools imports
jjg
parents: 5520
diff changeset
    28
import java.util.Iterator;
8d2148961366 8000663: clean up langtools imports
jjg
parents: 5520
diff changeset
    29
10
06bc494ca11e Initial load
duke
parents:
diff changeset
    30
import com.sun.source.tree.*;
06bc494ca11e Initial load
duke
parents:
diff changeset
    31
06bc494ca11e Initial load
duke
parents:
diff changeset
    32
/**
06bc494ca11e Initial load
duke
parents:
diff changeset
    33
 * A path of tree nodes, typically used to represent the sequence of ancestor
06bc494ca11e Initial load
duke
parents:
diff changeset
    34
 * nodes of a tree node up to the top level CompilationUnitTree node.
06bc494ca11e Initial load
duke
parents:
diff changeset
    35
 *
06bc494ca11e Initial load
duke
parents:
diff changeset
    36
 * @author Jonathan Gibbons
06bc494ca11e Initial load
duke
parents:
diff changeset
    37
 * @since 1.6
06bc494ca11e Initial load
duke
parents:
diff changeset
    38
 */
20612
4761f3ff7afb 8025913: Rename jdk.Supported to jdk.Exported
darcy
parents: 18664
diff changeset
    39
@jdk.Exported
10
06bc494ca11e Initial load
duke
parents:
diff changeset
    40
public class TreePath implements Iterable<Tree> {
06bc494ca11e Initial load
duke
parents:
diff changeset
    41
    /**
25287
d2440361b323 8046614: Fill in missing doc comments
jjg
parents: 20612
diff changeset
    42
     * Returns a tree path for a tree node within a compilation unit,
d2440361b323 8046614: Fill in missing doc comments
jjg
parents: 20612
diff changeset
    43
     * or {@code null} if the node is not found.
d2440361b323 8046614: Fill in missing doc comments
jjg
parents: 20612
diff changeset
    44
     * @param unit the compilation unit to search
d2440361b323 8046614: Fill in missing doc comments
jjg
parents: 20612
diff changeset
    45
     * @param target the node to locate
d2440361b323 8046614: Fill in missing doc comments
jjg
parents: 20612
diff changeset
    46
     * @return the tree path
10
06bc494ca11e Initial load
duke
parents:
diff changeset
    47
     */
06bc494ca11e Initial load
duke
parents:
diff changeset
    48
    public static TreePath getPath(CompilationUnitTree unit, Tree target) {
06bc494ca11e Initial load
duke
parents:
diff changeset
    49
        return getPath(new TreePath(unit), target);
06bc494ca11e Initial load
duke
parents:
diff changeset
    50
    }
06bc494ca11e Initial load
duke
parents:
diff changeset
    51
06bc494ca11e Initial load
duke
parents:
diff changeset
    52
    /**
25287
d2440361b323 8046614: Fill in missing doc comments
jjg
parents: 20612
diff changeset
    53
     * Returns a tree path for a tree node within a subtree identified by a TreePath object.
d2440361b323 8046614: Fill in missing doc comments
jjg
parents: 20612
diff changeset
    54
     * Returns {@code null} if the node is not found.
d2440361b323 8046614: Fill in missing doc comments
jjg
parents: 20612
diff changeset
    55
     * @param path the path in which to search
d2440361b323 8046614: Fill in missing doc comments
jjg
parents: 20612
diff changeset
    56
     * @param target the node to locate
d2440361b323 8046614: Fill in missing doc comments
jjg
parents: 20612
diff changeset
    57
     * @return the tree path of the target node
10
06bc494ca11e Initial load
duke
parents:
diff changeset
    58
     */
06bc494ca11e Initial load
duke
parents:
diff changeset
    59
    public static TreePath getPath(TreePath path, Tree target) {
06bc494ca11e Initial load
duke
parents:
diff changeset
    60
        path.getClass();
06bc494ca11e Initial load
duke
parents:
diff changeset
    61
        target.getClass();
06bc494ca11e Initial load
duke
parents:
diff changeset
    62
06bc494ca11e Initial load
duke
parents:
diff changeset
    63
        class Result extends Error {
06bc494ca11e Initial load
duke
parents:
diff changeset
    64
            static final long serialVersionUID = -5942088234594905625L;
06bc494ca11e Initial load
duke
parents:
diff changeset
    65
            TreePath path;
06bc494ca11e Initial load
duke
parents:
diff changeset
    66
            Result(TreePath path) {
06bc494ca11e Initial load
duke
parents:
diff changeset
    67
                this.path = path;
06bc494ca11e Initial load
duke
parents:
diff changeset
    68
            }
06bc494ca11e Initial load
duke
parents:
diff changeset
    69
        }
14952
d0022ae20516 8004832: Add new doclint package
jjg
parents: 14258
diff changeset
    70
10
06bc494ca11e Initial load
duke
parents:
diff changeset
    71
        class PathFinder extends TreePathScanner<TreePath,Tree> {
06bc494ca11e Initial load
duke
parents:
diff changeset
    72
            public TreePath scan(Tree tree, Tree target) {
14952
d0022ae20516 8004832: Add new doclint package
jjg
parents: 14258
diff changeset
    73
                if (tree == target) {
10
06bc494ca11e Initial load
duke
parents:
diff changeset
    74
                    throw new Result(new TreePath(getCurrentPath(), target));
14952
d0022ae20516 8004832: Add new doclint package
jjg
parents: 14258
diff changeset
    75
                }
10
06bc494ca11e Initial load
duke
parents:
diff changeset
    76
                return super.scan(tree, target);
06bc494ca11e Initial load
duke
parents:
diff changeset
    77
            }
06bc494ca11e Initial load
duke
parents:
diff changeset
    78
        }
06bc494ca11e Initial load
duke
parents:
diff changeset
    79
14952
d0022ae20516 8004832: Add new doclint package
jjg
parents: 14258
diff changeset
    80
        if (path.getLeaf() == target) {
d0022ae20516 8004832: Add new doclint package
jjg
parents: 14258
diff changeset
    81
            return path;
d0022ae20516 8004832: Add new doclint package
jjg
parents: 14258
diff changeset
    82
        }
d0022ae20516 8004832: Add new doclint package
jjg
parents: 14258
diff changeset
    83
10
06bc494ca11e Initial load
duke
parents:
diff changeset
    84
        try {
06bc494ca11e Initial load
duke
parents:
diff changeset
    85
            new PathFinder().scan(path, target);
06bc494ca11e Initial load
duke
parents:
diff changeset
    86
        } catch (Result result) {
06bc494ca11e Initial load
duke
parents:
diff changeset
    87
            return result.path;
06bc494ca11e Initial load
duke
parents:
diff changeset
    88
        }
06bc494ca11e Initial load
duke
parents:
diff changeset
    89
        return null;
06bc494ca11e Initial load
duke
parents:
diff changeset
    90
    }
06bc494ca11e Initial load
duke
parents:
diff changeset
    91
06bc494ca11e Initial load
duke
parents:
diff changeset
    92
    /**
06bc494ca11e Initial load
duke
parents:
diff changeset
    93
     * Creates a TreePath for a root node.
25287
d2440361b323 8046614: Fill in missing doc comments
jjg
parents: 20612
diff changeset
    94
     * @param node the root node
10
06bc494ca11e Initial load
duke
parents:
diff changeset
    95
     */
25287
d2440361b323 8046614: Fill in missing doc comments
jjg
parents: 20612
diff changeset
    96
    public TreePath(CompilationUnitTree node) {
d2440361b323 8046614: Fill in missing doc comments
jjg
parents: 20612
diff changeset
    97
        this(null, node);
10
06bc494ca11e Initial load
duke
parents:
diff changeset
    98
    }
06bc494ca11e Initial load
duke
parents:
diff changeset
    99
06bc494ca11e Initial load
duke
parents:
diff changeset
   100
    /**
06bc494ca11e Initial load
duke
parents:
diff changeset
   101
     * Creates a TreePath for a child node.
25287
d2440361b323 8046614: Fill in missing doc comments
jjg
parents: 20612
diff changeset
   102
     * @param path the parent path
d2440361b323 8046614: Fill in missing doc comments
jjg
parents: 20612
diff changeset
   103
     * @param tree the child node
10
06bc494ca11e Initial load
duke
parents:
diff changeset
   104
     */
25287
d2440361b323 8046614: Fill in missing doc comments
jjg
parents: 20612
diff changeset
   105
    public TreePath(TreePath path, Tree tree) {
d2440361b323 8046614: Fill in missing doc comments
jjg
parents: 20612
diff changeset
   106
        if (tree.getKind() == Tree.Kind.COMPILATION_UNIT) {
d2440361b323 8046614: Fill in missing doc comments
jjg
parents: 20612
diff changeset
   107
            compilationUnit = (CompilationUnitTree) tree;
10
06bc494ca11e Initial load
duke
parents:
diff changeset
   108
            parent = null;
06bc494ca11e Initial load
duke
parents:
diff changeset
   109
        }
06bc494ca11e Initial load
duke
parents:
diff changeset
   110
        else {
25287
d2440361b323 8046614: Fill in missing doc comments
jjg
parents: 20612
diff changeset
   111
            compilationUnit = path.compilationUnit;
d2440361b323 8046614: Fill in missing doc comments
jjg
parents: 20612
diff changeset
   112
            parent = path;
10
06bc494ca11e Initial load
duke
parents:
diff changeset
   113
        }
25287
d2440361b323 8046614: Fill in missing doc comments
jjg
parents: 20612
diff changeset
   114
        leaf = tree;
10
06bc494ca11e Initial load
duke
parents:
diff changeset
   115
    }
06bc494ca11e Initial load
duke
parents:
diff changeset
   116
    /**
25287
d2440361b323 8046614: Fill in missing doc comments
jjg
parents: 20612
diff changeset
   117
     * Returns the compilation unit associated with this path.
d2440361b323 8046614: Fill in missing doc comments
jjg
parents: 20612
diff changeset
   118
     * @return the compilation unit
10
06bc494ca11e Initial load
duke
parents:
diff changeset
   119
     */
06bc494ca11e Initial load
duke
parents:
diff changeset
   120
    public CompilationUnitTree getCompilationUnit() {
06bc494ca11e Initial load
duke
parents:
diff changeset
   121
        return compilationUnit;
06bc494ca11e Initial load
duke
parents:
diff changeset
   122
    }
06bc494ca11e Initial load
duke
parents:
diff changeset
   123
06bc494ca11e Initial load
duke
parents:
diff changeset
   124
    /**
25287
d2440361b323 8046614: Fill in missing doc comments
jjg
parents: 20612
diff changeset
   125
     * Returns the leaf node for this path.
d2440361b323 8046614: Fill in missing doc comments
jjg
parents: 20612
diff changeset
   126
     * @return the leaf node
10
06bc494ca11e Initial load
duke
parents:
diff changeset
   127
     */
06bc494ca11e Initial load
duke
parents:
diff changeset
   128
    public Tree getLeaf() {
06bc494ca11e Initial load
duke
parents:
diff changeset
   129
        return leaf;
06bc494ca11e Initial load
duke
parents:
diff changeset
   130
    }
06bc494ca11e Initial load
duke
parents:
diff changeset
   131
06bc494ca11e Initial load
duke
parents:
diff changeset
   132
    /**
25287
d2440361b323 8046614: Fill in missing doc comments
jjg
parents: 20612
diff changeset
   133
     * Returns the path for the enclosing node, or {@code null} if there is no enclosing node.
d2440361b323 8046614: Fill in missing doc comments
jjg
parents: 20612
diff changeset
   134
     * @return the path for the enclosing node
10
06bc494ca11e Initial load
duke
parents:
diff changeset
   135
     */
06bc494ca11e Initial load
duke
parents:
diff changeset
   136
    public TreePath getParentPath() {
06bc494ca11e Initial load
duke
parents:
diff changeset
   137
        return parent;
06bc494ca11e Initial load
duke
parents:
diff changeset
   138
    }
06bc494ca11e Initial load
duke
parents:
diff changeset
   139
18664
5c35de99f6df 6473148: TreePath.iterator() should document the iteration order
vromero
parents: 16303
diff changeset
   140
    /**
5c35de99f6df 6473148: TreePath.iterator() should document the iteration order
vromero
parents: 16303
diff changeset
   141
     *  Iterates from leaves to root.
5c35de99f6df 6473148: TreePath.iterator() should document the iteration order
vromero
parents: 16303
diff changeset
   142
     */
5c35de99f6df 6473148: TreePath.iterator() should document the iteration order
vromero
parents: 16303
diff changeset
   143
    @Override
10
06bc494ca11e Initial load
duke
parents:
diff changeset
   144
    public Iterator<Tree> iterator() {
06bc494ca11e Initial load
duke
parents:
diff changeset
   145
        return new Iterator<Tree>() {
18664
5c35de99f6df 6473148: TreePath.iterator() should document the iteration order
vromero
parents: 16303
diff changeset
   146
            @Override
10
06bc494ca11e Initial load
duke
parents:
diff changeset
   147
            public boolean hasNext() {
3149
0cd06d598d6f 6843077: JSR 308: Annotations on types
jjg
parents: 10
diff changeset
   148
                return next != null;
10
06bc494ca11e Initial load
duke
parents:
diff changeset
   149
            }
06bc494ca11e Initial load
duke
parents:
diff changeset
   150
18664
5c35de99f6df 6473148: TreePath.iterator() should document the iteration order
vromero
parents: 16303
diff changeset
   151
            @Override
10
06bc494ca11e Initial load
duke
parents:
diff changeset
   152
            public Tree next() {
3149
0cd06d598d6f 6843077: JSR 308: Annotations on types
jjg
parents: 10
diff changeset
   153
                Tree t = next.leaf;
0cd06d598d6f 6843077: JSR 308: Annotations on types
jjg
parents: 10
diff changeset
   154
                next = next.parent;
0cd06d598d6f 6843077: JSR 308: Annotations on types
jjg
parents: 10
diff changeset
   155
                return t;
10
06bc494ca11e Initial load
duke
parents:
diff changeset
   156
            }
06bc494ca11e Initial load
duke
parents:
diff changeset
   157
18664
5c35de99f6df 6473148: TreePath.iterator() should document the iteration order
vromero
parents: 16303
diff changeset
   158
            @Override
10
06bc494ca11e Initial load
duke
parents:
diff changeset
   159
            public void remove() {
06bc494ca11e Initial load
duke
parents:
diff changeset
   160
                throw new UnsupportedOperationException();
06bc494ca11e Initial load
duke
parents:
diff changeset
   161
            }
06bc494ca11e Initial load
duke
parents:
diff changeset
   162
3149
0cd06d598d6f 6843077: JSR 308: Annotations on types
jjg
parents: 10
diff changeset
   163
            private TreePath next = TreePath.this;
10
06bc494ca11e Initial load
duke
parents:
diff changeset
   164
        };
06bc494ca11e Initial load
duke
parents:
diff changeset
   165
    }
06bc494ca11e Initial load
duke
parents:
diff changeset
   166
06bc494ca11e Initial load
duke
parents:
diff changeset
   167
    private CompilationUnitTree compilationUnit;
06bc494ca11e Initial load
duke
parents:
diff changeset
   168
    private Tree leaf;
06bc494ca11e Initial load
duke
parents:
diff changeset
   169
    private TreePath parent;
06bc494ca11e Initial load
duke
parents:
diff changeset
   170
}