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> |
---|