01: /*
02: * Copyright 2000,2005 wingS development team.
03: *
04: * This file is part of wingS (http://wingsframework.org).
05: *
06: * wingS is free software; you can redistribute it and/or modify
07: * it under the terms of the GNU Lesser General Public License
08: * as published by the Free Software Foundation; either version 2.1
09: * of the License, or (at your option) any later version.
10: *
11: * Please see COPYING for the complete licence.
12: */
13: package org.wings.template;
14:
15: import java.io.IOException;
16: import java.io.InputStream;
17:
18: /**
19: * A TemplateSource for a Template. This encapsulates what is the notion
20: * of a template from the parsers point of view: some named entity, that
21: * might change over time and thus has a modification time; an input stream
22: * to access the contents.
23: * <p/>
24: * So <CODE>TemplateSource</CODE> is a general source where templates can come
25: * from. You can think of Files, URLs, Database-BLOBS ..
26: *
27: * @author <A href="mailto:H.Zeller@acm.org">Henner Zeller</A>
28: */
29: public interface TemplateSource {
30: /**
31: * Returns a canonical name of this TemplateSource.
32: * <p/>
33: * The name returned here is used to look up the parsing
34: * result of the internal caching, so it should differ
35: * for all different Sources :-)
36: * May return <code>null</code> if this Source is supposed
37: * to be parsed each time. The canonical name would be something
38: * like a filename or an URL.
39: *
40: * @return the canonical name of the source. like 'file:/web/template.html'
41: */
42: String getCanonicalName();
43:
44: /**
45: * Returns the time the content of this TemplateSource
46: * was last modified.
47: * <p/>
48: * The return value is used to decide whether to reparse a
49: * Source or not. Reparsing is done if the value returned
50: * here <em>differs</em> from the value returned at the last processing
51: * time. This may not return a 'real' time, it needs just
52: * to be comparable to itself; so some sort of version counter instead
53: * of time would be perfect as well.
54: *
55: * @return long a modification time
56: */
57: long lastModified();
58:
59: /**
60: * Gets an InputStream of this TemplateSource.
61: * <p/>
62: * <em>Note</em>
63: * that this method may be called twice if the page has to
64: * be parsed first. So you probably have to implement a
65: * buffer if your underlying source is transient ..
66: *
67: * @return an InputStream the content of the template is read from.
68: */
69: InputStream getInputStream() throws IOException;
70: }
|