svn commit: r1201907 - in /webservices/commons/trunk/modules/axiom: modules/axiom-samples/src/test/java/org/apache/axiom/samples/ src/site/apt/

[ve...@apache.org]

Author: veithen
Date: Mon Nov 14 21:13:30 2011
New Revision: 1201907

URL: http://svn.apache.org/viewvc?rev=1201907&view=rev
Log:
Added another sample inspired by a recent question posted by Andreas Brunner on the Axis2 mailing list.

Added:
    webservices/commons/trunk/modules/axiom/modules/axiom-samples/src/test/java/org/apache/axiom/samples/LogWriter.java   (with props)
    webservices/commons/trunk/modules/axiom/modules/axiom-samples/src/test/java/org/apache/axiom/samples/MTOMLogSample.java   (with props)
Modified:
    webservices/commons/trunk/modules/axiom/src/site/apt/quickstart-samples.apt

Added: webservices/commons/trunk/modules/axiom/modules/axiom-samples/src/test/java/org/apache/axiom/samples/LogWriter.java
URL: http://svn.apache.org/viewvc/webservices/commons/trunk/modules/axiom/modules/axiom-samples/src/test/java/org/apache/axiom/samples/LogWriter.java?rev=1201907&view=auto
==============================================================================
--- webservices/commons/trunk/modules/axiom/modules/axiom-samples/src/test/java/org/apache/axiom/samples/LogWriter.java (added)
+++ webservices/commons/trunk/modules/axiom/modules/axiom-samples/src/test/java/org/apache/axiom/samples/LogWriter.java Mon Nov 14 21:13:30 2011
@@ -0,0 +1,55 @@
+/*
+ * 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.
+ */
+package org.apache.axiom.samples;
+
+import java.io.IOException;
+
+import javax.activation.DataHandler;
+import javax.xml.stream.XMLStreamException;
+import javax.xml.stream.XMLStreamWriter;
+
+import org.apache.axiom.ext.stax.datahandler.DataHandlerProvider;
+import org.apache.axiom.ext.stax.datahandler.DataHandlerWriter;
+import org.apache.axiom.util.stax.wrapper.XMLStreamWriterWrapper;
+
+// START SNIPPET: main
+public class LogWriter extends XMLStreamWriterWrapper implements DataHandlerWriter {
+    public LogWriter(XMLStreamWriter parent) {
+        super(parent);
+    }
+
+    public Object getProperty(String name) throws IllegalArgumentException {
+        if (name.equals(DataHandlerWriter.PROPERTY)) {
+            return this;
+        } else {
+            return super.getProperty(name);
+        }
+    }
+
+    public void writeDataHandler(DataHandler dataHandler, String contentID, boolean optimize)
+            throws IOException, XMLStreamException {
+        super.writeCharacters("[base64 encoded data]");
+    }
+
+    public void writeDataHandler(DataHandlerProvider dataHandlerProvider, String contentID,
+            boolean optimize) throws IOException, XMLStreamException {
+        super.writeCharacters("[base64 encoded data]");
+    }
+}
+// END SNIPPET: main

Propchange: webservices/commons/trunk/modules/axiom/modules/axiom-samples/src/test/java/org/apache/axiom/samples/LogWriter.java
------------------------------------------------------------------------------
    svn:eol-style = native

Added: webservices/commons/trunk/modules/axiom/modules/axiom-samples/src/test/java/org/apache/axiom/samples/MTOMLogSample.java
URL: http://svn.apache.org/viewvc/webservices/commons/trunk/modules/axiom/modules/axiom-samples/src/test/java/org/apache/axiom/samples/MTOMLogSample.java?rev=1201907&view=auto
==============================================================================
--- webservices/commons/trunk/modules/axiom/modules/axiom-samples/src/test/java/org/apache/axiom/samples/MTOMLogSample.java (added)
+++ webservices/commons/trunk/modules/axiom/modules/axiom-samples/src/test/java/org/apache/axiom/samples/MTOMLogSample.java Mon Nov 14 21:13:30 2011
@@ -0,0 +1,71 @@
+/*
+ * 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.
+ */
+package org.apache.axiom.samples;
+
+import java.io.StringWriter;
+
+import javax.activation.DataHandler;
+import javax.xml.namespace.QName;
+import javax.xml.stream.XMLStreamException;
+import javax.xml.stream.XMLStreamWriter;
+
+import junit.framework.TestCase;
+
+import org.apache.axiom.om.OMAbstractFactory;
+import org.apache.axiom.om.OMElement;
+import org.apache.axiom.om.util.StAXUtils;
+import org.apache.axiom.soap.SOAPEnvelope;
+import org.apache.axiom.soap.SOAPFactory;
+import org.apache.axiom.util.stax.xop.ContentIDGenerator;
+import org.apache.axiom.util.stax.xop.OptimizationPolicy;
+import org.apache.axiom.util.stax.xop.XOPEncodingStreamWriter;
+import org.apache.commons.logging.Log;
+import org.apache.commons.logging.LogFactory;
+
+public class MTOMLogSample extends TestCase {
+    private static final Log log = LogFactory.getLog(MTOMLogSample.class);
+    
+    // START SNIPPET: variant1
+    private void logMessage1(SOAPEnvelope env) throws XMLStreamException {
+        StringWriter sw = new StringWriter();
+        XMLStreamWriter writer = StAXUtils.createXMLStreamWriter(sw);
+        XMLStreamWriter encoder = new XOPEncodingStreamWriter(writer,
+                ContentIDGenerator.DEFAULT, OptimizationPolicy.DEFAULT);
+        env.serialize(encoder);
+        log.info("Message: " + sw.toString());
+    }
+    // END SNIPPET: variant1
+    
+    // START SNIPPET: variant2
+    private void logMessage2(SOAPEnvelope env) throws XMLStreamException {
+        StringWriter sw = new StringWriter();
+        env.serialize(new LogWriter(StAXUtils.createXMLStreamWriter(sw)));
+        log.info("Message: " + sw.toString());
+    }
+    // END SNIPPET: variant2
+    
+    public void test() throws XMLStreamException {
+        SOAPFactory factory = OMAbstractFactory.getSOAP11Factory();
+        SOAPEnvelope env = factory.getDefaultEnvelope();
+        OMElement element = factory.createOMElement(new QName("urn:testService", "invokeMtom", "ns"), env.getBody());
+        element.addChild(factory.createOMText(new DataHandler("test", "text/xml"), true));
+        logMessage1(env);
+        logMessage2(env);
+    }
+}

Propchange: webservices/commons/trunk/modules/axiom/modules/axiom-samples/src/test/java/org/apache/axiom/samples/MTOMLogSample.java
------------------------------------------------------------------------------
    svn:eol-style = native

Modified: webservices/commons/trunk/modules/axiom/src/site/apt/quickstart-samples.apt
URL: http://svn.apache.org/viewvc/webservices/commons/trunk/modules/axiom/src/site/apt/quickstart-samples.apt?rev=1201907&r1=1201906&r2=1201907&view=diff
==============================================================================
--- webservices/commons/trunk/modules/axiom/src/site/apt/quickstart-samples.apt (original)
+++ webservices/commons/trunk/modules/axiom/src/site/apt/quickstart-samples.apt Mon Nov 14 21:13:30 2011
@@ -50,3 +50,39 @@ Loading local chunks from a large XML do
   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.
+
+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. However the following simple trick can be used to implement this:
+
+%{snippet|id=variant1|file=modules/axiom-samples/src/test/java/org/apache/axiom/samples/MTOMLogSample.java}
+  
+  It relies on the <<<XOPEncodingStreamWriter>>> class which is used by Axiom internally to perform the
+  XOP/MTOM encoding. This class is implemented as an <<<XMLStreamWriter>>> wrapper and is responsible for
+  generating the <<<xop:Include>>> elements. It also builds a map of the MIME parts that need to be generated.
+  Since <<<XOPEncodingStreamWriter>>> is an <<<XMLStreamWriter>>> proxy, it can easily be used in conjunction with the
+  <<<serialize(XMLStreamWriter)>>> method and an <<<XMLStreamWriter>>> that writes the result to
+  a <<<StringWriter>>>. The trick here is to only store the SOAP part and to disregard the MIME parts
+  for the attachments. Since <<<XOPEncodingStreamWriter>>> only stores references to the <<<DataHandler>>>
+  objects for these attachements, there is no overhead associated with that.
+  
+  One may wonder how <<<XOPEncodingStreamWriter>>> can receive <<<DataHandler>>> objects considering that
+  it is an <<<XMLStreamWriter>>> implementation and that the StAX API doesn't know anything about XOP/MTOM or
+  <<<DataHandler>>> objects. The answer is that <<<XOPEncodingStreamWriter>>> actually implements an Axiom
+  specific extension defined by the <<<DataHandlerWriter>>> interface. An alternative solution for the logging
+  problem is therefore to use a custom <<<XMLStreamWriter>>> implementation that supports that extension and
+  that bypasses the serialization of the <<<DataHandler>>> objects, e.g. by replacing them by some
+  placeholder text:
+
+%{snippet|id=main|file=modules/axiom-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:
+
+%{snippet|id=variant2|file=modules/axiom-samples/src/test/java/org/apache/axiom/samples/MTOMLogSample.java}