KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > cocoon > util > location > MultiLocatable


1 /*
2 * Copyright 2005 The Apache Software Foundation or its licensors,
3 * as applicable.
4 *
5 * Licensed under the Apache License, Version 2.0 (the "License");
6 * you may not use this file except in compliance with the License.
7 * You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17 package org.apache.cocoon.util.location;
18
19 import java.util.List JavaDoc;
20
21 /**
22  * An extension of {@link Location} for classes that can hold a list of locations.
23  * It will typically be used to build location stacks.
24  * <p>
25  * The <em>first</em> location of the collection returned by {@link #getLocations()} should be
26  * be identical to the result of {@link org.apache.cocoon.util.location.Locatable#getLocation()}.
27  * <p>
28  * If the list of locations designates a call stack, then its first element should be the deepmost
29  * location of this stack. This is consistent with the need for <code>getLocation()</code> to
30  * return the most precise location.
31  *
32  * @since 2.1.8
33  * @version $Id: MultiLocatable.java 332023 2005-11-09 11:45:47Z crossley $
34  */
35 public interface MultiLocatable extends Locatable {
36     
37     /**
38      * Return the list of locations.
39      *
40      * @return a list of locations, possibly empty but never null.
41      */
42     public List JavaDoc getLocations();
43     
44     /**
45      * Add a location to the current list of locations.
46      * <p>
47      * Implementations are free to filter locations that can be added (e.g. {@link Location#UNKNOWN}),
48      * and there is therefore no guarantee that the given location will actually be added to the list.
49      * Filtered locations are silently ignored.
50      *
51      * @param location the location to be added.
52      */
53     public void addLocation(Location location);
54
55 }
56
Popular Tags