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 com.tomgibara.pronto.util.Duration;
21  
22  /**
23   * <p>
24   * Implementations of this interface may be passed to a control factory to
25   * create a controller that responds to instructions from STDIN (<code>System.in</code>).
26   * When new input on STDIN is received by the controller, any control
27   * instructions it contains are executed.
28   * </p>
29   * 
30   * <p>
31   * Such a controller could be used to control a Java application via a shell
32   * pipe, or provide a user with a simple interface with which to control
33   * execution.
34   * </p>
35   * 
36   * <p>
37   * Each line submitted on STDIN should consist of a label-name optionally
38   * followed by a parameter. Blank lines and leading spaces are ignored. An
39   * example line to a controller might be:
40   * </p>
41   * 
42   * <code>stop 20s</code>
43   * 
44   * <p>
45   * The interpretation of this line is entirely determined by the controller's
46   * engine and its corresponding adapter.
47   * </p>
48   * 
49   * <p>
50   * Lines supplied on STDIN are subject to a maximum length - this is intended to
51   * protect a Java application from excessive memory usage caused by long lines
52   * of input. See the documentation on pronto properties for more information
53   * about how to change this maximum length.
54   * </p>
55   * 
56   * <p>
57   * Note that the values returned for settings do <em>not</em> need to be
58   * stable; they can change between calls on the interface.
59   * </p>
60   * 
61   * 
62   * @author Tom Gibara
63   * 
64   */
65  
66  public interface StdinControllerSettings extends ControllerSettings {
67  
68      /**
69       * The approximate time between successive checks for new input on STDIN.
70       * Polling is necessary because there is no reliable cross-platform way of
71       * performing non-blocking IO on STDIN from Java. Returning a null value
72       * from this method indicates that the default value should be used. Refer
73       * to the documentation on pronto properties to find out the default value.
74       * 
75       * @return the polling period on STDIN, or null
76       */
77  
78      Duration getCheckPeriod();
79  
80      /**
81       * Whether the input on STDIN is user interactive. There is no way to
82       * identify whether the <code>System.in</code> stream is obtaining input
83       * from a user or a pipe. Returning a true value from this method will cause
84       * the controller to report input-errors to STDOUT, otherwise input errors
85       * are logged to the standard package logger.
86       * 
87       * @return true if STDIN should be treated as interactive, false otherwise
88       */
89  
90      boolean isInteractive();
91  
92  }