01: /*******************************************************************************
02: * Copyright (c) 2000, 2006 IBM Corporation and others.
03: * All rights reserved. This program and the accompanying materials
04: * are made available under the terms of the Eclipse Public License v1.0
05: * which accompanies this distribution, and is available at
06: * http://www.eclipse.org/legal/epl-v10.html
07: *
08: * Contributors:
09: * IBM Corporation - initial API and implementation
10: *******************************************************************************/package org.eclipse.jdt.core;
11:
12: /**
13: * A Java model region describes a hierarchical set of elements.
14: * Regions are often used to describe a set of elements to be considered
15: * when performing operations; for example, the set of elements to be
16: * considered during a search. A region may include elements from different
17: * projects.
18: * <p>
19: * When an element is included in a region, all of its children
20: * are considered to be included. Children of an included element
21: * <b>cannot</b> be selectively excluded.
22: * </p>
23: * <p>
24: * This interface is not intended to be implemented by clients.
25: * Instances can be created via the <code>JavaCore.newRegion</code>.
26: * </p>
27: *
28: * @see JavaCore#newRegion()
29: */
30: public interface IRegion {
31: /**
32: * Adds the given element and all of its descendents to this region.
33: * If the specified element is already included, or one of its
34: * ancestors is already included, this has no effect. If the element
35: * being added is an ancestor of an element already contained in this
36: * region, the ancestor subsumes the descendent.
37: *
38: * @param element the given element
39: */
40: void add(IJavaElement element);
41:
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: /**
51: * Returns the top level elements in this region.
52: * All descendents of these elements are also included in this region.
53: *
54: * @return the top level elements in this region
55: */
56: IJavaElement[] getElements();
57:
58: /**
59: * Removes the specified element from the region and returns
60: * <code>true</code> if successful, <code>false</code> if the remove
61: * fails. If an ancestor of the given element is included, the
62: * remove fails (in other words, it is not possible to selectively
63: * exclude descendants of included ancestors).
64: *
65: * @param element the given element
66: * @return <code>true</code> if successful, <code>false</code> if the remove fails
67: */
68: boolean remove(IJavaElement element);
69: }
|