source: 3thparty/jupload/target/classes/wjhk/jupload2/policies/package.html @ 3951

Revision 3951, 15.0 KB checked in by alexandrecorreia, 13 years ago (diff)

Ticket #1709 - Adicao de codigo fonte java do componente jupload
Line 
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
7with a minimum of java code.</P>
8
9This pages describes how to create a new upload policy, to adapt the applet to your needs, without interfering
10with 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
14the main ways to adapt the applet to your needs.
15</DIR>
16
17
18<H3>Creating a new upload policy: introduction</H3>
19
20Creating a new upload policy, allows you to change the applet behaviour, and still use the core applet function. This
21insures 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}.
24You can then add some kind of 'before upload check', or have a specific applet behaviour, for instance be able to hear
25sound 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
30class: the easiest way is to inherit from @link wjhk.jupload2.policies.DefaultUploadPolicy}.
31You 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
33applet release. If you need other hooks (method within the UploadPolicy
34interface, to allow other customizations), please let me know by posting a message
35on the sourceforge jupload forums (open discussions for instance), or
36post a new Feature Request in the jupload sourceforge project page. For instance, some attributes and methods from
37DefaultUploadPolicy 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
39using the creating a new policy, using the UploadPolicy interface. All methods are described in
40the 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
111if 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
113of 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
122This 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
126Choose, remove, remove all buttons are. <B>If you override this method, you must use the given button if you want
127these functionalities to work</B>. If you don't put the browse button, for instance, the user won't be able to
128display a file chooser, unless you manage it yourself. See {@link wjhk.jupload2.policies.PictureUploadPolicy}, for a way to use the
129standard 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> 
135These 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
148display 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}
155displays 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
159box, that contain a full screen display of the current picture. </P>
160
161
162<H3>Methods to control the file chooser</H3>
163
164This 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
168from 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
173on 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
177extensions. 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,
181so that long calculation won't block the applet. See an example in the {@link wjhk.jupload2.policies.PictureUploadPolicy}. This policy
182returns 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
189this 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
193some 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
197applet parameters. If not, this method allows you to check that upload is a success. That is: there is no
198error (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
202for 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
206variables 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.
210It allows any check or update of applet variables based on the server return. You probably should not have to override
211this 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.
215If 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
219method, 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
232also has a setter. You can override them to add some execution time calculation. For instance, {@link Coppermine#getPostURL()}
233calls 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
238Javascript</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
294succeed, which is not the case when the server has a big trouble.</P>
295
296
297</BODY>
298</HTML>
Note: See TracBrowser for help on using the repository browser.