1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/src/share/jaxws_classes/com/sun/xml/internal/ws/api/pipe/Codec.java Wed Apr 27 01:27:09 2016 +0800
1.3 @@ -0,0 +1,241 @@
1.4 +/*
1.5 + * Copyright (c) 1997, 2013, Oracle and/or its affiliates. All rights reserved.
1.6 + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
1.7 + *
1.8 + * This code is free software; you can redistribute it and/or modify it
1.9 + * under the terms of the GNU General Public License version 2 only, as
1.10 + * published by the Free Software Foundation. Oracle designates this
1.11 + * particular file as subject to the "Classpath" exception as provided
1.12 + * by Oracle in the LICENSE file that accompanied this code.
1.13 + *
1.14 + * This code is distributed in the hope that it will be useful, but WITHOUT
1.15 + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
1.16 + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
1.17 + * version 2 for more details (a copy is included in the LICENSE file that
1.18 + * accompanied this code).
1.19 + *
1.20 + * You should have received a copy of the GNU General Public License version
1.21 + * 2 along with this work; if not, write to the Free Software Foundation,
1.22 + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
1.23 + *
1.24 + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
1.25 + * or visit www.oracle.com if you need additional information or have any
1.26 + * questions.
1.27 + */
1.28 +
1.29 +package com.sun.xml.internal.ws.api.pipe;
1.30 +
1.31 +import com.sun.xml.internal.ws.api.BindingID;
1.32 +import com.sun.xml.internal.ws.api.WSBinding;
1.33 +import com.sun.xml.internal.ws.api.message.Message;
1.34 +import com.sun.xml.internal.ws.api.message.Packet;
1.35 +import com.sun.xml.internal.ws.api.server.EndpointAwareCodec;
1.36 +
1.37 +import javax.xml.stream.XMLStreamWriter;
1.38 +import java.io.IOException;
1.39 +import java.io.InputStream;
1.40 +import java.io.OutputStream;
1.41 +import java.nio.ByteBuffer;
1.42 +import java.nio.channels.ReadableByteChannel;
1.43 +import java.nio.channels.WritableByteChannel;
1.44 +
1.45 +/**
1.46 + * Encodes a {@link Message} (its XML infoset and attachments) to a sequence of bytes.
1.47 + *
1.48 + * <p>
1.49 + * This interface provides pluggability for different ways of encoding XML infoset,
1.50 + * such as plain XML (plus MIME attachments), XOP, and FastInfoset.
1.51 + *
1.52 + * <p>
1.53 + * Transport usually needs a MIME content type of the encoding, so the {@link Codec}
1.54 + * interface is designed to return this information. However, for some encoding
1.55 + * (such as XOP), the encoding may actually change based on the actual content of
1.56 + * {@link Message}, therefore the codec returns the content type as a result of encoding.
1.57 + *
1.58 + * <p>
1.59 + * {@link Codec} does not produce transport-specific information, such as HTTP headers.
1.60 + *
1.61 + * <p>
1.62 + * {@link Codec} implementations should be thread-safe; a codec instance could be used
1.63 + * concurrently in multiple threads. If a codec have to generate or use a per-request
1.64 + * state, the codec implementation must store the state in the Packet instead of using an
1.65 + * instance variable of the codec implementation.
1.66 + *
1.67 + * <p>
1.68 + * {@link BindingID} determines the {@link Codec}. See {@link BindingID#createEncoder(WSBinding)}.
1.69 + *
1.70 + * @author Kohsuke Kawaguchi
1.71 + * @author shih-chang.chen@oracle.com
1.72 + *
1.73 + * @see EndpointAwareCodec
1.74 + */
1.75 +public interface Codec {
1.76 +
1.77 + /**
1.78 + * Get the MIME type associated with this Codec.
1.79 + * <p>
1.80 + * If available the MIME type will represent the media that the codec
1.81 + * encodes and decodes.
1.82 + *
1.83 + * The MIME type returned will be the most general representation independent
1.84 + * of an instance of this MIME type utilized as a MIME content-type.
1.85 + *
1.86 + * @return
1.87 + * null if the MIME type can't be determined by the <code>Codec</code>
1.88 + * implementation. Otherwise the MIME type is returned.
1.89 + */
1.90 + public String getMimeType();
1.91 +
1.92 + /**
1.93 + * If the MIME content-type of the encoding is known statically
1.94 + * then this method returns it.
1.95 + *
1.96 + * <p>
1.97 + * Transports often need to write the content type before it writes
1.98 + * the message body, and since the encode method returns the content type
1.99 + * after the body is written, it requires a buffering.
1.100 + *
1.101 + * For those {@link Codec}s that always use a constant content type,
1.102 + * This method allows a transport to streamline the write operation.
1.103 + *
1.104 + * @return
1.105 + * null if the content-type can't be determined in short of
1.106 + * encodin the packet. Otherwise content type for this {@link Packet},
1.107 + * such as "application/xml".
1.108 + */
1.109 + ContentType getStaticContentType(Packet packet);
1.110 +
1.111 + /**
1.112 + * Encodes an XML infoset portion of the {@link Message}
1.113 + * (from <soap:Envelope> to </soap:Envelope>).
1.114 + *
1.115 + * <p>
1.116 + * Internally, this method is most likely invoke {@link Message#writeTo(XMLStreamWriter)}
1.117 + * to turn the message into infoset.
1.118 + *
1.119 + * @param packet
1.120 + * @param out
1.121 + * Must not be null. The caller is responsible for closing the stream,
1.122 + * not the callee.
1.123 + *
1.124 + * @return
1.125 + * The MIME content type of the encoded message (such as "application/xml").
1.126 + * This information is often ncessary by transport.
1.127 + *
1.128 + * @throws IOException
1.129 + * if a {@link OutputStream} throws {@link IOException}.
1.130 + */
1.131 + ContentType encode( Packet packet, OutputStream out ) throws IOException;
1.132 +
1.133 + /**
1.134 + * The version of {@link #encode(Packet,OutputStream)}
1.135 + * that writes to NIO {@link ByteBuffer}.
1.136 + *
1.137 + * <p>
1.138 + * TODO: for the convenience of implementation, write
1.139 + * an adapter that wraps {@link WritableByteChannel} to {@link OutputStream}.
1.140 + */
1.141 + ContentType encode( Packet packet, WritableByteChannel buffer );
1.142 +
1.143 + /*
1.144 + * The following methods need to be documented and implemented.
1.145 + *
1.146 + * Such methods will be used by a client side
1.147 + * transport pipe that implements the ClientEdgePipe.
1.148 + *
1.149 + String encode( InputStreamMessage message, OutputStream out ) throws IOException;
1.150 + String encode( InputStreamMessage message, WritableByteChannel buffer );
1.151 + */
1.152 +
1.153 + /**
1.154 + * Creates a copy of this {@link Codec}.
1.155 + *
1.156 + * <p>
1.157 + * Since {@link Codec} instance is not re-entrant, the caller
1.158 + * who needs to encode two {@link Message}s simultaneously will
1.159 + * want to have two {@link Codec} instances. That's what this
1.160 + * method produces.
1.161 + *
1.162 + * <h3>Implentation Note</h3>
1.163 + * <p>
1.164 + * Note that this method might be invoked by one thread while
1.165 + * another thread is executing one of the {@link #encode} methods.
1.166 + * <!-- or otherwise you'd always have to maintain one idle copy -->
1.167 + * <!-- just so that you can make copies from -->
1.168 + * This should be OK because you'll be only copying things that
1.169 + * are thread-safe, and creating new ones for thread-unsafe resources,
1.170 + * but please let us know if this contract is difficult.
1.171 + *
1.172 + * @return
1.173 + * always non-null valid {@link Codec} that performs
1.174 + * the encoding work in the same way --- that is, if you
1.175 + * copy an FI codec, you'll get another FI codec.
1.176 + *
1.177 + * <p>
1.178 + * Once copied, two {@link Codec}s may be invoked from
1.179 + * two threads concurrently; therefore, they must not share
1.180 + * any state that requires isolation (such as temporary buffer.)
1.181 + *
1.182 + * <p>
1.183 + * If the {@link Codec} implementation is already
1.184 + * re-entrant and multi-thread safe to begin with,
1.185 + * then this method may simply return <tt>this</tt>.
1.186 + */
1.187 + Codec copy();
1.188 +
1.189 + /**
1.190 + * Reads bytes from {@link InputStream} and constructs a {@link Message}.
1.191 + *
1.192 + * <p>
1.193 + * The design encourages lazy decoding of a {@link Message}, where
1.194 + * a {@link Message} is returned even before the whole message is parsed,
1.195 + * and additional parsing is done as the {@link Message} body is read along.
1.196 + * A {@link Codec} is most likely have its own implementation of {@link Message}
1.197 + * for this purpose.
1.198 + *
1.199 + * @param in
1.200 + * the data to be read into a {@link Message}. The transport would have
1.201 + * read any transport-specific header before it passes an {@link InputStream},
1.202 + * and {@link InputStream} is expected to be read until EOS. Never null.
1.203 + *
1.204 + * <p>
1.205 + * Some transports, such as SMTP, may 'encode' data into another format
1.206 + * (such as uuencode, base64, etc.) It is the caller's responsibility to
1.207 + * 'decode' these transport-level encoding before it passes data into
1.208 + * {@link Codec}.
1.209 + *
1.210 + * @param contentType
1.211 + * The MIME content type (like "application/xml") of this byte stream.
1.212 + * Thie text includes all the sub-headers of the content-type header. Therefore,
1.213 + * in more complex case, this could be something like
1.214 + * <tt>multipart/related; boundary="--=_outer_boundary"; type="multipart/alternative"</tt>.
1.215 + * This parameter must not be null.
1.216 + *
1.217 + * @param response
1.218 + * The parsed {@link Message} will be set to this {@link Packet}.
1.219 + * {@link Codec} may add additional properties to this {@link Packet}.
1.220 + * On a successful method completion, a {@link Packet} must contain a
1.221 + * {@link Message}.
1.222 + *
1.223 + * @throws IOException
1.224 + * if {@link InputStream} throws an exception.
1.225 + */
1.226 + void decode( InputStream in, String contentType, Packet response ) throws IOException;
1.227 +
1.228 + /**
1.229 + *
1.230 + * @see #decode(InputStream, String, Packet)
1.231 + */
1.232 + void decode( ReadableByteChannel in, String contentType, Packet response );
1.233 +
1.234 + /*
1.235 + * The following methods need to be documented and implemented.
1.236 + *
1.237 + * Such methods will be used by a server side
1.238 + * transport pipe that can support the invocation of methods on a
1.239 + * ServerEdgePipe.
1.240 + *
1.241 + XMLStreamReaderMessage decode( InputStream in, String contentType ) throws IOException;
1.242 + XMLStreamReaderMessage decode( ReadableByteChannel in, String contentType );
1.243 + */
1.244 +}
