1 package wjhk.jupload2.upload.helper;
2
3 import wjhk.jupload2.context.JUploadContext;
4 import wjhk.jupload2.exception.JUploadIOException;
5 import wjhk.jupload2.upload.FileUploadThreadHTTP;
6
7 /**
8 * This interface contains all technical methods to encode data, into a given
9 * character encoding. This is especially useful to encode the HTTP output to
10 * the server. <BR>
11 * <BR>
12 * Each appendXxxx method returns the current instance. This allows easy
13 * concatanation of calls to this class. For instance:<BR>
14 *
15 * <PRE>
16 * bae.append(a).appendFileProperty(b, c).append(d);
17 * </PRE>
18 *
19 * @author etienne_sf
20 * @see FileUploadThreadHTTP
21 */
22 public interface ByteArrayEncoder {
23
24 /**
25 * Closes the encoding writer, and prepares the encoded length and byte
26 * array. This method must be called before call to
27 * {@link #getEncodedLength()} and {@link #getEncodedByteArray()}.
28 * <B>Note:</B> After a call to this method, you can not append any new data
29 * to the encoder.
30 *
31 * @throws JUploadIOException Encapsulates any IO Exception
32 */
33 public void close() throws JUploadIOException;
34
35 /**
36 * Append a string, to be encoded at the current end of the byte array.
37 *
38 * @param str The string to append and encode.
39 * @return Return the current ByteArrayEncoder, to allow chained call (see
40 * explanation, here above).
41 * @throws JUploadIOException
42 */
43 public ByteArrayEncoder append(String str) throws JUploadIOException;
44
45 /**
46 * Append a byte, to be encoded at the current end of the byte array. he
47 * byte to be written is the eight low-order bits of the argument b. The 24
48 * high-order bits of b are ignored.
49 *
50 * @param b Writes the specified byte to this output stream.
51 * @return Return the current ByteArrayEncoder, to allow chained call (see
52 * explanation, here above).
53 * @throws JUploadIOException
54 */
55 public ByteArrayEncoder append(int b) throws JUploadIOException;
56
57 /**
58 * Append a stream, to be encoded at the current end of the byte array.
59 *
60 * @param b
61 * @return Return the current ByteArrayEncoder, to allow chained call (see
62 * explanation, here above).
63 * @throws JUploadIOException
64 */
65 public ByteArrayEncoder append(byte[] b) throws JUploadIOException;
66
67 /**
68 * Append a property, name and value. It will be encoded at the current end
69 * of the byte array.<BR>
70 * Note: After the last call to appendTextProperty, you should call
71 * {@link #appendEndPropertyList()}, to properly finish the property list.
72 * In HTTP mode, it will add the last boundary, at a specific format.
73 *
74 * @param name Name of the property to be added
75 * @param value Value of this property for the current file. It's up to the
76 * caller to call this method at the right time.
77 * @param index Index of the file concerned by this value. -1 if this is a
78 * global parameter.
79 * @return Return the current ByteArrayEncoder, to allow chained call (see
80 * explanation, here above).
81 * @throws JUploadIOException
82 * @see #appendEndPropertyList()
83 */
84 public ByteArrayEncoder appendTextProperty(String name, String value,
85 int index) throws JUploadIOException;
86
87 /**
88 * Finish a property list. In HTTP mode, the last boundary for the
89 * form/multipart content is added. After a call to this method, no more
90 * property may be written. If several ByteEncoder are used, it's up to the
91 * called to call this mehod only once, for the ByteEncoder that will be
92 * written last on the request.
93 *
94 * @return Return the current ByteArrayEncoder, to allow chained call (see
95 * explanation, here above).
96 * @throws JUploadIOException
97 */
98 public ByteArrayEncoder appendEndPropertyList() throws JUploadIOException;
99
100 /**
101 * Add to the current encoder all properties contained in the given HTML
102 * form. There is no index for the current file: all the form parameters are
103 * global parameters (index will be set to -1 when calling
104 * {@link #appendTextProperty(String, String, int)}.
105 *
106 * @param formname The HTML form name. This method will get the data from
107 * this form, by using the {@link JUploadContext#getApplet()}
108 * method.
109 * @return Return the current ByteArrayEncoder, to allow chained call (see
110 * explanation, here above).
111 * @throws JUploadIOException
112 */
113 public ByteArrayEncoder appendFormVariables(String formname)
114 throws JUploadIOException;
115
116 /**
117 * Append a string, to be encoded at the current end of the byte array.
118 *
119 * @param bae The ByteArrayEncoder whose encoding result should be appended
120 * to the current encoder. bae must be closed, before being
121 * appended.
122 * @return Return the current ByteArrayEncoder, to allow chained call (see
123 * explanation, here above).
124 * @throws JUploadIOException This exception is thrown when this method is
125 * called on a non-closed encoder.
126 */
127 public ByteArrayEncoder append(ByteArrayEncoder bae)
128 throws JUploadIOException;
129
130 /**
131 * @return the closed
132 */
133 public boolean isClosed();
134
135 /**
136 * Gets the HTTP boundary, that separate the form variables.
137 *
138 * @return The HTTP boundary, that was generated when the instance was
139 * created.
140 */
141 public String getBoundary();
142
143 /**
144 * @return the encoding
145 */
146 public String getEncoding();
147
148 /**
149 * Get the length of the encoded result. Can be called only once the encoder
150 * has been closed.
151 *
152 * @return the encodedLength
153 * @throws JUploadIOException This exception is thrown when this method is
154 * called on a non-closed encoder.
155 */
156 public int getEncodedLength() throws JUploadIOException;
157
158 /**
159 * Get the encoded result. Can be called only once the encoder has been
160 * closed.
161 *
162 * @return the encodedByteArray
163 * @throws JUploadIOException This exception is thrown when this method is
164 * called on a non-closed encoder.
165 */
166 public byte[] getEncodedByteArray() throws JUploadIOException;
167
168 /**
169 * Get the String that matches the encoded result. Can be called only once
170 * the encoder has been closed.
171 *
172 * @return the String that has been encoded.
173 * @throws JUploadIOException This exception is thrown when this method is
174 * called on a non-closed encoder.
175 */
176 public String getString() throws JUploadIOException;
177
178 }