1 /****************************************************************
2 * Licensed to the Apache Software Foundation (ASF) under one *
3 * or more contributor license agreements. See the NOTICE file *
4 * distributed with this work for additional information *
5 * regarding copyright ownership. The ASF licenses this file *
6 * to you under the Apache License, Version 2.0 (the *
7 * "License"); you may not use this file except in compliance *
8 * with the License. You may obtain a copy of the License at *
9 * *
10 * http://www.apache.org/licenses/LICENSE-2.0 *
11 * *
12 * Unless required by applicable law or agreed to in writing, *
13 * software distributed under the License is distributed on an *
14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY *
15 * KIND, either express or implied. See the License for the *
16 * specific language governing permissions and limitations *
17 * under the License. *
18 ****************************************************************/
19 package org.apache.jsieve.util;
20
21 /**
22 * Presents a high level reporting view of a Sieve node tree.
23 * Familiarity with
24 * <a href='http://www.ietf.org/rfc/rfc3028.txt'>Sieve</a> is assumed
25 * (but not of the internals of the
26 * <a href='http://james.apache.org/jsieve/'>JSieve</a> implementation).
27 * Anyone who requires a low level, <code>JSieve</code> specific view
28 * should see {@link NodeHandler}
29 *
30 * @see NodeTraverser
31 * @see NodeHandler
32 */
33 public interface SieveHandler {
34
35 /**
36 * Handles the start of a Sieve script.
37 * @throws HaltTraversalException
38 * @return this
39 */
40 public SieveHandler startScript() throws HaltTraversalException;
41
42 /**
43 * Handles the end of a Sieve script.
44 * @throws HaltTraversalException
45 * @return this
46 */
47 public SieveHandler endScript() throws HaltTraversalException;
48
49 /**
50 * Handles the start of a block.
51 * @throws HaltTraversalException
52 * @return this
53 */
54 public SieveHandler startBlock() throws HaltTraversalException;
55
56 /**
57 * Handles the end of a block.
58 * @throws HaltTraversalException
59 * @return this
60 */
61 public SieveHandler endBlock() throws HaltTraversalException;
62
63 /**
64 * Handles the start of a block of commands.
65 * @throws HaltTraversalException
66 * @return this
67 */
68 public SieveHandler startCommands() throws HaltTraversalException;
69
70 /**
71 * Handles the end of a block of commands.
72 * @throws HaltTraversalException
73 * @return this
74 */
75 public SieveHandler endCommands() throws HaltTraversalException;
76
77 /**
78 * Handles the start of a command.
79 * @param commandName name identifying the command
80 * @throws HaltTraversalException
81 * @return this
82 */
83 public SieveHandler startCommand(String commandName) throws HaltTraversalException;
84
85 /**
86 * Handles the end of a command.
87 * @param commandName name identifying the command
88 * @throws HaltTraversalException
89 * @return this
90 */
91 public SieveHandler endCommand(String commandName) throws HaltTraversalException;
92
93
94 /**
95 * Handles the start of a block of arguments.
96 * @throws HaltTraversalException
97 * @return this
98 */
99 public SieveHandler startArguments() throws HaltTraversalException;
100
101 /**
102 * Handles the end of a block of arguments.
103 * @throws HaltTraversalException
104 * @return this
105 */
106 public SieveHandler endArguments() throws HaltTraversalException;
107
108 /**
109 * Handles a tag argument.
110 * Note that this supplies the identifier for the tag
111 * (after the leading ':' has been stripped).
112 * @param identifier not null
113 * @throws HaltTraversalException
114 * @return this
115 */
116 public SieveHandler argument(String identifier) throws HaltTraversalException;
117
118 /**
119 * Handler a numeric argument.
120 * @param number not null
121 * @throws HaltTraversalException
122 * @return this
123 */
124 public SieveHandler argument(int number) throws HaltTraversalException;
125
126 /**
127 * Handles the start of an argument which is a list of strings.
128 * @throws HaltTraversalException
129 * @return this
130 */
131 public SieveHandler startStringListArgument() throws HaltTraversalException;
132
133 /**
134 * Handles the end of an argument which is a list of strings.
135 * @throws HaltTraversalException
136 * @return this
137 */
138 public SieveHandler endStringListArgument() throws HaltTraversalException;
139
140 /**
141 * One string from a list.
142 * @param string not null
143 * @throws HaltTraversalException
144 * @return this
145 */
146 public SieveHandler listMember(String string) throws HaltTraversalException;
147
148 /**
149 * Handles the start of a list of tests.
150 * @throws HaltTraversalException
151 * @return this
152 */
153 public SieveHandler startTestList() throws HaltTraversalException;
154
155 /**
156 * Handles the end of a list of tests.
157 * @throws HaltTraversalException
158 * @return this
159 */
160 public SieveHandler endTestList() throws HaltTraversalException;
161
162 /**
163 * Handles the start of a test.
164 * @param testName name identifying the test
165 * @throws HaltTraversalException
166 * @return this
167 */
168 public SieveHandler startTest(String testName) throws HaltTraversalException;
169
170 /**
171 * Handles the end of a test.
172 * @param testName name identifying the test
173 * @throws HaltTraversalException
174 * @return this
175 */
176 public SieveHandler endTest(String testName) throws HaltTraversalException;
177
178 /**
179 * Convenience basic implementation.
180 * All methods do nothing.
181 */
182 public abstract static class Base implements SieveHandler {
183
184 public SieveHandler argument(int number) throws HaltTraversalException {
185 return this;
186 }
187
188 public SieveHandler argument(String tag) throws HaltTraversalException {
189 return this;
190 }
191
192 public SieveHandler endArguments() throws HaltTraversalException {
193 return this;
194 }
195
196 public SieveHandler endBlock() throws HaltTraversalException {
197 return this;
198 }
199
200 public SieveHandler endCommand(String commandName) throws HaltTraversalException {
201 return this;
202 }
203
204 public SieveHandler endCommands() throws HaltTraversalException {
205 return this;
206 }
207
208 public SieveHandler endScript() throws HaltTraversalException {
209 return this;
210 }
211
212 public SieveHandler endStringListArgument() throws HaltTraversalException {
213 return this;
214 }
215
216 public SieveHandler endTest(String testName) throws HaltTraversalException {
217 return this;
218 }
219
220 public SieveHandler endTestList() throws HaltTraversalException {
221 return this;
222 }
223
224 public SieveHandler listMember(String string) throws HaltTraversalException {
225 return this;
226 }
227
228 public SieveHandler startArguments() throws HaltTraversalException {
229 return this;
230 }
231
232 public SieveHandler startBlock() throws HaltTraversalException {
233 return this;
234 }
235
236 public SieveHandler startCommand(String commandName) throws HaltTraversalException {
237 return this;
238 }
239
240 public SieveHandler startCommands() throws HaltTraversalException {
241 return this;
242 }
243
244 public SieveHandler startScript() throws HaltTraversalException {
245 return this;
246 }
247
248 public SieveHandler startStringListArgument() throws HaltTraversalException {
249 return this;
250 }
251
252 public SieveHandler startTest(String testName) throws HaltTraversalException {
253 return this;
254 }
255
256 public SieveHandler startTestList() throws HaltTraversalException {
257 return this;
258 }
259 }
260 }