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 /*
|
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 {@code this}.
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 * {@code multipart/related; boundary="--=_outer_boundary"; type="multipart/alternative"}.
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 /*
|