1 | |
---|
2 | <HTML> |
---|
3 | |
---|
4 | <BODY> |
---|
5 | |
---|
6 | <P>This package contains the upload policies: they give you hook entry points, to override the default applet behaviour |
---|
7 | with a minimum of java code.</P> |
---|
8 | |
---|
9 | This pages describes how to create a new upload policy, to adapt the applet to your needs, without interfering |
---|
10 | with the core applet, that is: with having compatibility with future JUpload versions. Here are other links on this subject: |
---|
11 | <DIR> |
---|
12 | <LI> See {@link wjhk.jupload2.policies.UploadPolicy} for the list of applet parameters</LI> |
---|
13 | <LI><a href="../../../howto-customization.html">howto customize</a> for a presentation of |
---|
14 | the main ways to adapt the applet to your needs. |
---|
15 | </DIR> |
---|
16 | |
---|
17 | |
---|
18 | <H3>Creating a new upload policy: introduction</H3> |
---|
19 | |
---|
20 | Creating a new upload policy, allows you to change the applet behaviour, and still use the core applet function. This |
---|
21 | insures you that your development will remain compatible with next applet versions. |
---|
22 | <P>You'll find on this page a description of the {@link wjhk.jupload2.policies.UploadPolicy} methods, grouped by categories.</P> |
---|
23 | <P><B>Note:</B> Creating a new upload policy is mandatory, if you want to manage some other kind of {@link wjhk.jupload2.filedata.FileData}. |
---|
24 | You can then add some kind of 'before upload check', or have a specific applet behaviour, for instance be able to hear |
---|
25 | sound file before upload.</P> |
---|
26 | |
---|
27 | <h3>Presentation</h3> |
---|
28 | |
---|
29 | <p>To create a new upload policy, you need to create a new java |
---|
30 | class: the easiest way is to inherit from @link wjhk.jupload2.policies.DefaultUploadPolicy}. |
---|
31 | You can then override methods of the UploadPolicy interface that you need to update for your needs.</p> |
---|
32 | <p>This kind of customization will be compatible within next JUpload |
---|
33 | applet release. If you need other hooks (method within the UploadPolicy |
---|
34 | interface, to allow other customizations), please let me know by posting a message |
---|
35 | on the sourceforge jupload forums (open discussions for instance), or |
---|
36 | post a new Feature Request in the jupload sourceforge project page. For instance, some attributes and methods from |
---|
37 | DefaultUploadPolicy are protected (not private), so that you can use them in your own upload policies.</p> |
---|
38 | <p>Here is a sample description of the customization that you can do by |
---|
39 | using the creating a new policy, using the UploadPolicy interface. All methods are described in |
---|
40 | the next section of this page.</p> |
---|
41 | <ul> |
---|
42 | <li>Control files management: |
---|
43 | <ul> |
---|
44 | <li>Authorization (or not) to add a file to the list of |
---|
45 | files to upload, see UploadPolicy#createFileData(File, File). This |
---|
46 | allows the policy to validate files, before adding them to the |
---|
47 | list of files that must be displayed. The |
---|
48 | {@link wjhk.jupload2.policies.UploadPolicy#createFileData(File, File)} checks that the added |
---|
49 | files are valid pictures.</li> |
---|
50 | <li>File preparation before upload (for instance to resize |
---|
51 | a picture, or encode a text file to a specific format)</li> |
---|
52 | </ul> |
---|
53 | </li> |
---|
54 | <li>Display other buttons on the applet (or remove the default |
---|
55 | buttons), see UploadPolicy.createTopPanel(JButton, JButton, JButton, |
---|
56 | JPanel)</li> |
---|
57 | <li>Specific behaviour, on file selection. The |
---|
58 | wjhk.jupload2.policies.PictureUploadPolicy allows picture |
---|
59 | management. The UploadPolicy.onSelectFile(FileData) method is called |
---|
60 | when the user selects a file in the list. This allow the policy to |
---|
61 | do any action about this file. The |
---|
62 | PictureUploadPolicy.onSelectFile(FileData) displays a preview |
---|
63 | pictures on the top part of the applet.</li> |
---|
64 | </ul> |
---|
65 | |
---|
66 | <h3>Note: UploadPolicyFactory</h3> |
---|
67 | |
---|
68 | <p>The JuploadApplet asks the UploadPolicyFactory to create |
---|
69 | (instanciate) the needed UploadPolicy. That is:</p> |
---|
70 | <dir> |
---|
71 | <li>During initialization of the applet, the |
---|
72 | UploadPolicyFactory.getUploadPolicy() method is called. This method |
---|
73 | checks the <i>uploadPolicy</i> parameter. If this uploadPolicy is |
---|
74 | unknown or not set, the DefaultUploadPolicy is used. If a specific |
---|
75 | uploadPolicy is found, it can of course read specific parameters |
---|
76 | from the APPLET tag.</li> |
---|
77 | <li>Then, UploadPolicyFactory.getUploadPolicy() creates the |
---|
78 | class implementing the UploadPolicy factory, and returns the |
---|
79 | reference to this class.</li> |
---|
80 | <li>The upload policy can not be changed while the applet is |
---|
81 | running.</li> |
---|
82 | </dir> |
---|
83 | |
---|
84 | <h3>Creation of a new UploadPolicy: detailed steps</h3> |
---|
85 | <p>To create a new UploadPolicy, you'll need to:</p> |
---|
86 | <ul> |
---|
87 | <li><b>Create a new class, implementing the UploadPolicy |
---|
88 | interface</b>. The easiest way is to inherit from an existing |
---|
89 | UploadPolicy. This insure that your new policy will be compatible |
---|
90 | with next JUpload releases. <br> |
---|
91 | <i>Note: The upload policies are created by UploadPolicyFactory. |
---|
92 | <U>Their constructor must:</U> |
---|
93 | <ul> |
---|
94 | <li>Be public, to be called by this class,</li> |
---|
95 | <li>Have one parameter: the current <a href="../context/JUploadContext.html">wjhk.jupload2.context.JUploadContext</a>.</li> |
---|
96 | </ul> |
---|
97 | </i></li> |
---|
98 | <li><b>Override some UploadPolicy methods</b>, to have your |
---|
99 | specific behaviour.</li> |
---|
100 | <li>Don't change any other java code, so that your upload |
---|
101 | policy will work with next JUpload releases. <br> |
---|
102 | <i>Note: if you need another 'hook', to be able to add specific |
---|
103 | customization, please add a new Feature Request in sourceforge, I'll receive a notification mail.</i></li> |
---|
104 | </ul> |
---|
105 | |
---|
106 | |
---|
107 | <H3>Methods to control file management</H3> |
---|
108 | |
---|
109 | <H4>FileData createFileData(File file, File root) throws JUploadExceptionStopAddingFiles</H4> |
---|
110 | <P>This methods creates a new {@link wjhk.jupload2.filedata.FileData} object. It returns null is no file data was created, for instance |
---|
111 | if this file didn't check some specific validation checks. <BR> |
---|
112 | <B>Note:</B> use this method to use any FileData specific to your needs. See {@link wjhk.jupload2.policies.PictureUploadPolicy} for a sample |
---|
113 | of this. |
---|
114 | </P> |
---|
115 | |
---|
116 | <H4>void afterFileDropped(DropTargetDropEvent dropEvent)</H4> |
---|
117 | <P>Specific reaction of the applet, when file are dropped onto it.</P> |
---|
118 | |
---|
119 | |
---|
120 | <H3>Methods to control the applet GUI (display, behaviour)</H3> |
---|
121 | |
---|
122 | This methods are used to control what the {@link wjhk.jupload2.gui.JUploadFileChooser} has to do. |
---|
123 | |
---|
124 | <H4>JPanel createTopPanel(JButton browse, JButton remove, JButton removeAll, JUploadPanel mainPanel)</H4> |
---|
125 | <P>Allows the applet to change the way the top part of the applet is displayed, that is: the place where the |
---|
126 | Choose, remove, remove all buttons are. <B>If you override this method, you must use the given button if you want |
---|
127 | these functionalities to work</B>. If you don't put the browse button, for instance, the user won't be able to |
---|
128 | display a file chooser, unless you manage it yourself. See {@link wjhk.jupload2.policies.PictureUploadPolicy}, for a way to use the |
---|
129 | standard buttons, and add specific ones.</P> |
---|
130 | |
---|
131 | |
---|
132 | <H4>void addComponentsToJUploadPanel(JUploadPanel jUploadPanel)</H4> |
---|
133 | <P>Extension of the createTopPanel() idea. You can place any component of JUpload at any place ... or at no place. |
---|
134 | <B>If you override this method, you'll have to call the {@link wjhk.jupload2.gui.JUploadPanel} getter to get core applet objects.</B> |
---|
135 | These are: |
---|
136 | <DIR> |
---|
137 | <LI>Standard buttons: browseButton, removeButton, removeAllButton, stopButton, uploadButton. |
---|
138 | <LI>Drag'n drop listener: dndListener, to manage files dropped on the applet |
---|
139 | <LI>The log output: jLogWindowPane |
---|
140 | <LI>The progress bar, which indicated the upload progress (from 0 to 100%): progressBar. |
---|
141 | <LI>The status label, where upload speed is indicated: |
---|
142 | <LI>The file panel, that contains the list of files to upload: filePanel. |
---|
143 | </DIR> |
---|
144 | </P> |
---|
145 | |
---|
146 | <H4>JPanel createProgressPanel(JProgressBar progressBar, JButton uploadButton, JButton stopButton, JPanel mainPanel)</H4> |
---|
147 | <P>You probably won't have to override this method. Note that this method allows you to not |
---|
148 | display the stop and upload buttons. </P> |
---|
149 | |
---|
150 | <H4>JPanel createStatusBar(JLabel statusContent, JPanel mainPanel)</H4> |
---|
151 | <P>This method should not be used any more. Use the showStatusBar applet parameter instead.</P> |
---|
152 | |
---|
153 | <H4>void onFileSelected(FileData fileData)</H4> |
---|
154 | <P>Reaction of the applet, when a file is selected in the file list. For instance, {@link wjhk.jupload2.policies.PictureUploadPolicy} |
---|
155 | displays the selected picture in the preview component.</P> |
---|
156 | |
---|
157 | <H4>void onFileDoubleClicked(FileData fileData)</H4> |
---|
158 | <P>Reaction of the applet, when a file is double clicked. For instance, {@link wjhk.jupload2.policies.PictureUploadPolicy} opens a dialog |
---|
159 | box, that contain a full screen display of the current picture. </P> |
---|
160 | |
---|
161 | |
---|
162 | <H3>Methods to control the file chooser</H3> |
---|
163 | |
---|
164 | This methods are used to control what the {@link wjhk.jupload2.gui.JUploadFileChooser} has to do. |
---|
165 | |
---|
166 | <H4>JUploadFileChooser createFileChooser()</H4> |
---|
167 | <P>Allows the applet to change user another JFileChooser. Your specific file chooser should inherit |
---|
168 | from JUploadFileChooser</P> |
---|
169 | |
---|
170 | <H4>boolean fileFilterAccept(File file)</H4> |
---|
171 | <P>Called by the {@link wjhk.jupload2.gui.JUploadFileFilter}. This method contains the actual response to the { |
---|
172 | @link java.io.FileFilter#accept(File)} method of the FileFilter interface. It allows to control what can be displayed |
---|
173 | on the file chooser.</P> |
---|
174 | |
---|
175 | <H4>String fileFilterGetDescription()</H4> |
---|
176 | <P>The file filter description, in the file chooser. The default is to display the list of authorized |
---|
177 | extensions. This can be too large, if many extensions are authorized. You can then put here a more descriptive text.</P> |
---|
178 | |
---|
179 | <H4>Icon fileViewGetIcon(File file)</H4> |
---|
180 | <P>Returns the icon that must be displayed for this file on the file chooser. This method is called asynchroneously, |
---|
181 | so that long calculation won't block the applet. See an example in the {@link wjhk.jupload2.policies.PictureUploadPolicy}. This policy |
---|
182 | returns an icon created from the picture content.</P> |
---|
183 | |
---|
184 | |
---|
185 | <H3>Upload management</H3> |
---|
186 | |
---|
187 | <H4>boolean isUploadReady()</H4> |
---|
188 | <P>Allows a control of the current upload policy, before any upload work starts. <B>You'll probably have to override |
---|
189 | this method if you want to do pre-upload checks on files</B></P> |
---|
190 | |
---|
191 | <H4>void beforeUpload()</H4> |
---|
192 | <P>This method is called just before upload, for instance to allow any 'before upload' work, like computing |
---|
193 | some global information. See also the FileData.beforeUpload(), that is called for each file.</P> |
---|
194 | |
---|
195 | <H4>boolean checkUploadSuccess(int status, String msg, String body) throws JUploadException</H4> |
---|
196 | <P>You probably won't have to override this method, if you use the stringUploadSuccess and stringUploadError |
---|
197 | applet parameters. If not, this method allows you to check that upload is a success. That is: there is no |
---|
198 | error (for instance, page not found), and the server side application actually accepted the file(s).</P> |
---|
199 | |
---|
200 | <H4>void afterUpload(Exception e, String serverOutput) throws JUploadException</H4> |
---|
201 | <P>Allows the caller to free any resource used during upload. See also the FileData.afterUpload(), that is called |
---|
202 | for each file.</P> |
---|
203 | |
---|
204 | <H4>String getLastResponseBody()</H4> |
---|
205 | <P>This method is useful only in HTTP upload (not FTP, for instance). It allows any check or update of applet |
---|
206 | variables based on the server return. You probably should not have to override this method.</P> |
---|
207 | |
---|
208 | <H4>String getLastResponseMessage()</H4> |
---|
209 | <P>This method is useful only in HTTP upload (not FTP, for instance). It returns the full HTTP response, with headers. |
---|
210 | It allows any check or update of applet variables based on the server return. You probably should not have to override |
---|
211 | this method.</P> |
---|
212 | |
---|
213 | <H4>void addHeader(String header)</H4> |
---|
214 | <P>Add a header to the list of all header that must be added to all upload. Useful only when uploading in HTTP mode. |
---|
215 | If you override this method, you'll have to override the onAppendHeader(ByteArrayEncoder) method.</P> |
---|
216 | |
---|
217 | <H4>ByteArrayEncoder onAppendHeader(ByteArrayEncoder sb) throws JUploadIOException</H4> |
---|
218 | <P>Add header on the HTTP request, while this requet is being written to the server. <B>If you override this |
---|
219 | method, you'll have to call super.onAppendHeader(ByteArrayEncoder) method</B>.</P> |
---|
220 | |
---|
221 | <H4>String getSpecificHeaders()</H4> |
---|
222 | <P>Allows the upload policy to add specific headers. This is used only for HTTP upload.</P> |
---|
223 | |
---|
224 | <H4>String getFormdata()</H4> |
---|
225 | <P>Load data from an HTML form. These data will be set with each file in the upload. See also the |
---|
226 | {@link wjhk.jupload2.filedata.FileData#appendFileProperties(ByteArrayEncoder)} method, for a way to add data specific to one file.</P> |
---|
227 | |
---|
228 | |
---|
229 | <H3>Getters and setters</H3> |
---|
230 | |
---|
231 | <P>The last category of methods is the getters and setters. There is a getter for each applet parameter. Most of applet parameters |
---|
232 | also has a setter. You can override them to add some execution time calculation. For instance, {@link Coppermine#getPostURL()} |
---|
233 | calls the default getter, than the album id as a new parameter on the URL.</P> |
---|
234 | <P>Here are the other getters:</P> |
---|
235 | |
---|
236 | <H4>void setProperty(String prop, String value) throws JUploadException</H4> |
---|
237 | <P>Allows to set any property. This can be called for any applet parameter. <B>This method can be called from |
---|
238 | Javascript</B>, to allow runtime control of applet state by the javascript.</P> |
---|
239 | |
---|
240 | <H4>JUploadApplet getApplet()</H4> |
---|
241 | <P>This important getter returns the JUploadApplet. From it, you can get any GUI component.</P> |
---|
242 | |
---|
243 | <H4>String getDateFormat()</H4> |
---|
244 | <P>Returns the current date format, so that all date/time are displayed by using the same format.</P> |
---|
245 | |
---|
246 | <H4>int getSslVerifyCert()</H4> |
---|
247 | <P>For SSL management. Standard code should be good enough.</P> |
---|
248 | |
---|
249 | |
---|
250 | <H3>Message display (debug, info, warning, error...)</H3> |
---|
251 | |
---|
252 | <H4>void displayParameterStatus()</H4> |
---|
253 | <P><B>You should override</B> this method, to display any parameter specific to your upload policy. See |
---|
254 | {@link wjhk.jupload2.policies.PictureUploadPolicy} for a sample.</P> |
---|
255 | |
---|
256 | <H4>void alert(String key)</H4> |
---|
257 | <P>You probably won't have to override this method. Displays an alert box, based on the key of the translated message.</P> |
---|
258 | |
---|
259 | <H4>void alertStr(String str)</H4> |
---|
260 | <P>You probably won't have to override this method. Displays an alert box.</P> |
---|
261 | |
---|
262 | <H4>void displayInfo(String info)</H4> |
---|
263 | <P>You probably won't have to override this method.. Will be renamed, as it just logged an info message.</P> |
---|
264 | |
---|
265 | <H4>void displayWarn(String warn)</H4> |
---|
266 | <P>You probably won't have to override this method. Will be renamed, as it just logs a warning.</P> |
---|
267 | |
---|
268 | <H4>void displayDebug(String debug, int minDebugLevel)</H4> |
---|
269 | <P>You probably won't have to override this method.. Will be renamed, as it just logs a debug message.</P> |
---|
270 | |
---|
271 | <H4>void displayErr(String err, Exception e)</H4> |
---|
272 | <P>You probably won't have to override this method. Will be renamed.</P> |
---|
273 | |
---|
274 | <H4>void displayErr(Exception e)</H4> |
---|
275 | <P>You probably won't have to override this method. Will be renamed.</P> |
---|
276 | |
---|
277 | <H4>void displayErr(String err)</H4> |
---|
278 | <P>You probably won't have to override this method. Will be renamed.</P> |
---|
279 | |
---|
280 | <H4>String getString(String key)</H4> |
---|
281 | <P>You probably won't have to override this method. Manages text translation.</P> |
---|
282 | |
---|
283 | |
---|
284 | <H3>Miscellaneous methods </H3> |
---|
285 | |
---|
286 | <H4>Cursor setWaitCursor()</H4> |
---|
287 | <P>You can change the applet wait cursor, by overriding this method.</P> |
---|
288 | |
---|
289 | <H4>void setCursor(Cursor cursor)</H4> |
---|
290 | <P>I don't think you'll have to override this one...</P> |
---|
291 | |
---|
292 | <H4>void sendDebugInformation(String reason)</H4> |
---|
293 | <P>send the debug output to the urlToSendErrorTo applet parameter. Allows logging on the server ... if this calls |
---|
294 | succeed, which is not the case when the server has a big trouble.</P> |
---|
295 | |
---|
296 | |
---|
297 | </BODY> |
---|
298 | </HTML> |
---|