org.apache.axiom.ext.stax.datahandler.DataHandlerWriter Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of com.liferay.sharepoint.soap.repository
Liferay Sharepoint SOAP Repository
There is a newer version: 5.0.22
/*
 * 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.ext.stax.datahandler;

import java.io.IOException;

import javax.activation.DataHandler;
import javax.xml.stream.XMLStreamException;

/**
 * Extension interface for {@link javax.xml.stream.XMLStreamWriter} implementations that can
 * receive base64 encoded binary content as {@link DataHandler} objects. A stream writer
 * implementing this extension may write the binary data as base64 encoded character data
 * or using some optimization such as XOP/MTOM.
 * 
 * All the requirements specified in {@link org.apache.axiom.ext.stax} apply to
 * this extension interface. In particular,
 * a consumer MUST use {@link javax.xml.stream.XMLStreamWriter#getProperty(String)} with the property
 * name defined by {@link #PROPERTY} to get a reference to this extension interface.
 * 

 * The interface defines two methods to write binary content, one that takes a {@link DataHandler}
 * argument and one with a {@link DataHandlerProvider} argument. The first should be used when
 * the content is immediately available, while the second supports deferred loading of the data
 * handler. The meaning of the contentID and optimize arguments is
 * the same for both methods:
 * 

 *   contentID
 *   

 *     A content ID of the binary content, if available. The semantics of this argument are
 *     similar to those defined for the return value of the
 *     {@link DataHandlerReader#getContentID()} method:
 *     
 *       This argument should only be set if a content ID has been used
 *           previously in an interaction with another component or system.
 *           The caller SHOULD NOT generate a new content ID solely for the
 *           purpose of invoking the extension.
 *       
The argument must be a raw content ID.
 *       
The implementation MUST NOT make any assumption about the uniqueness or validity
 *           of the content ID. It MAY ignore the supplied value.
 *     
 *   
optimize
 *   

 *     Specifies if binary content is eligible for optimization (e.g. using XOP) or if it should
 *     be serialized as base64. This is only an indication and the implementation MAY choose
 *     to override this value or ignore it entirely.
 * 
 * Instead of interacting directly with this extension interface, the consumer may use the
 * {@link org.apache.axiom.util.stax.XMLStreamWriterUtils#writeDataHandler(javax.xml.stream.XMLStreamWriter, DataHandler, String, boolean)} or
 * {@link org.apache.axiom.util.stax.XMLStreamWriterUtils#writeDataHandler(javax.xml.stream.XMLStreamWriter, DataHandlerProvider, String, boolean)}
 * utility methods. These methods make the processing of binary data entirely transparent for
 * the caller.
 */
public interface DataHandlerWriter {
    /**
     * The name of the property used to look up this extension interface from a
     * {@link javax.xml.stream.XMLStreamWriter} implementation.
     */
    String PROPERTY = DataHandlerWriter.class.getName();

    /**
     * Write binary content to the stream. The implementation may choose to write the data as base64
     * encoded character data or using an optimization protocol such as XOP/MTOM.
     * 
     * @param dataHandler
     *            the binary content to write
     * @param contentID
     *            an existing content ID for the binary data (see above)
     * @param optimize
     *            indicates whether the content is eligible for optimization (see above)
     * @throws IOException
     *             if an error occurs while reading from the data handler
     * @throws XMLStreamException
     *             if an error occurs while writing to the underlying stream
     */
    void writeDataHandler(DataHandler dataHandler, String contentID, boolean optimize)
            throws IOException, XMLStreamException;

    /**
     * Write binary content to the stream. This method allows the implementation to defer loading of
     * the content. More precisely, if the implementation decides to use an optimization scheme such
     * as XOP, then the content will not be written immediately to the underlying stream, but only
     * after the XML infoset is complete. If the caller uses this method, the implementation can
     * defer the actual loading of the binary content.
     * 
     * @param dataHandlerProvider
     *            the binary content to write
     * @param contentID
     *            an existing content ID for the binary data (see above)
     * @param optimize
     *            indicates whether the content is eligible for optimization (see above)
     * @throws IOException
     *             If an error occurs while reading from the data handler. Since the implementation
     *             is free to override the supplied optimize argument, it may attempt
     *             to load the binary data immediately. Because this operation may fail, the method
     *             must declare this exception.
     * @throws XMLStreamException
     *             if an error occurs while writing to the underlying stream
     */
    void writeDataHandler(DataHandlerProvider dataHandlerProvider, String contentID,
            boolean optimize) throws IOException, XMLStreamException;
}