View Javadoc

1   /*
2    * Copyright 2001-2005 The Apache Software Foundation.
3    *
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    *
8    *      http://www.apache.org/licenses/LICENSE-2.0
9    *
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
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  	// TO BE COMPLETED
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 	// TO BE COMPLETED
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 	// TO BE COMPLETED
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 	// TO BE COMPLETED
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 	// TO BE COMPLETED
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 	// TO BE COMPLETED
231     }
232 
233 }
234