01: /*
02: * Licensed to the Apache Software Foundation (ASF) under one or more
03: * contributor license agreements. See the NOTICE file distributed with
04: * this work for additional information regarding copyright ownership.
05: * The ASF licenses this file to You under the Apache License, Version 2.0
06: * (the "License"); you may not use this file except in compliance with
07: * the License. You may obtain a copy of the License at
08: *
09: * 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;
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 446917 2006-09-16 19:10:40Z vgritsenko $
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 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: }
|