01: package org.drools.lang;
02:
03: import java.io.IOException;
04: import java.io.Reader;
05: import java.util.List;
06:
07: import org.drools.lang.dsl.DSLMapping;
08:
09: /*
10: * Copyright 2005 JBoss Inc
11: *
12: * Licensed under the Apache License, Version 2.0 (the "License");
13: * you may not use this file except in compliance with the License.
14: * You may obtain a copy of the License at
15: *
16: * http://www.apache.org/licenses/LICENSE-2.0
17: *
18: * Unless required by applicable law or agreed to in writing, software
19: * distributed under the License is distributed on an "AS IS" BASIS,
20: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
21: * See the License for the specific language governing permissions and
22: * limitations under the License.
23: */
24:
25: /**
26: * Expanders are extension points for expanding
27: * expressions in DRL at parse time.
28: * This is just-in-time translation, or macro expansion, or
29: * whatever you want.
30: *
31: * The important thing is that it happens at the last possible moment,
32: * so any errors in expansion are included in the parsers errors.
33: *
34: * Just-in-time expansions may include complex pre-compilers,
35: * or just macros, and everything in between.
36: *
37: * Expanders should ideally not make presumptions on any embedded semantic
38: * language. For instance, java aware pre processing should be done in
39: * drools-java semantic module, not in the parser itself. Expanders should
40: * be reusable across semantic languages.
41: *
42: * @author Michael Neale
43: *
44: */
45: public interface Expander {
46:
47: /**
48: * Expands (process) the expression Just-In-Time for the parser.
49: * If the source is not meant to be expanded, or if no
50: * appropriate match was found for expansion, it will echo back
51: * the same expression.
52: *
53: * @param drl the source code to be pre-processed
54: * @return source code after running pre-processors
55: */
56: public String expand(Reader drl) throws IOException;
57:
58: /**
59: * Expands (process) the expression Just-In-Time for the parser.
60: * If the source is not meant to be expanded, or if no
61: * appropriate match was found for expansion, it will echo back
62: * the same expression.
63: *
64: * @param source the source code to be expanded
65: * @return source code after running pre-processors
66: */
67: public String expand(String source);
68:
69: /**
70: * Add the new mapping to this expander.
71: * @param mapping
72: */
73: public void addDSLMapping(DSLMapping mapping);
74:
75: /**
76: * Returns the list of errors from the last expansion made
77: * @return A list of <code>ExpanderException</code>
78: */
79: public List getErrors();
80:
81: /**
82: * Returns true in case the last expansion had any errors
83: * @return
84: */
85: public boolean hasErrors();
86:
87: }
|