This utility provides a demonstration of how a combination of a Java Bean embedded in the Oracle Forms Java Client and Java called from the Oracle Forms Services on the middle tier can be used to transfer files from the browser client machine, onto the middle tier machine. The utility consists of three parts:
The Java Bean portion must reside in a signed JAR file at deployment time since it performs an operation that is outside of the Java sandbox for non trusted code. This distribution ships with a signed version of the JAR file.
The FileUpload demo consists of the following files (relative directories shown in brackets):
The doc directory and the classes directory contain the JavaDoc for the code and the compiled classes respectively
In order for an application to be able to reuse the Fileupload code provided, some changes need to be made to the environment that Forms Services on the middle tier is running with. The easy way to do this is to create a custom environment file which you can then reference from the relevant configuration in the formsweb.cfg file.
This environment file should make sure that the CLASSPATH used by Forms Services includes the uploadserver.jar file. For example:
#fileupload.env
#Environment file used to setup the FileUpload Demo
ORACLE_HOME=c:\oracle\DevSuiteHome
PATH=c:\oracle\DevSuiteHome\jdk\jre\bin\classic;c:\oracle\DevSuiteHome\bin
CLASSPATH=c:\oracle\DevSuiteHome\\forms\\demos\jars\uploadserver.jar;c:\oracle\DevSuiteHome\jdk\jre\lib\rt.jar
FORMS_path=c:\oracle\DevSuiteHome\\forms\\demos\lib;c:\oracle\DevSuiteHome\\forms\\demos\fileupload\forms
An entry in the formsweb.cfg file to call the FileUplaod demo might look like this, note the addition of the custom env file fileupload.env:
[FileUpload]
pageTitle=OracleAS Forms Services - FileUpload Sample
IE=jinitiator
baseHTMLJInitiator=demobasejini.html
archive_jini=frmall_jinit.jar,/formsdemo/jars/uploadclient.jar
width=675
height=480
separateFrame=false
splashScreen=no
lookAndFeel=oracle
colorScheme=blue
form=fileuploaderforms/java
background=/formsdemo/images/blue.gif
envFile=fileupload.env
Reusing the FileUpload utility within your own applications requires the following steps.
begin
FileUploader.eventHandler(:system.custom_item_event,get_parameter_list(:system.custom_item_event_parameters));
end;
/*----------------------------------------------------*
* Sample Callback trigger for FileUploader
* You should always implement a check on the status
* to make sure that the upload has worked.
*
* This trigger will only be executed once the upload
* has finished or aborted
*---------------------------------------------------*/
Begin
if FileUploader.getStatus = FileUploader.FINISHED then
message(FileUploader.getSourceFile || 'was uploaded');
elsif FileUploader.getStatus = FileUploader.FAILED then
message('Upload Failed because: '||FileUploader.getError);
end if;
end;
FileUploader.init('UPLOAD.FILE_UPLOAD_BEAN','FILEUPLOADER_CALLBACK');
FileUploader.UploadFile('d:\temp\uploaded');
Warning: If you intend to use the FileUpload utility in your own applications, We recommend that you re-sign the UploadClient PJC with your own x509 certificate.
All of the code required for the FileUpload facility is exposed through the FileUploader package in the FileUpload.pll library. The FileUpload PLL also contains several other packages which provide interfaces to the Java classes used by the utility. These are called via FileUpload and should not be called directly.
Function | Purpose |
---|---|
Init (BeanName in VARCHAR2, CallbackTrigger in VARCHAR2) |
Defines the settings for the upload utility This must be called before upload can be used.
|
UploadFile (DestinationDirectory in VARCHAR2, DestinationFilename in VARCHAR2, SourceDirectory in VARCHAR2); |
Displays a file dialog on the client, allows the user to select a file and uploads that file to the middle tier.
|
UploadNamedFile (FileName in VARCHAR2, DestinationDirectory in VARCHAR2, DestinationFilename in VARCHAR2) |
Directly uploads a named file from the client without displaying a file selection dialog.
|
GetStatus return PLS_INTEGER |
Returns the current status of the upload as one of the following constants:
GetStatus is mainly called from the Callback trigger which will be executed after a successful and a failed upload |
GetError return VARCHAR2 | Returns the text of the last error returned by the FileUpload. The result of this function is useful after GetStatus returns FileUploader.Failed or after the exception FileUploaderEx is raised. |
EventHandler (EventName in VARCHAR2, EventData in PARAMLIST); |
Handles all of the messages (events) from the bean. Should be called from the WHEN-CUSTOM-ITEM-EVENT trigger attached to the Bean Area.
|
Exception | Purpose |
---|---|
FileUploaderEx |
Exception raised when an unexpected error occurs in the FileUpload process. When this exception is raised you should check the value of FileUploader.getError; |
The following functions are used to control various aspects of FileUpload functionality.
Function | Purpose |
---|---|
GetSourceFile return VARCHAR2 |
Returns the name of the last file to be uploaded. Note: this is the name of the file on the client. The upload process may have renamed the file when saving on the server if that was requested. |
GetSourceDir return VARCHAR2 |
Returns the name of the directory that the last file was uploaded from. |
GetSourceLen return PLS_INTEGER |
Returns the size in bytes of the last file that was uploaded. |
SetCompressed (CompressionOn in BOOLEAN) |
Takes a boolean value to switch compression on or off. When compression is switched on, the FileUpload utility will automatically compress the file before uploading it. The file will be decompressed as it is written to the server. Compressing the file in this way can vastly reduce the amount of time required for upload and is switched on by default. However, with certain file types such as files which are already compressed (.ZIP, .CAB files etc.) compression will actually slow down the overall upload process. To evaluate the effectiveness of the compression, switch Debug mode on (see below) and you will see the effect of compression on the number of bytes being uploaded. |
SetDebug (DebugOn in BOOLEAN) |
Takes a boolean value to switch Debug mode on. When Debug mode is on, various informational messages will be written to the Java console as the upload process progresses. |
SetDialogPos (X_Pos in PLS_INTEGER,Y_Pos in PLS_INTEGER) | Allows you to control the position of the file selection dialog in Pixels. (See Known Restrictions) |
The FileUpload utility is provided with full source code and JavaDoc. The source code for the client and server parts of the code can be found in FileUpload\src. If you do change the code you must remember to re-sign the uploadclient jar file with your own certificate.
At the time of publication the FileUpload utility has the following restrictions: