5 Minute Tutorial for StaxMate
As per introduction, StaxMate is designed to allow
- Reading XML content efficiently, conveniently and correctly
- Writing XML content efficiently, conveniently and correctly
To showcase how this is done, let's have a look at sample use cases.
Writing an XML document
Let's start with one of simplest and most common use cases: that of writing (aka generating) XML content. Content can come from variety of sources; here we consider the case where we just want to write explicit content (another common case would be to write content read earlier, but let's reserve that for an advanced example).
So, here's xml document that we want to output:
Let's first look at the whole code, and then discuss what it actually does:
Let's have a look at all the steps, to see what is being done and why
- First we create a StaxMate output factory: here we use automatic introspection that Stax XMLOutputFactory offers (to find any plugged implementation)
- This output factory is full thread-safe (after configuration), and should be reused: usually a single(ton) instance is enough for the whole application or service.
- Create the document output object. Document object just denotes document itself, not a root element: but we will add the root element under it (could also add comments, processing instructions). In this case, we will write an xml file.
- We can also choose to "pretty print" output document, by enabling indentation.
- It is often useful to add xml comments that include developer-readable information about generator process; it is easily ignored by xml readers
- Add Employee element
- Add attribute 'id' with typed value (StaxMate can convert from number to String)
- Add 'name' element
- Add both 'first' element and its textual contents
- Add similarly, 'last' and its textual contents
- Important: MUST close the root-level object; otherwise start elements may not get closed, contents not flushed to the file.
Not too bad? Some things to consider:
- Although we use XMLInputFactory implementation auto-discovery here, it is often preferable to pass this information from outside, perhaps using Dependency Injection framework (can then specify which impl to use; recommended one is com.ctc.wstx.stax.WstxOutputFactory, for Woodstox).
- Indentation usually should NOT be used for production systems – since it just adds 20-30% to document size without any useful additional information – but it can be convenient during development and debugging.
- Instead of writing contents to a file, we could have uses a ByteArrayOutputStream, StringWriter, or servlet's OutputStream as well; there are many convenience methods for typical targets.
- Typed conversion for 'id' attribute value is just one example of ability to use Java types for output, not having to convert to Strings first
- Methods that add child containers (SMOutputElement usually) can be chained, if the element itself is not needed for anything else; this can shorten the code nicely without reducing readability.
Reading XML content
The first step on input side is similar to output side: that of creating the necessary StaxMate factory:
TO BE COMPLETED