1 /*
2 * Copyright (c) 1997, 2013, 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} implementations should be thread-safe; a codec instance could be used
60 * concurrently in multiple threads. If a codec have to generate or use a per-request
61 * state, the codec implementation must store the state in the Packet instead of using an
62 * instance variable of the codec implementation.
63 *
64 * <p>
65 * {@link BindingID} determines the {@link Codec}. See {@link BindingID#createEncoder(WSBinding)}.
66 *
67 * @author Kohsuke Kawaguchi
68 * @author shih-chang.chen@oracle.com
69 *
70 * @see EndpointAwareCodec
71 */
72 public interface Codec {
73
74 /**
75 * Get the MIME type associated with this Codec.
76 * <p>
77 * If available the MIME type will represent the media that the codec
78 * encodes and decodes.
79 *
80 * The MIME type returned will be the most general representation independent
81 * of an instance of this MIME type utilized as a MIME content-type.
82 *
83 * @return
84 * null if the MIME type can't be determined by the <code>Codec</code>
85 * implementation. Otherwise the MIME type is returned.
86 */
87 public String getMimeType();
88
89 /**
90 * If the MIME content-type of the encoding is known statically
91 * then this method returns it.
92 *
93 * <p>
94 * Transports often need to write the content type before it writes
95 * the message body, and since the encode method returns the content type
96 * after the body is written, it requires a buffering.
97 *
98 * For those {@link Codec}s that always use a constant content type,
99 * This method allows a transport to streamline the write operation.
100 *
101 * @return
102 * null if the content-type can't be determined in short of
103 * encodin the packet. Otherwise content type for this {@link Packet},
104 * such as "application/xml".
105 */
106 ContentType getStaticContentType(Packet packet);
107
108 /**
109 * Encodes an XML infoset portion of the {@link Message}
110 * (from <soap:Envelope> to </soap:Envelope>).
111 *
112 * <p>
113 * Internally, this method is most likely invoke {@link Message#writeTo(XMLStreamWriter)}
114 * to turn the message into infoset.
115 *
116 * @param packet
117 * @param out
118 * Must not be null. The caller is responsible for closing the stream,
119 * not the callee.
120 *
121 * @return
122 * The MIME content type of the encoded message (such as "application/xml").
123 * This information is often ncessary by transport.
124 *
125 * @throws IOException
126 * if a {@link OutputStream} throws {@link IOException}.
127 */
128 ContentType encode( Packet packet, OutputStream out ) throws IOException;
129
130 /**
131 * The version of {@link #encode(Packet,OutputStream)}
132 * that writes to NIO {@link ByteBuffer}.
133 *
134 * <p>
135 * TODO: for the convenience of implementation, write
136 * an adapter that wraps {@link WritableByteChannel} to {@link OutputStream}.
137 */
138 ContentType encode( Packet packet, WritableByteChannel buffer );
139
140 /*
141 * The following methods need to be documented and implemented.
142 *
143 * Such methods will be used by a client side
144 * transport pipe that implements the ClientEdgePipe.
145 *
146 String encode( InputStreamMessage message, OutputStream out ) throws IOException;
147 String encode( InputStreamMessage message, WritableByteChannel buffer );
148 */
149
150 /**
151 * Creates a copy of this {@link Codec}.
152 *
153 * <p>
154 * Since {@link Codec} instance is not re-entrant, the caller
155 * who needs to encode two {@link Message}s simultaneously will
156 * want to have two {@link Codec} instances. That's what this
157 * method produces.
158 *
159 * <h3>Implentation Note</h3>
160 * <p>
161 * Note that this method might be invoked by one thread while
162 * another thread is executing one of the {@link #encode} methods.
163 * <!-- or otherwise you'd always have to maintain one idle copy -->
164 * <!-- just so that you can make copies from -->
165 * This should be OK because you'll be only copying things that
166 * are thread-safe, and creating new ones for thread-unsafe resources,
167 * but please let us know if this contract is difficult.
168 *
169 * @return
170 * always non-null valid {@link Codec} that performs
171 * the encoding work in the same way --- that is, if you
172 * copy an FI codec, you'll get another FI codec.
173 *
174 * <p>
175 * Once copied, two {@link Codec}s may be invoked from
176 * two threads concurrently; therefore, they must not share
177 * any state that requires isolation (such as temporary buffer.)
178 *
179 * <p>
180 * If the {@link Codec} implementation is already
181 * re-entrant and multi-thread safe to begin with,
182 * then this method may simply return <tt>this</tt>.
183 */
184 Codec copy();
185
186 /**
187 * Reads bytes from {@link InputStream} and constructs a {@link Message}.
188 *
189 * <p>
190 * The design encourages lazy decoding of a {@link Message}, where
191 * a {@link Message} is returned even before the whole message is parsed,
192 * and additional parsing is done as the {@link Message} body is read along.
193 * A {@link Codec} is most likely have its own implementation of {@link Message}
194 * for this purpose.
195 *
196 * @param in
197 * the data to be read into a {@link Message}. The transport would have
198 * read any transport-specific header before it passes an {@link InputStream},
199 * and {@link InputStream} is expected to be read until EOS. Never null.
200 *
201 * <p>
202 * Some transports, such as SMTP, may 'encode' data into another format
203 * (such as uuencode, base64, etc.) It is the caller's responsibility to
204 * 'decode' these transport-level encoding before it passes data into
205 * {@link Codec}.
206 *
207 * @param contentType
208 * The MIME content type (like "application/xml") of this byte stream.
209 * Thie text includes all the sub-headers of the content-type header. Therefore,
210 * in more complex case, this could be something like
211 * <tt>multipart/related; boundary="--=_outer_boundary"; type="multipart/alternative"</tt>.
212 * This parameter must not be null.
213 *
214 * @param response
215 * The parsed {@link Message} will be set to this {@link Packet}.
216 * {@link Codec} may add additional properties to this {@link Packet}.
217 * On a successful method completion, a {@link Packet} must contain a
218 * {@link Message}.
219 *
220 * @throws IOException
221 * if {@link InputStream} throws an exception.
222 */
223 void decode( InputStream in, String contentType, Packet response ) throws IOException;
224
225 /**
226 *
227 * @see #decode(InputStream, String, Packet)
228 */
229 void decode( ReadableByteChannel in, String contentType, Packet response );
230
231 /*
232 * The following methods need to be documented and implemented.
233 *
234 * Such methods will be used by a server side
235 * transport pipe that can support the invocation of methods on a
236 * ServerEdgePipe.
237 *
238 XMLStreamReaderMessage decode( InputStream in, String contentType ) throws IOException;
239 XMLStreamReaderMessage decode( ReadableByteChannel in, String contentType );
240 */
241 }