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  package com.tomgibara.pronto.control;
19  
20  import java.text.ParseException;
21  
22  /**
23   * <p>
24   * Implementations of this interface provide a controller with string
25   * representations of a state engine's labels. The label names returned from
26   * this interface must, by default, match the following pattern:
27   * </p>
28   * 
29   * <code>^[\p{javaLowerCase}\p{javaUpperCase}\p{Digit}-_]+$</code>
30   * 
31   * <p>
32   * This pattern can be changed via the pronto static properties.
33   * </p>
34   * 
35   * <p>
36   * It is strongly advised (though not mandatory) that the mapping provided be
37   * one-to-one.
38   * </p>
39   * 
40   * @author Tom Gibara
41   * 
42   */
43  
44  public interface EngineControlAdapter<S, L, P> {
45  
46      /**
47       * Provides a string representation of a supplied label.
48       * 
49       * @param label
50       *            a label in the controller's state graph
51       * @return the name for the label, or null if the label has no name
52       */
53  
54      // TODO this methods is not called anywhere - use it or lose it
55      String nameFromLabel(L label);
56  
57      /**
58       * Returns the label with the supplied name.
59       * 
60       * @param name
61       *            a name supplied to the controller
62       * @return the label so named, or null if there is no label with that name
63       */
64  
65      L labelFromName(String name);
66  
67      /**
68       * Returns a parameter string that is supplied to the controller into a
69       * parameter object that can be used to perform transitions.
70       * 
71       * @param string
72       *            the string representation of the parameter that was supplied
73       *            to the controller, or null if there was no parameter specified
74       * @return the parameter object that corresponds to the supplied string, or
75       *         null
76       * @throws ParseException
77       *             if the supplied string could not be parsed into a valid
78       *             parameter object
79       */
80      P parseParameter(String string) throws ParseException;
81  }