1 package org.apache.struts.flow.core.location;
2
3 import java.util.List;
4
5 /***
6 * An extension of {@link Location} for classes that can hold a list of locations.
7 * It will typically be used to build location stacks.
8 * <p>
9 * The <em>first</em> location of the collection returned by {@link #getLocations()} should be
10 * be identical to the result of {@link org.apache.struts.flow.core.location.Locatable#getLocation()}.
11 * <p>
12 * If the list of locations designates a call stack, then its first element should be the deepmost
13 * location of this stack. This is consistent with the need for <code>getLocation()</code> to
14 * return the most precise location.
15 *
16 * @since 2.1.8
17 * @version $Id: MultiLocatable.java 233343 2005-08-18 18:06:44Z sylvain $
18 */
19 public interface MultiLocatable extends Locatable {
20
21 /***
22 * Return the list of locations.
23 *
24 * @return a list of locations, possibly empty but never null.
25 */
26 public List getLocations();
27
28 /***
29 * Add a location to the current list of locations.
30 * <p>
31 * Implementations are free to filter locations that can be added (e.g. {@link Location#UNKNOWN}),
32 * and there is therefore no guarantee that the given location will actually be added to the list.
33 * Filtered locations are silently ignored.
34 *
35 * @param location the location to be added.
36 */
37 public void addLocation(Location location);
38
39 }