DocumentWriter


1   /*
2   
3   This software is OSI Certified Open Source Software.
4   OSI Certified is a certification mark of the Open Source Initiative.
5   
6   The license (Mozilla version 1.0) can be read at the MMBase site.
7   See http://www.MMBase.org/license
8   
9   */
10  package org.mmbase.util.xml;
11  
12  import java.io.*;
13  import java.util.ResourceBundle  ;
14  import java.util.MissingResourceException  ;
15  
16  import org.xml.sax.InputSource  ;
17  
18  import org.w3c.dom.*;
19  import javax.xml.transform.*;
20  import javax.xml.transform.stream.StreamResult  ;
21  import javax.xml.transform.dom.DOMSource  ;
22  
23  import org.mmbase.util.logging.*;
24  
25  /**
26   * Abstract class for creating xml documents.
27   * Use this class as the base class for writers that construct and export DOM documents.
28   * The document can then be used internally or serialized using a number of
29   * utility methods.
30   *
31   * @since MMBase-1.6
32   * @author Pierre van Rooden
33   * @version $Id: DocumentWriter.java,v 1.10 2006/04/18 13:11:41 michiel Exp $
34   */
35  abstract public class DocumentWriter extends DocumentReader {
36  
37      // logger
38      private static final Logger log = Logging.getLoggerInstance(DocumentWriter.class);
39  
40      /**
41       * True if the document has been generated
42       */
43      private boolean documentGenerated=false;
44  
45      /**
46       * If true, comments are included
47       */
48      private boolean includeComments = false;
49  
50      /**
51       *  Resource bundle with builder comments
52       */
53      private ResourceBundle   messageRB;
54  
55      // keep public and system id
56      String   publicId ="";
57      String   systemId ="";
58  
59      /**
60       * Constructs the document writer.
61       * The constructor creates a basic document with a root element based on the specified document type parameters.
62       * The document is empty after construction.
63       * It is actually filled with a call to {@link #generateDocument()}, which is in turn called when
64       * the document is first accessed through {@link #getDocument()}.
65       * @param qualifiedName the qualified name of the document's root element
66       * @param publicId the PUBLIC id of the document type
67       * @param systemId the SYSTEm id of the document type
68       */
69      public DocumentWriter(String   qualifiedName, String   publicId, String   systemId) throws DOMException {
70          DOMImplementation domImpl = DocumentReader.getDocumentBuilder().getDOMImplementation();
71          this.publicId = publicId;
72          this.systemId = systemId;
73          DocumentType doctype = domImpl.createDocumentType(qualifiedName, this.publicId, this.systemId);
74          document = domImpl.createDocument(null, qualifiedName, doctype);
75      }
76  
77  
78      /**
79       * Constructs the document by reading it from a source.
80       * @param source the input source from which to read the document
81       * @since MMBase-1.7
82       */
83      public DocumentWriter(InputSource   source) {
84          super(source);
85          documentGenerated = true;
86      }
87  
88      /**
89       * Constructs the document by reading it from a source.
90       * You can pass a resolve class to this constructor, allowing you to indicate the package in which the dtd
91       * of the document read is to be found. The dtd sould be in the resources package under the package of the class passed.
92       * @param source the input source from which to read the document
93       * @param validating whether to validate the document
94       * @param resolveBase the base class whose package is used to resolve dtds, set to null if unknown
95       * @since MMBase-1.7
96       */
97      public DocumentWriter(InputSource   source, boolean validating, Class   resolveBase) {
98          super(source, validating, resolveBase);
99          documentGenerated = true;
100     }
101 
102     /**
103      * Initialize the ResourceBundle with the given resource.
104      * You need a respource to use the addfCOmment() and getMessage() methods.
105      * @param resourcelocation Resource.
106      */
107     protected void getMessageRetriever(String   resourcelocation) {
108         try {
109             messageRB = ResourceBundle.getBundle(resourcelocation);
110         } catch (MissingResourceException   e) {
111             log.error("Resource for DocumentWriter is missing: "+resourcelocation);
112         }
113     }
114 
115     /**
116      * Retrieves a message from the resource bundle.
117      * @param key the key of the message
118      */
119     protected String   getMessage(String   key) {
120         return getMessage(key,"");
121     }
122 
123     /**
124      * Retrieves a message from the resource bundle.
125      * @param key the key of the message
126      * @param a1 the first parameter to substitute in the message
127      */
128     protected String   getMessage(String   key, String   a1) {
129         return getMessage(key,a1,"","");
130     }
131 
132     /**
133      * Retrieves a message from the resource bundle.
134      * @param key the key of the message
135      * @param a1 the first parameter to substitute in the message
136      * @param a2 the second parameter to substitute in the message
137      */
138     protected String   getMessage(String   key, String   a1, String   a2) {
139         return getMessage(key,a1,a2,"");
140     }
141 
142     /**
143      * Retrieves a message from the resource bundle.
144      * @param key the key of the message
145      * @param a1 the first parameter to substitute in the message
146      * @param a2 the second parameter to substitute in the message
147      * @param a3 the third parameter to substitute in the message
148      */
149     protected String   getMessage(String   key, String   a1, String   a2, String   a3) {
150         if (messageRB!=null)
151         try {
152             String   message = messageRB.getString(key);
153             Object  [] args = new String  [3];
154             args[0] = a1;
155             args[1] = a2;
156             args[2] = a3;
157             return java.text.MessageFormat.format(message, args);
158         } catch (MissingResourceException   e) {
159             log.error("Resource for DocumentWriter is broken. There is no " + key + " key in resource.");
160         }
161         return null;
162     }
163 
164     /**
165      * Creates a DOM element which contains a Text Node, and adds it to the
166      * specified node as a child.
167      * @param tagname name of the new element
168      * @param content content of the new element as a string
169      * @param out the element to which to add the new Element.
170      * @return the newly created element
171      */
172     protected Element addContentElement(String   tagname,String   content, Element out) {
173         Element el = document.createElement(tagname);
174         if (content == null) content="";
175         Text tel = document.createTextNode(content);
176         el.appendChild(tel);
177         out.appendChild(el);
178         return el;
179     }
180 
181     /**
182      * Creates a Comment (provided comments should be included), and adds it to the
183      * specified node as a child.
184      * The comment is retrieved from a resource bundle - if no resource was specified,
185      * no comments are added.
186      * @param key the key of the comment to add as a string
187      * @param out the element to which to add the new Comment.
188      * @return the newly created comment or null if nothing was added
189      * @see #setIncludeComments
190      */
191     protected Comment addComment(String   key, Element out) {
192         return addComment(key, "", "", out);
193     }
194 
195     /**
196      * Creates a Comment (provided comments should be included), and adds it to the
197      * specified node as a child.
198      * The comment is retrieved from a resource bundle - if no resource was specified,
199      * no comments are added.
200      * @param key the key of the comment to add as a string
201      * @param a1 the first parameter to substitute in the comment
202      * @param out the element to which to add the new Comment.
203      * @return the newly created comment or null if nothing was added
204      * @see #setIncludeComments
205      */
206     protected Comment addComment(String   key, String   a1, Element out) {
207         return addComment(key, a1, "", out);
208     }
209 
210     /**
211      * Creates a Comment (provided comments should be included), and adds it to the
212      * specified node as a child.
213      * The comment is retrieved from a resource bundle - if no resource was specified,
214      * no comments are added.
215      * @param key the comment to add as a string
216      * @param a1 the first parameter to substitute in the comment
217      * @param a2 the second parameter to substitute in the comment
218      * @param out the element to which to add the new Comment.
219      * @return the newly created comment or null if nothing was added
220      * @see #setIncludeComments
221      */
222     protected Comment addComment(String   key, String   a1, String   a2, Element out) {
223         Comment comm=null;
224         if (includeComments) {
225             String   message=getMessage(key,a1,a2);
226             if (message!=null) {
227                 comm=document.createComment(" "+message+" ");
228                 out.appendChild(comm);
229             }
230         }
231         return comm;
232     }
233 
234     /**
235      * Generates the document.
236      * You need to override this class with the code that constructs your document.
237      * @throws DOMException when an error occurred during generation
238      */
239     abstract protected void generate() throws DOMException;
240 
241     /**
242      * Generates the document if it hadn't be done so already.
243      * If not, an exception is thrown.
244      * Use getDocument() to safely retrive a generated coeumnt.
245      * @throws DOMException when an error occurred during generation
246      * @throws DOMException when the document was already constructed
247      */
248     public final Document generateDocument() throws DOMException {
249         if (!documentGenerated) {
250             generate();
251             documentGenerated=true;
252             return document;
253         } else {
254             throw new IllegalStateException  ("Document already constructed");
255         }
256     }
257 
258     /**
259      * Returns the completed document representation;
260      * If the document was not yet generated, it is generated  by calling generateDocument().
261      * @return the generated document
262      * @throws DOMException when an error occurred during generation
263      */
264     public Document getDocument() throws DOMException {
265         if (!documentGenerated) {
266             generateDocument();
267         }
268         return document;
269     }
270 
271     /**
272      * Sets whether the document will include comments
273      * @param value if true, the document will include comments
274      */
275     public void setIncludeComments(boolean value) {
276         includeComments=value;
277     }
278 
279     /**
280      * Gets whether the document will include comments
281      * @return  if true, the document will include comments
282      */
283     public boolean includeComments() {
284         return includeComments;
285     }
286 
287     /**
288      * Generates the document and returns it as a string.
289      * @throws TransformerException if the document is malformed
290      */
291     public String   writeToString() throws TransformerException {
292         StringWriter strw=new StringWriter(500);
293         write(new StreamResult  (strw));
294         return strw.toString();
295     }
296 
297     /**
298      * Generates the document and store it as a file in the given path.
299      * @param filename the filepath where the configuration is to be stored
300      * @throws TransformerException if the document is malformed
301      * @throws IOException if the file cannot be written
302      */
303     public void writeToFile(String   filename) throws IOException, TransformerException {
304         writeToStream(new FileOutputStream(filename));
305     }
306 
307     /**
308      * Generates the document and store it in the given stream.
309      * @param out the output stream where the configuration is to be stored
310      */
311     public void writeToStream(OutputStream out) throws TransformerException {
312         write(new StreamResult  (out));
313     }
314 
315     /**
316      * Generates the document and writes it to the result object.
317      * @param result the StreamResult object where to store the configuration'
318      */
319     public void write(StreamResult   result) throws TransformerException {
320         Document doc=getDocument();
321         TransformerFactory tfactory = TransformerFactory.newInstance();
322         tfactory.setURIResolver(new org.mmbase.util.xml.URIResolver(new java.io.File  ("")));
323         // This creates a transformer that does a simple identity transform,
324         // and thus can be used for all intents and purposes as a serializer.
325         Transformer serializer = tfactory.newTransformer();
326         // sets indent amount for xalan
327         // should be done elsewhere, but where?
328         serializer.setOutputProperty("{http://xml.apache.org/xslt}indent-amount", "2");
329         // xml output configuration
330         serializer.setOutputProperty(OutputKeys.INDENT, "yes");
331         serializer.setOutputProperty(OutputKeys.OMIT_XML_DECLARATION, "no");
332         serializer.setOutputProperty(OutputKeys.DOCTYPE_PUBLIC, publicId);
333         serializer.setOutputProperty(OutputKeys.DOCTYPE_SYSTEM, systemId);
334         serializer.transform(new DOMSource  (doc), result);
335     }
336 }
337
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags