View Javadoc
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 &lt;soap:Envelope> to &lt;/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 }