1 /*
   2  * Copyright (c) 1997, 2010, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package com.sun.xml.internal.ws.api.pipe;
  27 
  28 import com.sun.xml.internal.ws.api.BindingID;
  29 import com.sun.xml.internal.ws.api.WSBinding;
  30 import com.sun.xml.internal.ws.api.message.Message;
  31 import com.sun.xml.internal.ws.api.message.Packet;
  32 import com.sun.xml.internal.ws.api.server.EndpointAwareCodec;
  33 
  34 import javax.xml.stream.XMLStreamWriter;
  35 import java.io.IOException;
  36 import java.io.InputStream;
  37 import java.io.OutputStream;
  38 import java.nio.ByteBuffer;
  39 import java.nio.channels.ReadableByteChannel;
  40 import java.nio.channels.WritableByteChannel;
  41 
  42 /**
  43  * Encodes a {@link Message} (its XML infoset and attachments) to a sequence of bytes.
  44  *
  45  * <p>
  46  * This interface provides pluggability for different ways of encoding XML infoset,
  47  * such as plain XML (plus MIME attachments), XOP, and FastInfoset.
  48  *
  49  * <p>
  50  * Transport usually needs a MIME content type of the encoding, so the {@link Codec}
  51  * interface is designed to return this information. However, for some encoding
  52  * (such as XOP), the encoding may actually change based on the actual content of
  53  * {@link Message}, therefore the codec returns the content type as a result of encoding.
  54  *
  55  * <p>
  56  * {@link Codec} does not produce transport-specific information, such as HTTP headers.
  57  *
  58  * <p>
  59  * {@link Codec} is a non-reentrant object, meaning no two threads
  60  * can concurrently invoke the decode method. This allows the implementation
  61  * to easily reuse parser objects (as instance variables), which are costly otherwise.
  62  *
  63  *
  64  * <p>
  65  * {@link BindingID} determines the {@link Codec}. See {@link BindingID#createEncoder(WSBinding)}.
  66  *
  67  * @author Kohsuke Kawaguchi
  68  * @see EndpointAwareCodec
  69  */
  70 public interface Codec {
  71 
  72     /**
  73      * Get the MIME type associated with this Codec.
  74      * <p>
  75      * If available the MIME type will represent the media that the codec
  76      * encodes and decodes.
  77      *
  78      * The MIME type returned will be the most general representation independent
  79      * of an instance of this MIME type utilized as a MIME content-type.
  80      *
  81      * @return
  82      *      null if the MIME type can't be determined by the <code>Codec</code>
  83      *      implementation. Otherwise the MIME type is returned.
  84      */
  85     public String getMimeType();
  86 
  87     /**
  88      * If the MIME content-type of the encoding is known statically
  89      * then this method returns it.
  90      *
  91      * <p>
  92      * Transports often need to write the content type before it writes
  93      * the message body, and since the encode method returns the content type
  94      * after the body is written, it requires a buffering.
  95      *
  96      * For those {@link Codec}s that always use a constant content type,
  97      * This method allows a transport to streamline the write operation.
  98      *
  99      * @return
 100      *      null if the content-type can't be determined in short of
 101      *      encodin the packet. Otherwise content type for this {@link Packet},
 102      *      such as "application/xml".
 103      */
 104     ContentType getStaticContentType(Packet packet);
 105 
 106     /**
 107      * Encodes an XML infoset portion of the {@link Message}
 108      * (from &lt;soap:Envelope> to &lt;/soap:Envelope>).
 109      *
 110      * <p>
 111      * Internally, this method is most likely invoke {@link Message#writeTo(XMLStreamWriter)}
 112      * to turn the message into infoset.
 113      *
 114      * @param packet
 115      * @param out
 116      *      Must not be null. The caller is responsible for closing the stream,
 117      *      not the callee.
 118      *
 119      * @return
 120      *      The MIME content type of the encoded message (such as "application/xml").
 121      *      This information is often ncessary by transport.
 122      *
 123      * @throws IOException
 124      *      if a {@link OutputStream} throws {@link IOException}.
 125      */
 126     ContentType encode( Packet packet, OutputStream out ) throws IOException;
 127 
 128     /**
 129      * The version of {@link #encode(Packet,OutputStream)}
 130      * that writes to NIO {@link ByteBuffer}.
 131      *
 132      * <p>
 133      * TODO: for the convenience of implementation, write
 134      * an adapter that wraps {@link WritableByteChannel} to {@link OutputStream}.
 135      */
 136     ContentType encode( Packet packet, WritableByteChannel buffer );
 137 
 138     /*
 139      * The following methods need to be documented and implemented.
 140      *
 141      * Such methods will be used by a client side
 142      * transport pipe that implements the ClientEdgePipe.
 143      *
 144     String encode( InputStreamMessage message, OutputStream out ) throws IOException;
 145     String encode( InputStreamMessage message, WritableByteChannel buffer );
 146     */
 147 
 148     /**
 149      * Creates a copy of this {@link Codec}.
 150      *
 151      * <p>
 152      * Since {@link Codec} instance is not re-entrant, the caller
 153      * who needs to encode two {@link Message}s simultaneously will
 154      * want to have two {@link Codec} instances. That's what this
 155      * method produces.
 156      *
 157      * <h3>Implentation Note</h3>
 158      * <p>
 159      * Note that this method might be invoked by one thread while
 160      * another thread is executing one of the {@link #encode} methods.
 161      * <!-- or otherwise you'd always have to maintain one idle copy -->
 162      * <!-- just so that you can make copies from -->
 163      * This should be OK because you'll be only copying things that
 164      * are thread-safe, and creating new ones for thread-unsafe resources,
 165      * but please let us know if this contract is difficult.
 166      *
 167      * @return
 168      *      always non-null valid {@link Codec} that performs
 169      *      the encoding work in the same way --- that is, if you
 170      *      copy an FI codec, you'll get another FI codec.
 171      *
 172      *      <p>
 173      *      Once copied, two {@link Codec}s may be invoked from
 174      *      two threads concurrently; therefore, they must not share
 175      *      any state that requires isolation (such as temporary buffer.)
 176      *
 177      *      <p>
 178      *      If the {@link Codec} implementation is already
 179      *      re-entrant and multi-thread safe to begin with,
 180      *      then this method may simply return <tt>this</tt>.
 181      */
 182     Codec copy();
 183 
 184     /**
 185      * Reads bytes from {@link InputStream} and constructs a {@link Message}.
 186      *
 187      * <p>
 188      * The design encourages lazy decoding of a {@link Message}, where
 189      * a {@link Message} is returned even before the whole message is parsed,
 190      * and additional parsing is done as the {@link Message} body is read along.
 191      * A {@link Codec} is most likely have its own implementation of {@link Message}
 192      * for this purpose.
 193      *
 194      * @param in
 195      *      the data to be read into a {@link Message}. The transport would have
 196      *      read any transport-specific header before it passes an {@link InputStream},
 197      *      and {@link InputStream} is expected to be read until EOS. Never null.
 198      *
 199      *      <p>
 200      *      Some transports, such as SMTP, may 'encode' data into another format
 201      *      (such as uuencode, base64, etc.) It is the caller's responsibility to
 202      *      'decode' these transport-level encoding before it passes data into
 203      *      {@link Codec}.
 204      *
 205      * @param contentType
 206      *      The MIME content type (like "application/xml") of this byte stream.
 207      *      Thie text includes all the sub-headers of the content-type header. Therefore,
 208      *      in more complex case, this could be something like
 209      *      <tt>multipart/related; boundary="--=_outer_boundary"; type="multipart/alternative"</tt>.
 210      *      This parameter must not be null.
 211      *
 212      * @param response
 213      *      The parsed {@link Message} will be set to this {@link Packet}.
 214      *      {@link Codec} may add additional properties to this {@link Packet}.
 215      *      On a successful method completion, a {@link Packet} must contain a
 216      *      {@link Message}.
 217      *
 218      * @throws IOException
 219      *      if {@link InputStream} throws an exception.
 220      */
 221     void decode( InputStream in, String contentType, Packet response ) throws IOException;
 222 
 223     /**
 224      *
 225      * @see #decode(InputStream, String, Packet)
 226      */
 227     void decode( ReadableByteChannel in, String contentType, Packet response );
 228 
 229     /*
 230      * The following methods need to be documented and implemented.
 231      *
 232      * Such methods will be used by a server side
 233      * transport pipe that can support the invocation of methods on a
 234      * ServerEdgePipe.
 235      *
 236     XMLStreamReaderMessage decode( InputStream in, String contentType ) throws IOException;
 237     XMLStreamReaderMessage decode( ReadableByteChannel in, String contentType );
 238     */
 239 }