1 /******************************************************************************* 2 * Copyright (c) 2000, 2006 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.core; 12 13 /** 14 * A Java model region describes a hierarchical set of elements. 15 * Regions are often used to describe a set of elements to be considered 16 * when performing operations; for example, the set of elements to be 17 * considered during a search. A region may include elements from different 18 * projects. 19 * <p> 20 * When an element is included in a region, all of its children 21 * are considered to be included. Children of an included element 22 * <b>cannot</b> be selectively excluded. 23 * </p> 24 * <p> 25 * This interface is not intended to be implemented by clients. 26 * Instances can be created via the <code>JavaCore.newRegion</code>. 27 * </p> 28 * 29 * @see JavaCore#newRegion() 30 */ 31 public interface IRegion { 32 /** 33 * Adds the given element and all of its descendents to this region. 34 * If the specified element is already included, or one of its 35 * ancestors is already included, this has no effect. If the element 36 * being added is an ancestor of an element already contained in this 37 * region, the ancestor subsumes the descendent. 38 * 39 * @param element the given element 40 */ 41 void add(IJavaElement element); 42 /** 43 * Returns whether the given element is contained in this region. 44 * 45 * @param element the given element 46 * @return true if the given element is contained in this region, false otherwise 47 */ 48 boolean contains(IJavaElement element); 49 /** 50 * Returns the top level elements in this region. 51 * All descendents of these elements are also included in this region. 52 * 53 * @return the top level elements in this region 54 */ 55 IJavaElement[] getElements(); 56 /** 57 * Removes the specified element from the region and returns 58 * <code>true</code> if successful, <code>false</code> if the remove 59 * fails. If an ancestor of the given element is included, the 60 * remove fails (in other words, it is not possible to selectively 61 * exclude descendants of included ancestors). 62 * 63 * @param element the given element 64 * @return <code>true</code> if successful, <code>false</code> if the remove fails 65 */ 66 boolean remove(IJavaElement element); 67 } 68