1
2
3
4
5
6
7
8
9
10
11
12 package sk.uniba.euromath.document.schema.plug;
13 import java.util.List;
14 import org.w3c.dom.Element;
15 /***
16 * <p>
17 * Represents rule for one element (the context element), that is being created.
18 * This rule may consist of more than one expression, but all expressions must
19 * generate exactly one element with required name. These expressions are
20 * alternatives to each other; only one expression can be selected to generate
21 * new contents of element.
22 * </p>
23 * <p>
24 * Returned values depends on context element of this instance. This context
25 * element doesn't exist yet, it is being created.
26 * </p>
27 * <p>
28 * Representing class must properly implement <code>equals()</code> and
29 * <code>hashValue()</code> to ensure, that it can be properly placed into
30 * <code>HashMap</code>. These values should be computed only from enclosed
31 * expressions.
32 * </p>
33 * <p>
34 * When creating element with this rule, choose between the following:
35 * </p>
36 * <ol>
37 * <li>Creating elements: when creating elements, then text is always validated
38 * with AnyString, therefore there can be no text at all. So, when creating
39 * elements, no text is needed to be created.</li>
40 * <li>When creating text, just rely on the value returned by
41 * <code>getNewTextRule</code>, there is no need to creating elements.</li>
42 * </ol>
43 * <p>
44 * So, creation algorithm is as follows:
45 * </p>
46 * <ul>
47 * <li>If <code>getNewTextRule()</code> is not <code>null</code>, then
48 * text is required and must be created.</li>
49 * <li>If <code>getNewContent</code> doesn't return <code>null</code>,
50 * then some elements are required.</li>
51 * <li>When text AND elements must be created, then they must be alternatives
52 * to each other: you must create some text OR you must create some elements.
53 * </li>
54 * <li>Otherwise, no content must be created.</li>
55 * </ul>
56 * @author Martin Vysny
57 */
58 public interface INewElementRuleP extends IBaseRuleP, ISingleQNameP, IForeignNodeP {
59 /***
60 * <p>
61 * Computes all possibilities of content, that can be generated by this rule
62 * and inserted into context element. There must be only such insertlists,
63 * that doesn't contain optional elements. All InsertLists with length equal
64 * to 1 should be grouped together in one InsertList.
65 * </p>
66 * <p>
67 * This content must be computed with existing attributes in mind.
68 * Expressions, whose contents violates given attribute set, must not be
69 * used.
70 * </p>
71 * <p>
72 * It must NOT be computed when instance of this object is created.
73 * </p>
74 * @param e element with already created attributes. It can be assumed that
75 * element has no content.
76 * @return array of Insertlists, that can generate sequence of element. If
77 * no content is required, return <code>null</code>.
78 */
79 public IElementSequenceRuleP getNewContent(Element e);
80 /***
81 * <p>
82 * For each expression returns one list of attributes, that can be created
83 * by this rule. Only required attributes must be included in result set.
84 * Special care must be taken: there must not be two equal list rules (with
85 * equal rules). If all lists being returned are zero-length then a
86 * zero-length sequence must be returned instead.
87 * </p>
88 * <p>
89 * Should be computed only once, when this function is called for first
90 * time.
91 * </p>
92 * @return list of creatable attributes.
93 */
94 public List<IAttributeListRuleP> getLists();
95 /***
96 * Computes and returns value rule, that can be inserted into context
97 * element.
98 * @param e element with already created attributes. It can be assumed that
99 * element has no content. It may not be inserted in the document.
100 * @return ValueRule for validating element's text context. If
101 * <code>null</code>, then no text content is required.
102 */
103 public IValueRule getNewTextRule(Element e);
104 }