View Javadoc

1   //
2   // Copyright (c) 2003, Caltha - Gajda, Krzewski, Mach, Potempski Sp.J.
3   // All rights reserved.
4   //
5   // Redistribution and use in source and binary forms, with or without modification, 
6   // are permitted provided that the following conditions are met:
7   //
8   // * Redistributions of source code must retain the above copyright notice, 
9   //	 this list of conditions and the following disclaimer.
10  // * Redistributions in binary form must reproduce the above copyright notice, 
11  //	 this list of conditions and the following disclaimer in the documentation 
12  //	 and/or other materials provided with the distribution.
13  // * Neither the name of the Caltha - Gajda, Krzewski, Mach, Potempski Sp.J. 
14  //	 nor the names of its contributors may be used to endorse or promote products 
15  //	 derived from this software without specific prior written permission.
16  //
17  // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 
18  // AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 
19  // WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
20  // IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, 
21  // INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 
22  // BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,
23  // OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 
24  // WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 
25  // ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 
26  // POSSIBILITY OF SUCH DAMAGE.
27  //
28  
29  package org.objectledge.templating;
30  
31  import java.io.Reader;
32  import java.io.Writer;
33  
34  import org.objectledge.ComponentInitializationError;
35  
36  /***
37   * Templating component.
38   *
39   * @author <a href="mailto:pablo@caltha.com">Pawel Potempski</a>
40   * @version $Id: Templating.java,v 1.9 2005/12/20 09:09:31 pablo Exp $
41   */
42  ///CLOVER:OFF
43  public interface Templating
44  {
45      /***
46       * Restart the templating service.
47       * 
48       * @throws ComponentInitializationError if anything goes wrong.
49       * @throws VirtualMachineError if anything goes wrong.
50       * @throws ThreadDeath if anything goes wrong.
51       */
52      public void restart() 
53          throws ComponentInitializationError, VirtualMachineError, ThreadDeath;
54      
55  	/***
56  	 * Create an empty {@link TemplatingContext} object.
57  	 *
58  	 * @return a Context.
59  	 */
60  	public TemplatingContext createContext();
61  
62  	/***
63  	 * Checks if the template with a given name exists.
64  	 *
65  	 * @param name template name.
66  	 * @return <code>true</code> if exists.
67  	 */
68  	public boolean templateExists(String name);
69  
70  	/***
71  	 * Get the specified template.
72  	 *
73  	 * @param name template name.
74  	 * @return the template.
75  	 * @throws TemplateNotFoundException if does not exist.
76  	 */
77  	public Template getTemplate(String name)
78  		throws TemplateNotFoundException;
79  
80  	/***
81  	 * Merge a template dynamically.
82  	 *
83  	 * @param context the templating context.
84  	 * @param source the reader with template source.
85  	 * @param target the writer to write the result.
86  	 * @param name the template name for logging purposes.
87  	 * @throws MergingException if something goes wrong.
88  	 */
89  	public void merge(TemplatingContext context, Reader source, 
90  						  Writer target, String name) 
91  		throws MergingException;
92  		
93  	/***
94  	 * Merge a template.
95  	 *
96  	 * @param context the templating context.
97  	 * @param template the template.
98  	 * @param target the writer to write the result.
99  	 * @throws MergingException if something goes wrong.
100 	 */
101 	public void merge(TemplatingContext context, Template template, Writer target) 
102 		throws MergingException;	
103 		
104 	/***
105 	 * Return the character encoding of the template files.
106 	 *  
107 	 * @return character encoding name.
108 	 */
109 	public String getTemplateEncoding();
110     
111     /***
112      * Invalidate template in local cache.
113      * 
114      * @param name the template name.
115      */
116     public void invalidateTemplate(String name);
117 }