1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16 package net.sf.nxqd;
17
18 import java.util.logging.Level;
19 import java.util.logging.Logger;
20 import java.util.ArrayList;
21 import java.util.List;
22 import java.util.Map;
23 import org.w3c.dom.Document;
24
25 /**
26 * The class <code>NxqdModify</code> is the context within which a set of
27 * one or more documents specified by an XQuery query can be modified
28 * in place. The modification is performed using an NxqdModify object,
29 * and a series of methods off that object that identify how the document
30 * is to be modified. Using these methods, the modification steps are
31 * identified. When the object is executed, these steps are performed in
32 * the order that they were specified.
33 *
34 * @author <a href="mailto:webhiker@sourceforge.net">webhiker</a>
35 * @version 1.0
36 */
37 public class NxqdModify extends NxqdConsumer {
38
39 /**
40 * The variable <code>logger</code> is used for logging events.
41 *
42 */
43 private static Logger logger = Logger.getLogger(NxqdModify.class.getName());
44
45 protected NxqdModify(NxqdManager manager) throws NxqdException {
46 super(manager);
47 }
48
49 /**
50 * Appends the provided data to the selected node's child notes. If the operation's
51 * target is an attribute node or the document root node, an exception is thrown
52 * at modification execution time.
53 *
54 * If the content to be added is an attribute, the content is added to the targeted
55 * node's attribute list. If the content to add is an element node, text, comment
56 * or processing instruction, its content is added immediately after the targeted
57 * node's last child node, unless the location parameter is specified.
58 *
59 * Documents resulting from this modification must be well-formed XML or an exception
60 * is thrown at modification execution time, if the documents affected are written back
61 * to their respective containers.
62 *
63 * @param selectionExpr a <code>NxqdQueryExpression</code> The XQuery expression used to
64 * target the location in the document where the modification is to be performed.
65 * Use <code>NxqdManager.prepare(...)</code> to create the <code>NxqdQueryExpression</code>.
66 * The query that you provide must target zero or more nodes,
67 * or an exception is thrown. If zero nodes are selected, no modifications are performed
68 * when execute(...) is called.
69 * @param type an <code>int</code> The type of information to be inserted. The value
70 * provided here determines whether the name or content parameter is required.
71 * Valid values are: Element, Attribute, Text, ProcessingInstruction or Comment.
72 * @param name a <code>String</code> The name of the node, attribute, or processing
73 * instruction to insert. This parameter is ignored if type is NxqdModify.Text
74 * @param content a <code>String</code> value
75 * @exception NxqdException if an error occurs
76 */
77 public void addAppendStep(NxqdQueryExpression selectionExpr,
78 int type,
79 String name,
80 String content)
81 throws NxqdException {
82
83 }
84
85 /**
86 * Appends the provided data to the selected node's child notes.
87 * If the operation's target is an attribute node or the document
88 * root node, an exception is thrown at modification execution time.
89 *
90 * If the content to be added is an attribute, the content is added to the targeted
91 * node's attribute list. If the content to add is an element node, text, comment or
92 * processing instruction, its content is added immediately after the targeted node's
93 * last child node, unless the location parameter is specified.
94 *
95 * Documents resulting from this modification must be well-formed XML or an exception
96 * is thrown at modification execution time, if the documents affected are written back
97 * to their respective containers.
98 *
99 * @param selectionExpr a <code>NxqdQueryExpression</code> The XQuery expression used to
100 * target the location in the document where the modification is to be performed.
101 * Use <code>NxqdManager.prepare(...)</code> to create the <code>NxqdQueryExpression</code>.
102 * The query that you provide must target zero or more nodes,
103 * or an exception is thrown. If zero nodes are selected, no modifications are performed
104 * when execute(...) is called.
105 * @param type an <code>int</code> The type of information to be inserted. The value
106 * provided here determines whether the name or content parameter is required.
107 * Valid values are: Element, Attribute, Text, ProcessingInstruction or Comment.
108 * @param name a <code>String</code> The name of the node, attribute, or processing
109 * instruction to insert. This parameter is ignored if type is NxqdModify.Text
110 * @param content a <code>String</code> value
111 * @param location an <code>int</code> Identifies the position in the child node list where
112 * the provided content is to be inserted. For example, if location is 3, and the target
113 * element has at least 3 child nodes, the new content will become the 3rd child of the target node. If this parameter is a negative number, or if this parameter contains a value that is larger
114 * than the number of child nodes, then the new node will be the last child node.
115 * @exception NxqdException if an error occurs
116 */
117 public void addAppendStep(NxqdQueryExpression selectionExpr,
118 int type,
119 String name,
120 String content,
121 int location) throws NxqdException {
122
123 }
124
125 /**
126 * Inserts the provided data into the document after the selected node. If the
127 * operation's target is an attribute node or the document root node, an exception
128 * is thrown at modification execution time.
129 *
130 * If the content to be added is an attribute, the content is added to the targeted
131 * node's parent node. For any other type of content, the content is inserted into the
132 * document immediately after the targeted node's end tag, as its next sibling.
133 *
134 * Documents resulting from this modification must be well-formed XML or an exception is
135 * thrown at modification execution time, if the documents affected are written back to
136 * their respective containers.
137 *
138 * @param selectionExpr a <code>NxqdQueryExpression</code> value. The XQuery expression
139 * used to target the location in the document where the modification is to be performed.
140 * @param type an <code>int</code> value. The type of information to be inserted.
141 * The value provided here determines whether the name or content parameter is required.
142 * Valid values are: Element, Attribute, Text, ProcessingInstruction or Comment.
143 * @param name a <code>String</code> value. The name of the node, attribute, or processing
144 * instruction to insert. This parameter is ignored if type is NxqdModify.Text or NxqdModify.Comment.
145 * @param content a <code>String</code> value
146 * @exception NxqdException if an error occurs
147 */
148 public void addInsertAfterStep(NxqdQueryExpression selectionExpr,
149 int type,
150 String name,
151 String content)
152 throws NxqdException {
153
154 }
155
156 /**
157 * Inserts the provided data into the document before the selected node, as a previous
158 * sibling. If the operation's target is an attribute node or the document root node,
159 * an exception is thrown at modification execution time.
160 *
161 * If the content to be added is an attribute, the content is added to the targeted
162 * node's parent node. For any other type of content, the content is inserted into the
163 * document immediately before the targeted node's start tag.
164 *
165 * Documents resulting from this modification must be well-formed XML or an exception
166 * is thrown at modification execution time, if the documents affected are written back
167 * to their respective containers.
168 *
169 * @param selectionExpr a <code>NxqdQueryExpression</code> value. The XQuery expression
170 * used to target the location in the document where the modification is to be performed.
171 * @param type an <code>int</code> value. The type of information to be inserted.
172 * The value provided here determines whether the name or content parameter is required.
173 * Valid values are: Element, Attribute, Text, ProcessingInstruction or Comment.
174 * @param name a <code>String</code> value. The name of the node, attribute, or processing
175 * instruction to insert. This parameter is ignored if type is NxqdModify.Text or NxqdModify.Comment.
176 * @param content a <code>String</code> value
177 */
178 public void addInsertBeforeStep(NxqdQueryExpression selectionExpr,
179 int type,
180 String name,
181 String content)
182 throws NxqdException {
183
184 }
185
186 /**
187 * Removes the node targeted by the selection expression. If the operation's target
188 * is the document root node an exception is thrown at modification execution time.
189 *
190 * @param selectionExpr a <code>NxqdQueryExpression</code> value
191 * @exception NxqdException if an error occurs
192 */
193 public void addRemoveStep(NxqdQueryExpression selectionExpr)
194 throws NxqdException {
195 }
196
197 /**
198 * Renames an element node, attribute node, or processing instruction. If the document
199 * content targeted by selectionExpr is any other type of content, an exception is thrown at
200 * modification execution time.
201 *
202 * @param selectionExpr a <code>NxqdQueryExpression</code> value
203 * @param newName a <code>String</code> value
204 * @exception NxqdException if an error occurs
205 */
206 public void addRenameStep(NxqdQueryExpression selectionExpr,
207 String newName)
208 throws NxqdException {
209
210 }
211
212 /**
213 * Replaces the targeted node's content with text. If the targeted node is an element node,
214 * all of the element node's children and text nodes are replaced with text. If the targeted
215 * node is an attribute node, the attribute's value is replaced by text. The purpose of this
216 * interface is primarily to replace text content. Note that text is treated as a text node.
217 * If it contains mark-up, that mark-up is escaped to make it legal text.
218 *
219 * Documents resulting from this modification must be well-formed XML or an exception is thrown
220 * at modification execution time, if the documents affected are written back to their respective
221 * containers.
222 *
223 * @param selectionExpr a <code>NxqdQueryExpression</code> value
224 * @param content a <code>String</code> value
225 * @exception NxqdException if an error occurs
226 */
227 public void addUpdateStep(NxqdQueryExpression selectionExpr,
228 String content)
229 throws NxqdException {
230
231 }
232
233 }
234