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 Tue Mar 06 16:09:35 2012 -0800 1.3 @@ -0,0 +1,239 @@ 1.4 +/* 1.5 + * Copyright (c) 1997, 2010, 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} is a non-reentrant object, meaning no two threads 1.63 + * can concurrently invoke the decode method. This allows the implementation 1.64 + * to easily reuse parser objects (as instance variables), which are costly otherwise. 1.65 + * 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 + * @see EndpointAwareCodec 1.72 + */ 1.73 +public interface Codec { 1.74 + 1.75 + /** 1.76 + * Get the MIME type associated with this Codec. 1.77 + * <p> 1.78 + * If available the MIME type will represent the media that the codec 1.79 + * encodes and decodes. 1.80 + * 1.81 + * The MIME type returned will be the most general representation independent 1.82 + * of an instance of this MIME type utilized as a MIME content-type. 1.83 + * 1.84 + * @return 1.85 + * null if the MIME type can't be determined by the <code>Codec</code> 1.86 + * implementation. Otherwise the MIME type is returned. 1.87 + */ 1.88 + public String getMimeType(); 1.89 + 1.90 + /** 1.91 + * If the MIME content-type of the encoding is known statically 1.92 + * then this method returns it. 1.93 + * 1.94 + * <p> 1.95 + * Transports often need to write the content type before it writes 1.96 + * the message body, and since the encode method returns the content type 1.97 + * after the body is written, it requires a buffering. 1.98 + * 1.99 + * For those {@link Codec}s that always use a constant content type, 1.100 + * This method allows a transport to streamline the write operation. 1.101 + * 1.102 + * @return 1.103 + * null if the content-type can't be determined in short of 1.104 + * encodin the packet. Otherwise content type for this {@link Packet}, 1.105 + * such as "application/xml". 1.106 + */ 1.107 + ContentType getStaticContentType(Packet packet); 1.108 + 1.109 + /** 1.110 + * Encodes an XML infoset portion of the {@link Message} 1.111 + * (from <soap:Envelope> to </soap:Envelope>). 1.112 + * 1.113 + * <p> 1.114 + * Internally, this method is most likely invoke {@link Message#writeTo(XMLStreamWriter)} 1.115 + * to turn the message into infoset. 1.116 + * 1.117 + * @param packet 1.118 + * @param out 1.119 + * Must not be null. The caller is responsible for closing the stream, 1.120 + * not the callee. 1.121 + * 1.122 + * @return 1.123 + * The MIME content type of the encoded message (such as "application/xml"). 1.124 + * This information is often ncessary by transport. 1.125 + * 1.126 + * @throws IOException 1.127 + * if a {@link OutputStream} throws {@link IOException}. 1.128 + */ 1.129 + ContentType encode( Packet packet, OutputStream out ) throws IOException; 1.130 + 1.131 + /** 1.132 + * The version of {@link #encode(Packet,OutputStream)} 1.133 + * that writes to NIO {@link ByteBuffer}. 1.134 + * 1.135 + * <p> 1.136 + * TODO: for the convenience of implementation, write 1.137 + * an adapter that wraps {@link WritableByteChannel} to {@link OutputStream}. 1.138 + */ 1.139 + ContentType encode( Packet packet, WritableByteChannel buffer ); 1.140 + 1.141 + /* 1.142 + * The following methods need to be documented and implemented. 1.143 + * 1.144 + * Such methods will be used by a client side 1.145 + * transport pipe that implements the ClientEdgePipe. 1.146 + * 1.147 + String encode( InputStreamMessage message, OutputStream out ) throws IOException; 1.148 + String encode( InputStreamMessage message, WritableByteChannel buffer ); 1.149 + */ 1.150 + 1.151 + /** 1.152 + * Creates a copy of this {@link Codec}. 1.153 + * 1.154 + * <p> 1.155 + * Since {@link Codec} instance is not re-entrant, the caller 1.156 + * who needs to encode two {@link Message}s simultaneously will 1.157 + * want to have two {@link Codec} instances. That's what this 1.158 + * method produces. 1.159 + * 1.160 + * <h3>Implentation Note</h3> 1.161 + * <p> 1.162 + * Note that this method might be invoked by one thread while 1.163 + * another thread is executing one of the {@link #encode} methods. 1.164 + * <!-- or otherwise you'd always have to maintain one idle copy --> 1.165 + * <!-- just so that you can make copies from --> 1.166 + * This should be OK because you'll be only copying things that 1.167 + * are thread-safe, and creating new ones for thread-unsafe resources, 1.168 + * but please let us know if this contract is difficult. 1.169 + * 1.170 + * @return 1.171 + * always non-null valid {@link Codec} that performs 1.172 + * the encoding work in the same way --- that is, if you 1.173 + * copy an FI codec, you'll get another FI codec. 1.174 + * 1.175 + * <p> 1.176 + * Once copied, two {@link Codec}s may be invoked from 1.177 + * two threads concurrently; therefore, they must not share 1.178 + * any state that requires isolation (such as temporary buffer.) 1.179 + * 1.180 + * <p> 1.181 + * If the {@link Codec} implementation is already 1.182 + * re-entrant and multi-thread safe to begin with, 1.183 + * then this method may simply return <tt>this</tt>. 1.184 + */ 1.185 + Codec copy(); 1.186 + 1.187 + /** 1.188 + * Reads bytes from {@link InputStream} and constructs a {@link Message}. 1.189 + * 1.190 + * <p> 1.191 + * The design encourages lazy decoding of a {@link Message}, where 1.192 + * a {@link Message} is returned even before the whole message is parsed, 1.193 + * and additional parsing is done as the {@link Message} body is read along. 1.194 + * A {@link Codec} is most likely have its own implementation of {@link Message} 1.195 + * for this purpose. 1.196 + * 1.197 + * @param in 1.198 + * the data to be read into a {@link Message}. The transport would have 1.199 + * read any transport-specific header before it passes an {@link InputStream}, 1.200 + * and {@link InputStream} is expected to be read until EOS. Never null. 1.201 + * 1.202 + * <p> 1.203 + * Some transports, such as SMTP, may 'encode' data into another format 1.204 + * (such as uuencode, base64, etc.) It is the caller's responsibility to 1.205 + * 'decode' these transport-level encoding before it passes data into 1.206 + * {@link Codec}. 1.207 + * 1.208 + * @param contentType 1.209 + * The MIME content type (like "application/xml") of this byte stream. 1.210 + * Thie text includes all the sub-headers of the content-type header. Therefore, 1.211 + * in more complex case, this could be something like 1.212 + * <tt>multipart/related; boundary="--=_outer_boundary"; type="multipart/alternative"</tt>. 1.213 + * This parameter must not be null. 1.214 + * 1.215 + * @param response 1.216 + * The parsed {@link Message} will be set to this {@link Packet}. 1.217 + * {@link Codec} may add additional properties to this {@link Packet}. 1.218 + * On a successful method completion, a {@link Packet} must contain a 1.219 + * {@link Message}. 1.220 + * 1.221 + * @throws IOException 1.222 + * if {@link InputStream} throws an exception. 1.223 + */ 1.224 + void decode( InputStream in, String contentType, Packet response ) throws IOException; 1.225 + 1.226 + /** 1.227 + * 1.228 + * @see #decode(InputStream, String, Packet) 1.229 + */ 1.230 + void decode( ReadableByteChannel in, String contentType, Packet response ); 1.231 + 1.232 + /* 1.233 + * The following methods need to be documented and implemented. 1.234 + * 1.235 + * Such methods will be used by a server side 1.236 + * transport pipe that can support the invocation of methods on a 1.237 + * ServerEdgePipe. 1.238 + * 1.239 + XMLStreamReaderMessage decode( InputStream in, String contentType ) throws IOException; 1.240 + XMLStreamReaderMessage decode( ReadableByteChannel in, String contentType ); 1.241 + */ 1.242 +}