View Javadoc

1   /*
2    * Copyright (c) 2001-2004,
3    * RedVerst Group, ISP RAS http://www.ispras.ru
4    * All rights reserved.
5    *
6    * Redistribution and use in source and binary forms, with or without
7    * modification, are permitted provided that the following conditions are met:
8    *
9    * 1. Redistributions of source code must retain the above copyright notice, this
10   *    list of conditions and the following disclaimer.
11   *
12   * 2. Redistributions in binary form must reproduce the above copyright notice,
13   *    this list of conditions and the following disclaimer in the documentation
14   *    and/or other materials provided with the distribution.
15   *
16   * 3. The names "ATP", "TreeDL", "RedVerst", "ISP RAS"
17   *    may not be used to endorse or promote products derived from this software
18   *    without specific prior written permission.
19   *
20   * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
21   * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
22   * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
23   * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
24   * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
25   * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
26   * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
27   * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
28   * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
29   * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
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   ::= "${" ( &lt;func:ID&gt; ":" )? ( "." )? path "}" ;<BR>
92       * path      ::= attribute ( "." attribute )* ;<BR>
93       * attribute ::= &lt;attr_name:ID&gt; ( "[" index "]" )? ;<BR>
94       * index     ::= &lt;index_var:ID&gt; | number ;<BR>
95       * number    ::= ( "-" )? ( &lt;digit&gt; )+ ;<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 }