[3951] | 1 | |
---|
| 2 | <HTML> |
---|
| 3 | |
---|
| 4 | <BODY> |
---|
| 5 | |
---|
| 6 | This package contains the code that actually executes the upload (see below for a full description of the way the upload |
---|
| 7 | is executed in the JUpload code). |
---|
| 8 | It is structured around these main items: |
---|
| 9 | <DIR> |
---|
| 10 | <LI><A HREF="FileUploadManagerThread.html">FileUploadManagerThread</A>: The main class. It controls the execution of |
---|
| 11 | the upload, manages the file preparation, the progress bar, the possible exceptions... |
---|
| 12 | <LI><A HREF="FileUploadThread.html">FileUploadThread</A>: The interface of the class the execute the successives requests |
---|
| 13 | to the server. The following class implements this interface: |
---|
| 14 | <DIR> |
---|
| 15 | <LI><A HREF="DefaultFileUploadThread.html">DefaultFileUploadThread</A> is an abstract class, the provides the global |
---|
| 16 | upload mechanism to send one packet of files to the server. The packet is created by FileUploadManagerThread, |
---|
| 17 | according to the current upload policy, with parameters like: <I>maxChunkSize</I> and <I>nbFilesPerRequest</I>. All protocol |
---|
| 18 | specific methods are implemented in the following implementation, depending on the applet parameter <I>postURL</I>: |
---|
| 19 | <LI><A HREF="FileUploadThreadHTTP.html">FileUploadThreadHTTP</A> executes uploads to an HTTP server (http, https, |
---|
| 20 | proxy or not...), by using POST requests. It implements the abstract methods of DefaultFileUploadThread. |
---|
| 21 | <LI><A HREF="FileUploadThreadFTP.html">FileUploadThreadFTP</A> is the implementation for FTP servers |
---|
| 22 | </DIR> |
---|
| 23 | <LI><A HREF="UploadFileData.html">UploadFileData</A> is an implementation of the |
---|
| 24 | <A HREF="../filedata/FileData.html">wjhk.jupload2.filedata.FileData</A> interface, to add the |
---|
| 25 | <A HREF="UploadFileData.html#uploadFile(java.io.OutputStream,%20long)">uploadFile(OutputStream, long)</A> method, |
---|
| 26 | which sends the file bytes to the server. |
---|
| 27 | <LI>The <A HREF="helper/package-summary.html">wjhk.jupload2.upload.helper</A> package offers various utilities to manage the upload. |
---|
| 28 | </DIR> |
---|
| 29 | |
---|
| 30 | <H3>How works the upload</H3> |
---|
| 31 | |
---|
| 32 | <P>Here is a description of what occurs, when the user clicks on the 'upload' button, on the applet, or when the |
---|
| 33 | applet startUpload() method is called by javascript:</P> |
---|
| 34 | <DIR> |
---|
| 35 | <LI>The JUploadPanel.doStartUpload() starts the job |
---|
| 36 | <LI>It calls the <A HREF="../policies/UploadPolicy.html#beforeUpload()">UploadPolicy.beforeUpload()</A> method. If this method |
---|
| 37 | returns false, the process stops here. |
---|
| 38 | <LI>It then creates and starts the FileUploadManagerThread thread. This thread is responsible to throw all necessary |
---|
| 39 | actions to execute the upload |
---|
| 40 | <LI>The fileUploadManagerThread creates the necessary queues and threads (see below) |
---|
| 41 | <LI>It then waits for the upload to finish, by comparing the total number of files to upload to the number of uploaded |
---|
| 42 | files, after each successful upload. |
---|
| 43 | </DIR> |
---|
| 44 | |
---|
| 45 | <P>The upload is done by these threads:</P> |
---|
| 46 | <DIR> |
---|
| 47 | <LI><A HREF="FileUploadManagerThread.html">FileUploadManagerThread</A>: The main thread of the upload, does these actions: |
---|
| 48 | <DIR> |
---|
| 49 | <LI>creation and start the queues described below. |
---|
| 50 | <LI>creation and start the threads described below. |
---|
| 51 | <LI>waiting for the upload to be finished |
---|
| 52 | <LI>updating the upload progress bar |
---|
| 53 | <LI>maintain the end of upload flag (with the isUploadFinished() method) |
---|
| 54 | </DIR> |
---|
| 55 | <LI><A HREF="FilePreparationThread.html">FilePreparationThread</A>: This thread: |
---|
| 56 | <DIR> |
---|
| 57 | <LI>reads the list of files, from the FilePanel, |
---|
| 58 | <LI>prepares each file for upload, by calling the <A HREF="../filedata/FileData.html#beforeUpload()">FileData.beforeUpload()</A> method. |
---|
| 59 | <LI>manages exceptions that could occurs here. If one occurs, the user is asked if he want to go on with upload. |
---|
| 60 | <LI>put the prepared file on the <B>preparedFileQueue</B>, if everything is ok. |
---|
| 61 | <LI>put a <A HREF="UploadFileDataPoisonned.html">UploadFileDataPoisonned</A>, to tell the PacketPreparationThread |
---|
| 62 | that the last file was sent. |
---|
| 63 | <LI>contains the reference of the number of files to upload (as some files may be in error, while the upload goes on). |
---|
| 64 | </DIR> |
---|
| 65 | <LI><A href="PacketConstructionThread.html">PacketConstructionThread</A>: This thread is responsible for grouping the |
---|
| 66 | files in packet of files, that will be sent in one request to the server. It: |
---|
| 67 | <DIR> |
---|
| 68 | <LI>reads the files in the <B>preparedFileQueue</B> |
---|
| 69 | <LI>checks if it can be added to the current packet. |
---|
| 70 | <LI>put the packet in the <B>packetQueue</B> as soon as a packet is ready (or when the upload is finished) |
---|
| 71 | <LI>put a <A HREF="UploadFilePacketPoisonned.html">UploadFilePacketPoisonned</A>, to tell the FileUploadThread |
---|
| 72 | that the last packet was sent. |
---|
| 73 | <LI>adds the file to the current packet. |
---|
| 74 | </DIR> |
---|
| 75 | <LI><A HREF="FileUploadThread.html">FileUploadThread</A>: This interface is implemented by these classes: |
---|
| 76 | <A HREF="DefaultFileUploadThread.html">DefaultFileUploadThread</A> is an abstract |
---|
| 77 | class that contains all non protocol-specific code. The <A HREF="FileUploadThreadFTP.html">FileUploadThreadFTP</A> and |
---|
| 78 | <A HREF="FileUploadThreadHTTP.html">FileUploadThreadHTTP</A> class implements the protocol-specific treatements, mainly: |
---|
| 79 | build the request and read the server response. These classes do these actions: |
---|
| 80 | <DIR> |
---|
| 81 | <LI>Reads the next packet in the <B>packetQueue</B> |
---|
| 82 | <LI>Checks if the upload is in chunked mode or not. Chunk mode is activated when the packet size is bigger than the |
---|
| 83 | maxChunkSize applet. There must be only one file in the packet. |
---|
| 84 | <LI>Calls the <A HREF="DefaultFileUploadThread.html#beforeRequest(wjhk.jupload2.upload.UploadFilePacket)">DefaultFileUploadThread.beforeRequest(UploadFilePacket)</A> |
---|
| 85 | method, for any request preparation (server connection...) |
---|
| 86 | <LI>Calls the <A HREF="DefaultFileUploadThread.html#startRequest(long,%20boolean,%20int,%20boolean)">DefaultFileUploadThread.startRequest(long, boolean, int, boolean)</A> |
---|
| 87 | method, for headers that need to be sent before the first file. |
---|
| 88 | <LI>[Non chunked mode] Loops throught the files in the packet: |
---|
| 89 | <DIR> |
---|
| 90 | <LI>Calls the <A HREF="DefaultFileUploadThread.html#beforeFile(wjhk.jupload2.upload.UploadFilePacket, wjhk.jupload2.upload.UploadFileData)">beforeFile(UploadFilePacket, UploadFileData)</A> |
---|
| 91 | <LI>Calls the <A HREF="UploadFileData.html#uploadFile(java.io.OutputStream, long)">UploadFileData.uploadFile(OutputStream, long)</A> to send the bytes for the already prepared files to the server. |
---|
| 92 | <LI>Calls the <A HREF="DefaultFileUploadThread.html#afterFile(wjhk.jupload2.upload.UploadFileData)">afterFile(UploadFileData)</A> |
---|
| 93 | </DIR> |
---|
| 94 | <LI>[Chunked mode] Loops throught the chunks for the unique file in the packet: |
---|
| 95 | <DIR> |
---|
| 96 | <LI>Calls the <A HREF="DefaultFileUploadThread.html#beforeFile(wjhk.jupload2.upload.UploadFilePacket, wjhk.jupload2.upload.UploadFileData)">beforeFile(UploadFilePacket, UploadFileData)</A> |
---|
| 97 | <LI>Calls the <A HREF="UploadFileData.html#uploadFile(java.io.OutputStream, long)">UploadFileData.uploadFile(OutputStream, long)</A> to send the bytes for the current chunk of the already prepared |
---|
| 98 | files to the server. |
---|
| 99 | <LI>Calls the <A HREF="DefaultFileUploadThread.html#afterFile(wjhk.jupload2.upload.UploadFileData)">afterFile(UploadFileData)</A> |
---|
| 100 | </DIR> |
---|
| 101 | <LI>Calls the <A HREF="DefaultFileUploadThread.html#finishRequest()">finishRequest()</A> method, to clean any |
---|
| 102 | resources about this request. |
---|
| 103 | <LI>The <A HREF="../policies/UploadPolicy.html#checkUploadSuccess(int, java.lang.String, java.lang.String)">UploadPolicy.checkUploadSuccess(int, String, String)</A> |
---|
| 104 | is called after each request to the server, to check that the server response contains the relevant success string. |
---|
| 105 | It also checks if an error occurs (and then displays the message to the user). In this case, the |
---|
| 106 | <A HREF="FileUploadManagerThread.html#setUploadException(wjhk.jupload2.exception.JUploadException)">FileUploadManagerThread.setUploadException(JUploadException)</A> |
---|
| 107 | is called. This stops the upload. All threads will quit. |
---|
| 108 | <LI>Calls the <A HREF="DefaultFileUploadThread.html#cleanRequest()">cleanRequest()</A> method, to clean any resources |
---|
| 109 | used by this request. |
---|
| 110 | <LI>Calls the <A HREF="DefaultFileUploadThread.html#cleanAll()">cleanAll()</A> method when the upload is finished, |
---|
| 111 | to clean any global resource for the upload. |
---|
| 112 | </DIR> |
---|
| 113 | </DIR> |
---|
| 114 | |
---|
| 115 | <H3>The resume facility</H3> |
---|
| 116 | <P>When a network error occurs during upload, the applet can have some retries to the server. These retries can be automatic |
---|
| 117 | or manually controlled. When an retries occurs, the whole packet is resent. That is: the apply re-execute the request that failed.</P> |
---|
| 118 | |
---|
| 119 | |
---|
| 120 | Impacts: |
---|
| 121 | - The FileData.afterUpload() can only be called once the whole request is a success or a failure without retry. That is: the afterUpload |
---|
| 122 | is called after catching the exception, that may be resumed. |
---|
| 123 | --> The call to FileData.afterUpload() should be moved from doNonChunkedUpload() and doChunkedUpload() to doUpload, in a |
---|
| 124 | new finally block, in a finally block. |
---|
| 125 | |
---|
| 126 | </BODY> |
---|
| 127 | </HTML> |
---|