##
## Licensed to the Apache Software Foundation (ASF) under one
## or more contributor license agreements. See the NOTICE file
## distributed with this work for additional information
## regarding copyright ownership. The ASF licenses this file
## to you under the Apache License, Version 2.0 (the
## "License"); you may not use this file except in compliance
## with the License. You may obtain a copy of the License at
##
## http://www.apache.org/licenses/LICENSE-2.0
##
## Unless required by applicable law or agreed to in writing,
## software distributed under the License is distributed on an
## "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
## KIND, either express or implied. See the License for the
## specific language governing permissions and limitations
## under the License.
##

Quick Start Samples
===================

Content:

<!-- MACRO{toc} -->

Adding Axiom as a Maven dependency
----------------------------------

To use Axiom in a project built using Maven, add the following dependencies:

    <dependency>
        <groupId>org.apache.ws.commons.axiom</groupId>
        <artifactId>axiom-api</artifactId>
        <version>${project.version}</version>
    </dependency>
    <dependency>
        <groupId>org.apache.ws.commons.axiom</groupId>
        <artifactId>axiom-impl</artifactId>
        <version>${project.version}</version>
        <scope>runtime</scope>
    </dependency>

Note that the `axiom-impl` dependency is added in scope `runtime`
because application code should not refer to implementation classes directly.
All Axiom features are accessible through the public API which is provided
by `axiom-api`.

If the application code requires a DOM compliant Axiom implementation,
then the following dependency needs to be added too:

    <dependency>
        <groupId>org.apache.ws.commons.axiom</groupId>
        <artifactId>axiom-dom</artifactId>
        <version>${project.version}</version>
        <scope>runtime</scope>
    </dependency>

Parsing and processing an XML document
--------------------------------------

The following sample shows how to parse and process an XML document using Axiom.
It is pretty much self-explaining:

<!-- MACRO{snippet|id=main|file=samples/src/test/java/org/apache/axiom/samples/ParseSample.java} -->

Schema validation using javax.xml.validation
--------------------------------------------

This sample demonstrates how to validate a part of an Axiom tree (actually the body of a SOAP message)
using the `javax.xml.validation` API:

<!-- MACRO{snippet|id=sax|file=samples/src/test/java/org/apache/axiom/samples/ValidateSample.java} -->

It leverages the fact that Axiom is capable of constructing a `SAXSource` from an `OMDocument`
or `OMElement`.

Alternatively, one can use a DOM compliant Axiom implementation and use a
`DOMSource` to pass the XML fragment to the validator:

<!-- MACRO{snippet|id=dom|file=samples/src/test/java/org/apache/axiom/samples/ValidateSample.java} -->

Loading local chunks from a large XML document
----------------------------------------------

Here the goal is to process a large XML document "by chunks", i.e.
  
1.  Parse the file and find a relevant element (e.g. by name)

2.  Load this element into memory as an `OMElement`.

3.  Process the `OMElement` (the "chunk").

The process is repeated until the end of the document is reached.

This can be achieved without loading the entire document into memory (and without loading all the
chunks in memory) by scanning the document using the StAX API and switching to Axiom when a
matching element is found:

<!-- MACRO{snippet|id=main|file=samples/src/test/java/org/apache/axiom/samples/FragmentsSample.java} -->

The code leverages the fact that `createStAXOMBuilder` can be used to build a fragment
(corresponding to a given element) from a StAX stream reader, simply by passing an
`XMLStreamReader` that is positioned on a `START_ELEMENT` event.

Processing MTOM messages
------------------------

This sample shows how to process MTOM messages with Axiom. The code actually sends a request to
the following JAX-WS service:

<!-- MACRO{snippet|id=class|file=samples/src/test/java/org/apache/axiom/samples/MTOMService.java} -->

It then extracts the binary content from the response and writes it to a given `OutputStream`:

<!-- MACRO{snippet|id=retrieveContent|file=samples/src/test/java/org/apache/axiom/samples/MTOMSample.java} -->

The sample code shows that in order to parse an MTOM message one first needs to construct an
`MultipartBody` object that is then passed to the relevant method in `OMXMLBuilderFactory`.
In the object model, an XOP/MTOM attachment is represented as an `OMText` node for which `isBinary()` returns
`true`. Such a node is created for each `xop:Include` element in the original message.
The binary data is stored in a `DataHandler` object that can be obtained by a call to the
`getDataHandler()` method of the `OMText` node.

By default attachments are loaded into memory, but the `MultipartBody` can be configured to buffer
data on disk. The sample actually shows an alternative method to reduce the
memory footprint of the MTOM processing, which is to enable streaming.

Logging MTOM messages without inlining optimized binary data
------------------------------------------------------------

A common way to log a SOAP message is to invoke the `toString` method on the corresponding `SOAPEnvelope`
object and send the result to the logger. However, this is problematic for MTOM messages because the
`toString` method will always serialize the message as plain XML and therefore inline optimized
binary data using base64 encoding.

Except for this particular use case, serializing a message using MTOM without actually producing
the MIME parts for the binary data is not meaningful and is therefore not directly supported by
the Axiom API. The solution is to use a custom `XMLStreamWriter` implementation that uses an
Axiom specific extension to accept `DataHandler` objects and replaces them by some
placeholder text:
  
<!-- MACRO{snippet|id=main|file=samples/src/test/java/org/apache/axiom/samples/LogWriter.java} -->

The following code shows how this class would be used to log the MTOM message:

<!-- MACRO{snippet|id=variant2|file=samples/src/test/java/org/apache/axiom/samples/MTOMLogSample.java} -->
