Coverage Report - wjhk.jupload2.upload.helper.ByteArrayEncoder
 
Classes in this File Line Coverage Branch Coverage Complexity
ByteArrayEncoder
N/A
N/A
1
 
 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  
 }