case-study/jdt-after/core extension/org/eclipse/jdt/internal/corext/dom/fragments/IASTFragment.java

   1 /*******************************************************************************
   2  * Copyright (c) 2000, 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 package org.eclipse.jdt.internal.corext.dom.fragments;
  12
  13 import org.eclipse.text.edits.TextEditGroup;
  14
  15 import org.eclipse.jdt.core.dom.ASTNode;
  16 import org.eclipse.jdt.core.dom.rewrite.ASTRewrite;
  17
  18 /**
  19  * An IASTFragment represents 'part' of an AST, but
  20  * not necessarily a subtree of the AST.  A fragment
  21  * may simply be an instance of some sort of pattern
  22  * or formation in an AST.
  23  * Such "fragments", however, do correspond to a
  24  * contiguous source code region, and, thus, posses a
  25  * source start position, and a source length.  Every
  26  * fragment maps to an ASTNode, although this mapping is
  27  * not necessarily straightforward, and more than one
  28  * fragment may map to a given node.
  29  *
  30  * Fragments support abstract operations, which
  31  * support the notion of 'matching' fragments.
  32  * One operation determines whether a fragment 'matches'
  33  * a given fragment.  Another operation finds all
  34  * sub-fragments (fragments contained within a
  35  * parent fragment, including the parent itself)
  36  * which 'match' another given fragment.
  37  *
  38  */
  39 public interface IASTFragment {
  40
  41         /**
  42          * Determines whether <code> other </code>
  43          * 'matches' <code> this </code>.
  44          * This binary operation should be reflexive,
  45          * symmetric, and transitive.
  46          *
  47          * That two node match does not imply that their source ranges
  48          * are the same, or that they map (via getAssociatedNode()) to the
  49          * same node.
  50          * @param other the element to test with
  51          * @return return <code> true if the passed element matches the current element.
  52          */
  53         public boolean matches(IASTFragment other);
  54
  55         /**
  56          * Returns (at least some approximation of) a maximal set of
  57          * sub-fragments of this fragment which match <code> toMatch </code>
  58          * @param toMatch the fragment to match
  59          * @return set of sub fragments that match
  60          */
  61         public IASTFragment[] getSubFragmentsMatching(IASTFragment toMatch);
  62
  63         /**
  64          * Every fragment maps to a node.
  65          * Multiple fragments can map to the same node.
  66          *
  67          * @return ASTNode The node to which this fragment maps.
  68          */
  69         public ASTNode getAssociatedNode();
  70
  71         /**
  72          * Every fragment has a source start position.
  73          *
  74          * @return int          The source start position.
  75          */
  76         public int getStartPosition();
  77
  78         /**
  79          * Every fragment has a source length.
  80          *
  81          * @return int          The source length.
  82          */
  83         public int getLength();
  84
  85         /**
  86          * Replaces this fragment with the given replacement node.
  87          *
  88          * @param rewrite an ASTRewrite
  89          * @param replacement replacement for this fragment
  90          * @param textEditGroup a description or <code>null</code>
  91          */
  92         public void replace(ASTRewrite rewrite, ASTNode replacement, TextEditGroup textEditGroup);
  93 }