1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32 package com.unitesk.atp.text.generation;
33
34 /***
35 * The text generator that process text patterns and generates text.
36 * See {@link #txt(String)} for the description of patterns.
37 *
38 * @author <A href="mailto:demakov@ispras.ru">Alexey Demakov</A>
39 * @version $Id: Generator.java,v 1.2 2004/10/11 15:00:43 all-x Exp $
40 */
41 public interface Generator
42 {
43 String DEFAULT_NAME = "";
44
45 /***
46 * Registers function for the usage in patterns.
47 *
48 * @param name The name of function.
49 * Must be {@link com.unitesk.atp.dynattrs.Accessor#isID(String) valid identifier}
50 * or empty string.
51 * @param func The implementation of function.
52 * @return If function with this name was registered already - return it.
53 * Otherwise return <code>null</code>.
54 */
55 Function setFunction( String name, Function func );
56
57 /***
58 * Returns function by name.
59 *
60 * @param name The name of function.
61 * @return If function with this name is registered - return it.
62 * Otherwise return <code>null</code>.
63 */
64 Function getFunction( String name );
65
66 /***
67 * Registers variable for the usage in patterns.
68 *
69 * @param name The name of variable.
70 * Must be {@link com.unitesk.atp.dynattrs.Accessor#isID(String) valid identifier}
71 * or empty string.
72 * @param var The value of variable.
73 * @return If variable with this name was registered already - return it.
74 * Otherwise return <code>null</code>.
75 */
76 Object setVariable( String name, Object var );
77
78 /***
79 * Returns variable by name.
80 *
81 * @param name The name of variable.
82 * @return If variable with this name is registered - return it.
83 * Otherwise return <code>null</code>.
84 */
85 Object getVariable( String name );
86
87 /***
88 * Processes text pattern and generates text.
89 * The pattern has parameters of the following form:
90 * <P><BLOCKQUOTE><code>
91 * pattern ::= "${" ( <func:ID> ":" )? ( "." )? path "}" ;<BR>
92 * path ::= attribute ( "." attribute )* ;<BR>
93 * attribute ::= <attr_name:ID> ( "[" index "]" )? ;<BR>
94 * index ::= <index_var:ID> | number ;<BR>
95 * number ::= ( "-" )? ( <digit> )+ ;<BR>
96 * </BLOCKQUOTE></code>
97 * The parameter of pattern is processed in the following way:
98 * <UL>
99 * <LI>If variable <code>var</code> is specified use it as an attributed object
100 * otherwise use the current variable.</LI>
101 * <LI>Find attribute value specified by attributed object
102 * and attribute <code>path</code></LI>
103 * <LI>If <code>func</code> is specified use it
104 * otherwise use the default function.
105 * Run the function at the attribute value.</LI>
106 * </UL>
107 *
108 * @param str The specified pattern.
109 * @throws UndefinedFunctionException
110 * If function name is undefined.
111 * @throws com.unitesk.atp.beanutils.PropertyException
112 * When problem with attribute path occurs.
113 * @see #getFunction(String)
114 * @see #getVariable(String)
115 */
116 void txt( String str );
117
118 /***
119 * Print string as is, don't treat it as pattern.
120 * This method is used for printing values of parameters.
121 *
122 * @param str The string to pass as is.
123 */
124 void txtAsIs( String str );
125 }