1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17 package org.apache.jetspeed.rewriter;
18
19 import java.io.Reader;
20 import java.io.Writer;
21
22 /***
23 * Rewriter
24 *
25 * @author <a href="mailto:taylor@apache.org">David Sean Taylor</a>
26 * @version $Id: Rewriter.java 516448 2007-03-09 16:25:47Z ate $
27 */
28 public interface Rewriter
29 {
30 /***
31 * Parses the reader of content receiving call backs for rewriter events.
32 * This method does not rewrite, but only parses. Useful for readonly operations.
33 * The configured parser can parse over different stream formats returning a
34 * normalized (org.sax.xml) attribute and element based events.
35 *
36 * @param adaptor the parser adaptor which handles generating SAX-like events called back on this object.
37 * @param reader the input stream over the content to be parsed.
38 * @exception RewriteException when a parsing error occurs or unexpected content is found.
39 */
40 void parse(ParserAdaptor adaptor, Reader reader)
41 throws RewriterException;
42
43 /***
44 * Parses the reader of content receiving call backs for rewriter events.
45 * The content is rewritten to the output stream.
46 * The configured parser can parse over different stream formats returning a
47 * normalized (org.sax.xml) attribute and element based events.
48 *
49 * @param adaptor the parser adaptor which handles generating SAX-like events called back on this object.
50 * @param reader the input stream over the content to be parsed.
51 * @param writer the output stream where content is rewritten to.
52 * @exception RewriteException when a parsing error occurs or unexpected content is found.
53 */
54 void rewrite(ParserAdaptor adaptor, Reader reader, Writer writer)
55 throws RewriterException;
56
57
58 /***
59 * This event is the inteface between the Rewriter and ParserAdaptor for rewriting URLs.
60 * The ParserAdaptor calls back the Rewriter when it finds a URL that is a candidate to be
61 * rewritten. The Rewriter rewrites the URL and returns it as the result of this function.
62 *
63 * @param url the URL to be rewritten
64 * @param tag The tag being processed
65 * @param attribute The current attribute being processsed
66 */
67 String rewriteUrl(String url, String tag, String attribute);
68
69 /***
70 * Returns true if the tag should be removed, otherwise false.
71 * Removing a tag only removes the tag but not the contents in
72 * between the start and end tag.
73 *
74 * @return true if the tag should be removed.
75 */
76 boolean shouldRemoveTag(String tag);
77
78 /***
79 * Returns true if the tag should be stripped, otherwise false.
80 * Stripping tags removes the start and end tag, plus all tags
81 * and content in between the start and end tag.
82 *
83 * @return true if the tag should be stripped.
84 */
85 boolean shouldStripTag(String tag);
86
87 /***
88 * Returns true if all comments should be removed.
89 *
90 * @return true If all comments should be removed.
91 */
92 boolean shouldRemoveComments();
93
94 /***
95 * Sets the base URL for rewriting. This URL is the base
96 * from which other URLs are generated.
97 *
98 * @param base The base URL for this rewriter
99 */
100 void setBaseUrl(String base);
101
102 /***
103 * Gets the base URL for rewriting. This URL is the base
104 * from which other URLs are generated.
105 *
106 * @return The base URL for this rewriter
107 */
108 String getBaseUrl();
109
110 /***
111 * Gets a new URL relative to Base according to the site / and URL
112 * rewriting rules of java.net.URL
113 *
114 * @return The new URL from path, relative to the base URL (or path, if path is absolute)
115 */
116 String getBaseRelativeUrl(String path);
117
118 /***
119 * Gets whether this rewriter require a proxy server.
120 *
121 * @return true if it requires a proxy
122 */
123 boolean getUseProxy();
124
125 /***
126 * Set whether this rewriter require a proxy server.
127 *
128 * @param useProxy true if it requires a proxy
129 */
130 void setUseProxy(boolean useProxy);
131
132 /***
133 * Rewriter event called back on the leading edge of processing a simple tag by the ParserAdaptor.
134 * Returns false to indicate to the ParserAdaptor to short-circuit processing on this tag.
135 *
136 * @param tag The name of the tag being processed.
137 * @param attrs The attribute list for the tag.
138 * @return Should return true to continue processing the tag in the ParserAdaptor, false to indicate that processing is completed.
139 */
140 boolean enterSimpleTagEvent(String tag, MutableAttributes attrs);
141
142 /***
143 * Rewriter event called back on the trailing edge of a simple tag by the ParserAdaptor.
144 * Returns a String that can be appended to the rewritten output for the given tag, or null to indicate no content available.
145 *
146 * @param tag The name of the tag being processed.
147 * @param attrs The attribute list for the tag.
148 * @return Returns a String that can be appended to the rewritten output for the given tag, or null to indicate no content available.
149 */
150 String exitSimpleTagEvent(String tag, MutableAttributes attrs);
151
152 /***
153 * Rewriter event called back on the leading edge of processing a start tag by the ParserAdaptor.
154 * Returns false to indicate to the ParserAdaptor to short-circuit processing on this tag.
155 *
156 * @param tag The name of the tag being processed.
157 * @param attrs The attribute list for the tag.
158 * @return Should return true to continue processing the tag in the ParserAdaptor, false to indicate that processing is completed.
159 */
160 boolean enterStartTagEvent(String tag, MutableAttributes attrs);
161
162 /***
163 * Rewriter event called back on the trailing edge of a start tag by the ParserAdaptor.
164 * Returns a String that can be appended to the rewritten output for the given tag, or null to indicate no content available.
165 *
166 * @param tag The name of the tag being processed.
167 * @param attrs The attribute list for the tag.
168 * @return Returns a String that can be appended to the rewritten output for the given tag, or null to indicate no content available.
169 */
170 String exitStartTagEvent(String tag, MutableAttributes attrs);
171
172 /***
173 * Rewriter event called back on the leading edge of processing an end tag by the ParserAdaptor.
174 * Returns false to indicate to the ParserAdaptor to short-circuit processing on this tag.
175 *
176 * @param tag The name of the tag being processed.
177 * @param attrs The attribute list for the tag.
178 * @return Should return true to continue processing the tag in the ParserAdaptor, false to indicate that processing is completed.
179 */
180 boolean enterEndTagEvent(String tag);
181
182 /***
183 * Rewriter event called back on the trailing edge of a end tag by the ParserAdaptor.
184 * Returns a String that can be appended to the rewritten output for the given tag, or null to indicate no content available.
185 *
186 * @param tag The name of the tag being processed.
187 * @param attrs The attribute list for the tag.
188 * @return Returns a String that can be appended to the rewritten output for the given tag, or null to indicate no content available.
189 */
190 String exitEndTagEvent(String tag);
191
192 /***
193 * Rewriter event called back when text is found for
194 * Returns false to indicate to the ParserAdaptor to short-circuit processing on this tag.
195 *
196 * @param values an array of characters containing the text.
197 * @param param
198 * @return Should return true to continue processing the tag in the ParserAdaptor, false to indicate that processing is completed.
199 */
200 boolean enterText(char[] values, int param);
201
202 /***
203 * Rewriter event called back just before tag conversion (rewriter callbacks) begins by the ParserAdaptor.
204 *
205 * @param tag The name of the tag being processed.
206 * @param attrs The attribute list for the tag.
207 */
208 void enterConvertTagEvent(String tag, MutableAttributes attrs);
209
210 }