View Javadoc
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 }