1
2
3
4
5
6
7
8
9
10
11
12 package sk.uniba.euromath.document.schema.plug;
13 import java.util.Iterator;
14 import org.w3c.dom.Element;
15 /***
16 * <p>
17 * Schema returns various information regarding allowed document structure. It
18 * is created for every namespace, and each <code>Schema</code> returns
19 * elements from its namespace only. Because class can be used by multiple
20 * documents simultaneously, each method must be thread-safe.
21 * </p>
22 * <p>
23 * Because of the identification system, in-memory <code>Document</code> is
24 * slightly modified. Schema instance must be aware that:
25 * <ul>
26 * <li>Every element node contains the <code>emp:id</code> attribute (the
27 * <code>http://www.uniba.sk/euromath/reserved</code> namespace)</li>
28 * <li>Schemas doesn't say anything about comments and processing instructions,
29 * so you must ignore these nodes.</li>
30 * </ul>
31 * It is strictly forbidden to modify given document in any way!
32 * </p>
33 * <p>
34 * Document can be changed between any two calls without further notification to
35 * Schema. Thus, Schema must be 'stateless' - it must not change its internal
36 * variables due to document contents. In other hand, it is guaranteed that when
37 * any Schema function is being executed, the document stays unmodified.
38 * </p>
39 * <p>
40 * The schema should be checked for all schema mismatches in the loading time.
41 * The document is valid when some schema method is called and it must be valid
42 * when the suggested modifications are made. Hence the document is always valid
43 * and the only method that is allowed to throw an exception is the
44 * <code>validate()</code> method. However the method may throw an exception
45 * to signalise wrong parameters, invalid document etc (these exceptions
46 * signalise that there is something wrong with plugins or EuroMath itself).
47 * </p>
48 * @author Martin Vysny
49 */
50 public interface ISchema {
51 /***
52 * Returns URI for which the Schema works. Schema may accept
53 * elements/attributes from other namespaces, however it should not attempt
54 * to define their content.
55 * @return URI to which the Schema is bound.
56 */
57 public String getNamespaceUri();
58 /***
59 * Returns list of possible local names of the root elements. URI is fixed
60 * and can be returned with function <code>getNamespaceUri()</code>- root
61 * element automatically belongs to the bounded URI. Caller guarantees that
62 * it won't modify this set. In exchange, Schema must cache this set.
63 * @return set of strings representing local names of the root elements.
64 */
65 public INameListP<INewElementRuleP> getRootElements();
66 /***
67 * <p>
68 * Computes all attributes defined in this schema, regardless of element,
69 * which they are bound to. Returned array must NOT be modifed in any way.
70 * These attributes are called exported - they can be inserted into other
71 * namespaces.
72 * </p>
73 * <p>
74 * This list serves for purpose of adding attributes of this namespace to
75 * elements from another namespace. Thus, if there are 2 or more attributes
76 * defined with same QName in schema, they cannot be returned here. That
77 * would raise ambiguity, because attributes are denoted only by QName, and
78 * we would have to select from more rules.
79 * </p>
80 * <p>
81 * Local attributes have empty URI instead of its own namespace URI, so
82 * empty URI must be replaced by its namespace URI.
83 * </p>
84 * <p>
85 * Result should be computed when object is created.
86 * </p>
87 * @return all attributes of this schema. Result list must contain
88 * <code>AttributeRule</code> instances.
89 */
90 public INameListP<IAttributeRuleP> getExportedAttributes();
91 /***
92 * Returns warnings that occured during schema loading. Items of iterator
93 * must NOT be modified nor deleted.
94 * @return <code>Iterator</code> of <code>String</code> representing
95 * warnings, or <code>null</code> if there were no warnings.
96 */
97 public Iterator<String> getWarnings();
98 /***
99 * <p>
100 * Validates given root element. It must be full validation, no elements nor
101 * texts must not be skipped. If this element is not valid, exception must
102 * be thrown.
103 * </p>
104 * <p>
105 * When element from another namespace uri is encountered in the process of
106 * validation, just call <code>ValidationContextP.validate()</code> to
107 * validate this unknown element.
108 * </p>
109 * <p>
110 * The only exception to this rule is <code>emp:id</code> attribute, which
111 * the schema must ignore.
112 * </p>
113 * @param element element to be validated, always one of possible root
114 * elements from this namespace.
115 * @throws SchemaException if something goes wrong in the process of
116 * validation. The <code>Schema</code> instance must provide as much
117 * information as possible about error. It should display path to errorneous
118 * element with <code>getPathToRoot()</code> method of
119 * <code>EuromathSchemaProvider</code> class.
120 */
121 public void validate(Element element) throws SchemaException;
122 /***
123 * Returns rule representing given existing element. If the document is not
124 * valid then the rule returned is correct if and only if the rule can be
125 * identified from the name of the element - the element is said to be
126 * context-free.
127 * @param element the element. It must stay unchanged while returned
128 * instance is used.
129 * @return rule, used to modify contents of given element.
130 */
131 public IElementRuleP getElementRule(Element element);
132 }