Source code: com/phoenixst/plexus/TraverserFactory.java
1 /*
2 * $Id: TraverserFactory.java,v 1.2 2003/09/24 21:38:09 rconner Exp $
3 *
4 * Copyright (C) 1994-2003 by Phoenix Software Technologists,
5 * Inc. and others. All rights reserved.
6 *
7 * THIS PROGRAM AND DOCUMENTATION IS PROVIDED UNDER THE TERMS OF THE
8 * COMMON PUBLIC LICENSE ("AGREEMENT") WHICH ACCOMPANIES IT. ANY
9 * USE, REPRODUCTION OR DISTRIBUTION OF THE PROGRAM CONSTITUTES
10 * RECIPIENT'S ACCEPTANCE OF THE AGREEMENT.
11 *
12 * The license text can also be found at
13 * http://opensource.org/licenses/cpl.php
14 */
15
16 package com.phoenixst.plexus;
17
18
19 /**
20 * An interface used to encapsulate a particular type of {@link
21 * Traverser}, so that it may be used without knowledge of its
22 * implementation. See {@link java.util.Comparator} for a similar,
23 * but simpler, information hiding construct used in ordering
24 * collections.
25 *
26 * <P>This allows graph algorithms to not have different
27 * implementations for undirected, forward directed, and reverse
28 * directed traversals, for example. The user may also create custom
29 * <code>TraverserFactory</code> objects to be used in non-trivial
30 * traversals. As an example, a graph representing a system of roads
31 * may be traversed by only following four-lane highways (a
32 * particular sort of object contained in the graph's edges), and the
33 * traversal may still be performed using a generic algorithm.
34 *
35 * <P>This interface is a trivially small example of the <i>Abstract
36 * Factory</i> pattern (see <i>Design Patterns</i>, by Gamma,
37 * et. al.).
38 *
39 * @version $Revision: 1.2 $
40 * @author Ray A. Conner
41 *
42 * @since 1.0
43 */
44 public interface TraverserFactory
45 {
46
47 /**
48 * Returns a <code>Traverser</code> initialized using
49 * <code>graph</code> and <code>node</code>.
50 *
51 * @param graph initial graph argument.
52 *
53 * @param node initial node argument.
54 *
55 * @return a <code>Traverser</code> initialized using
56 * <code>graph</code> and <code>node</code>.
57 *
58 * @throws ClassCastException if <code>node</code> is of an
59 * inappropriate type for <code>graph</code>, or if
60 * <code>graph</code> is of an inapporpriate type for this
61 * factory instance.
62 *
63 * @throws IllegalArgumentException if some aspect of
64 * <code>graph</code> or <code>node</code> prevent this factory
65 * from creating a <code>Traverser</code>.
66 *
67 * @throws NoSuchNodeException if <code>node</code> is not
68 * present in <code>graph</code>.
69 *
70 * @throws NullPointerException if <code>graph</code> is
71 * <code>null</code>, or if <code>node</code> is
72 * <code>null</code> and <code>graph</code> does not not permit
73 * <code>null</code> nodes.
74 */
75 public Traverser createTraverser( Graph graph, Object node );
76
77 }