View Javadoc
1   //
2   // $Id: UploadPolicyFactory.java 629 2009-02-23 16:25:14Z etienne_sf $
3   //
4   // jupload - A file upload applet.
5   // Copyright 2007 The JUpload Team
6   //
7   // Created: 2009-05-11
8   // Creator: etienne_sf
9   // Last modified: $Date: 2009-02-23 17:25:14 +0100 (lun., 23 févr. 2009) $
10  //
11  // This program is free software; you can redistribute it and/or modify it under
12  // the terms of the GNU General Public License as published by the Free Software
13  // Foundation; either version 2 of the License, or (at your option) any later
14  // version. This program is distributed in the hope that it will be useful, but
15  // WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
16  // FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
17  // details. You should have received a copy of the GNU General Public License
18  // along with this program; if not, write to the Free Software Foundation, Inc.,
19  // 675 Mass Ave, Cambridge, MA 02139, USA.
20  
21  package wjhk.jupload2.context;
22  
23  import java.awt.Cursor;
24  import java.awt.Frame;
25  import java.util.Vector;
26  
27  import javax.swing.JApplet;
28  
29  import wjhk.jupload2.exception.JUploadException;
30  import wjhk.jupload2.gui.JUploadPanel;
31  import wjhk.jupload2.gui.JUploadTextArea;
32  import wjhk.jupload2.gui.filepanel.FilePanel;
33  import wjhk.jupload2.gui.filepanel.FilePanel.FileListViewMode;
34  import wjhk.jupload2.policies.DefaultUploadPolicy;
35  import wjhk.jupload2.policies.UploadPolicy;
36  import wjhk.jupload2.upload.helper.ByteArrayEncoderHTTP;
37  
38  /**
39   * This interface it used in upload policies to get information on the current Context. This context is responsible for:
40   * <DIR> <LI>Reading parameters from the environment or the applet parameters. <LI>Storing the current UploadPolicy (or
41   * null if not set yet) <LI> <LI></DIR>
42   * 
43   * @author etienne_sf
44   */
45  public interface JUploadContext {
46  
47      /*
48       * **************************************************************************
49       * **************** VERSION MANAGEMENT *************************************************************************
50       */
51  
52      /**
53       * @return The 'official' version (applet version and SVN revision)
54       */
55      public String getDetailedVersionMessage();
56  
57      /**
58       * @return The applet version
59       */
60      public String getVersion();
61  
62      /**
63       * @return The applet SVN revision, from which it was compiled
64       */
65      public String getSvnRevision();
66  
67      /**
68       * @return Last modification date (date of last commit)
69       */
70      public String getLastModified();
71  
72      /**
73       * @return Last modification date (date of last commit)
74       */
75      public String getBuildDate();
76  
77      /**
78       * @return Last modification date (date of last commit)
79       */
80      public int getBuildNumber();
81  
82      /*
83       * **************************************************************************
84       * **************** GUI MANAGEMENT *************************************************************************
85       */
86  
87      /**
88       * Displays a given URL, in the given target. The target is meant in html &lt;A&gt; tag, and may be ignored if not
89       * relevant.
90       * 
91       * @param url The URL to display, in text format. It will be normalized 'before use'.
92       * @param success Indicates whether the upload was a success or not.
93       */
94      public void displayURL(String url, boolean success);
95  
96      /**
97       * Retrieves the current applet. This call is still used by {@link ByteArrayEncoderHTTP}, to append form variable.
98       * It will be removed, in the future.
99       * 
100      * @return The current applet, or null if not running in an applet
101      */
102     public JApplet getApplet();
103 
104     /**
105      * Returns the current frame. Can be used to attach Dialog, for instance.
106      * 
107      * @return The current frame
108      */
109     public Frame getFrame();
110 
111     /**
112      * Retrieves the current log window of this applet. This log window may visible or not depending on various applet
113      * parameter.
114      * 
115      * @return the current log window of this instance.
116      * @see JUploadPanel#showOrHideLogWindow()
117      */
118     public JUploadTextArea getLogWindow();
119 
120     /**
121      * Returns the mime type associated with the given file extension. As the applet may run on windows, the
122      * fileExtension is always changed to minor case, before looking for the corresponding mime type.
123      * 
124      * @param fileExtension The file extension, in any case.
125      * @return Returns the current mime type, for this extension.
126      */
127 
128     public String getMimeType(String fileExtension);
129 
130     /**
131      * Retrieves the current upload panel.
132      * 
133      * @return the current upload panel of this instance.
134      */
135     public JUploadPanel getUploadPanel();
136 
137     /**
138      * This method the current UploadPolicy, associated with the current execution context. This UploadPolicy is set
139      * once, when the application start. It can not change afterwards.
140      * 
141      * @return The current UploadPolicy, or null of the uploadPolicy has not been set yet.
142      * @throws JUploadException
143      */
144     public UploadPolicy getUploadPolicy() throws JUploadException;
145 
146     /**
147      * @return The current cursor.
148      * @see UploadPolicy#setCursor(Cursor)
149      */
150     public Cursor getCursor();
151 
152     /**
153      * @param cursor The cursor to set
154      * @return The Cursor that was active, before setting the new one. It's up to the caller to remind it, to be able to
155      *         restore it if necessary.
156      * @see UploadPolicy#setCursor(Cursor)
157      */
158     public Cursor setCursor(Cursor cursor);
159 
160     /**
161      * Sets the wait cursor on the current application (applet, executable...).
162      * 
163      * @return The cursor that was active before the call to this method
164      * @see UploadPolicy#setCursor(Cursor)
165      */
166     public Cursor setWaitCursor();
167 
168     /**
169      * Displays a message in the status window.
170      * 
171      * @param status
172      */
173     public void showStatus(String status);
174 
175     /*
176      * **************************************************************************
177      * **************** PARAMETERS MANAGEMENT *************************************************************************
178      */
179 
180     /**
181      * Get a String parameter value from applet properties or System properties.
182      * 
183      * @param key The name of the parameter to fetch.
184      * @param def A default value which is used, when the specified parameter is not set.
185      * @return The value of the applet parameter (resp. system property). If the parameter was not specified or no such
186      *         system property exists, returns the given default value.
187      */
188     public String getParameter(String key, String def);
189 
190     /**
191      * Get a String parameter value from applet properties or System properties.
192      * 
193      * @param key The parameter name
194      * @param def The default value
195      * @return the parameter value, or the default, if the system is not set.
196      */
197     public int getParameter(String key, int def);
198 
199     /**
200      * Get a String parameter value from applet properties or System properties.
201      * 
202      * @param key The parameter name
203      * @param def The default value
204      * @return the parameter value, or the default, if the system is not set.
205      */
206     public float getParameter(String key, float def);
207 
208     /**
209      * Get a String parameter value from applet properties or System properties.
210      * 
211      * @param key The parameter name
212      * @param def The default value
213      * @return the parameter value, or the default, if the system is not set.
214      */
215     public long getParameter(String key, long def);
216 
217     /**
218      * Get a boolean parameter value from applet properties or System properties.
219      * 
220      * @param key The parameter name
221      * @param def The default value
222      * @return the parameter value, or the default, if the system is not set.
223      */
224     public boolean getParameter(String key, boolean def);
225 
226     /**
227      * Get a {@link FilePanel.FileListViewMode} parameter value from applet properties or System properties.
228      * 
229      * @param key The parameter name
230      * @param def The default value
231      * @return the parameter value, or the default, if the system is not set.
232      */
233     public FilePanel.FileListViewMode getParameter(String key, FilePanel.FileListViewMode def);
234 
235     /**
236      * This function try to parse value as an integer. If value is not a correct integer, def is returned.
237      * 
238      * @param value The string value, that must be parsed
239      * @param def The default value
240      * @return The integer value of value, or def if value is not valid.
241      */
242     public int parseInt(String value, int def);
243 
244     /**
245      * This function try to parse value as a float number. If value is not a correct float, def is returned.
246      * 
247      * @param value The string value, that must be parsed
248      * @param def The default value
249      * @return The float value of value, or def if value is not valid.
250      */
251     public float parseFloat(String value, float def);
252 
253     /**
254      * This function try to parse value as a Long. If value is not a correct long, def is returned.
255      * 
256      * @param value The string value, that must be parsed
257      * @param def The default value
258      * @return The integer value of value, or def if value is not valid.
259      */
260     public long parseLong(String value, long def);
261 
262     /**
263      * This function try to parse value as a boolean. If value is not a correct boolean, def is returned.
264      * 
265      * @param value The new value for this property. If invalid, the default value is used.
266      * @param def The default value: used if value is invalid.
267      * @return The boolean value of value, or def if value is not a valid boolean.
268      */
269     public boolean parseBoolean(String value, boolean def);
270 
271     /**
272      * This function try to parse value as a {@link FilePanel.FileListViewMode}. If value is not a correct
273      * {@link FilePanel.FileListViewMode}, a warning is logged, and def is returned.
274      * 
275      * @param value The new value for this property. If invalid, the default value is used.
276      * @param def The default value: used if value is invalid.
277      * @return The {@link FilePanel.FileListViewMode} value of value, or def if value is not a valid
278      *         {@link FilePanel.FileListViewMode}.
279      */
280     public FileListViewMode parseFileListViewMode(String value, FilePanel.FileListViewMode def);
281 
282     /*
283      * **************************************************************************
284      * **************** TECHNICAL MANAGEMENT *************************************************************************
285      */
286 
287     /**
288      * This method allows to read the navigator cookies. These items will be added as headers, in the given Vector.
289      * 
290      * @param headers The headers, coming from {@link DefaultUploadPolicy}
291      */
292     public void readCookieFromNavigator(Vector<String> headers);
293 
294     /**
295      * This method allows to read the navigator userAgent. It will be added as headers, in the given Vector.
296      * 
297      * @param headers The headers, coming from {@link DefaultUploadPolicy}
298      */
299     public void readUserAgentFromNavigator(Vector<String> headers);
300 
301     /**
302      * Generates a valid URL, from a String. The generation may add the documentBase of the applet.
303      * 
304      * @param url A url. Can be a path relative to the current one.
305      * @return The normalized URL
306      * @throws JUploadException
307      */
308     public String normalizeURL(String url) throws JUploadException;
309 
310     /**
311      * Register a callback to be executed during applet termination.
312      * 
313      * @param object The Object instance to be registered
314      * @param method The Method of that object to be registered. The method must be of type void and must not take any
315      *            parameters and must be public.
316      */
317     public void registerUnload(Object object, String method);
318 
319     /**
320      * Runs all callback that must be called when releasing the applet.
321      */
322     public void runUnload();
323 
324     /**
325      * This allow runtime modifications of properties, from javascript. Currently, this can only be used after full
326      * initialization. This method only calls the UploadPolicy.setProperty method. <BR>
327      * Ex: document.jupload.setProperty(prop, value);
328      * 
329      * @param prop The property name that must be set.
330      * @param value The value of this property.
331      */
332     public void setProperty(String prop, String value);
333 
334     /**
335      * Public method that can be called by Javascript to start upload
336      * 
337      * @return Returns the upload result. See the constants defined in the {@link JavascriptHandler} javadoc.
338      */
339     public String startUpload();
340 }