Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 4 Next »

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 see what this means in action, let's have a look at simple sample use cases.

Writing an XML document

Let's start with a particular simple and common use case: that of writing (aka generating) XML content. Content can come from variety of sources; here we only consider generation, not where data comes from.

Let's say we want to output XML document like this one:

empl.xml

Let's first look at the whole code, and then discuss what it actually does:

WriteEmployee.java

Let's have a look at all the steps, to see what is being done and why

  1. 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.
  2. 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.
  3. We can also choose to "pretty print" output document, by enabling indentation.
  4. It is often useful to add xml comments that include developer-readable information about generator process; it is easily ignored by xml readers
  5. Add Employee element
  6. Add attribute 'id' with typed value (StaxMate can convert from number to String)
  7. Add 'name' element
  8. Add both 'first' element and its textual contents
  9. Add similarly, 'last' and its textual contents
  10. Important: MUST close the root-level object; otherwise start elements may not get closed, contents not flushed to the file.

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

Now that we have written some XML content, let's read it back in.
Let's start with code itself (which uses xml document that we saw earlier):

ReadEmployee.java

Let's have a look at all the steps, to see what is being done and why

  1. First we create a StaxMate input factory: similar to constructing output factory
  2. Create the root cursor; only traverses over the root element, ignores non-elements like comments

Additional things to consider:

  • As with output factory, usually it's better to inject specific factory

Advanced Use Cases

Here are links to some use cases that show more advanced usage:

TO BE COMPLETED

  • No labels