View Javadoc

1   /*
2    * Copyright (C) 2006  Tom Gibara
3    *
4    * This library is free software; you can redistribute it and/or
5    * modify it under the terms of the GNU Lesser General Public
6    * License as published by the Free Software Foundation; either
7    * version 2.1 of the License, or (at your option) any later version.
8    *
9    * This library is distributed in the hope that it will be useful,
10   * but WITHOUT ANY WARRANTY; without even the implied warranty of
11   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
12   * Lesser General Public License for more details.
13   *
14   * You should have received a copy of the GNU Lesser General Public
15   * License along with this library; if not, write to the Free Software
16   * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
17   */
18  
19  package com.tomgibara.pronto.state;
20  
21  import com.tomgibara.pronto.core.ProntoException;
22  import com.tomgibara.pronto.core.impl.StaticProperties;
23  import com.tomgibara.pronto.util.FactoryHelper;
24  
25  /**
26   * <p>
27   * This class is used to obtain graphs and engines to manage state transitions.
28   * </p>
29   * 
30   * <p>
31   * The idiom for using this package is to obtain an instance of this factory and
32   * from that an empty state graph. Then to obtain an editor on that graph
33   * through which any permitted states and transitions are added. And finally to
34   * combine that state graph with an activator in an engine that will manage
35   * state the transitions.
36   * </p>
37   * 
38   * <p>
39   * Only one instance of a StateFactory is available through the
40   * <code>getInstance()</code> method. The default implementation returned by
41   * this static method can be changed by assigning the system property
42   * <code>com.tomgibara.pronto.state.factory</code> the name of a class which
43   * extends this abstract base class.
44   * </p>
45   * 
46   * @author Tom Gibara
47   * 
48   */
49  
50  public abstract class StateFactory {
51  
52      // statics
53  
54      /** The default factory class name. */
55      private static final String CLASS = StaticProperties.getString("pronto.state.factory-class");
56  
57      /** The property name from which a different class name can be obtained. */
58      private static final String PROPERTY = StaticProperties.getString("pronto.state.factory-property");
59  
60      /** A factory helper object which does the work of instantiating the class. */
61      private static final FactoryHelper<StateFactory> HELPER = new FactoryHelper<StateFactory>(CLASS, null, PROPERTY);
62  
63      /**
64       * Should be called to obtain a <code>StateFactory</code> instance. This
65       * method is the single entry-point to state management functionality in the
66       * pronto framework.
67       * 
68       * @return the single instance of this factory
69       * 
70       * @throws ProntoException
71       *             if the factory instance could not be created
72       */
73  
74      public static StateFactory getInstance() throws ProntoException {
75          try {
76              return HELPER.getInstance();
77          } catch (Exception e) {
78              throw new ProntoException("previously recorded exception: " + e.getMessage(), e);
79          }
80      }
81  
82      // factory methods
83  
84      /**
85       * Creates an empty state graph from which an editor is typically obtained
86       * to build any required state graph.
87       * 
88       * @param <S>
89       *            the type of states the state graph editor will permit
90       * @param <L>
91       *            the type of labels the state graph editor will permit
92       * 
93       * @return a state graph containing no states
94       */
95  
96      public abstract <S, L> StateGraph<S, L> emptyStateGraph();
97  
98      /**
99       * Combines a graph and activator to form a new engine.
100      * 
101      * @param <S>
102      *            the type of states in the graph
103      * @param <L>
104      *            the type of labels in the graph
105      * @param <P>
106      *            the type of parameters accepted by the activator
107      * 
108      * @param graph
109      *            the graph of states and transitions permitted by the engine
110      * @param activator
111      *            an object that can 'act' in response to state changes
112      * 
113      * @return a new engine which can transition over the graph of states
114      *         subject to execution of the activator
115      */
116 
117     public abstract <S, L, P> StateEngine<S, L, P> newEngine(StateGraph<S, L> graph, StateActivator<S, L, P> activator);
118 
119 }