This utility provides a demonstration of how a combination of a Java Bean embedded in the Oracle 9iAS Forms Java Client and Java called from the Oracle 9iAS 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 as well as some utilities that will aid you in signing your own JAR files.
This distribution contains both the source code for the upload utility as well as a demo and compiled versions. When unzipped you will see the following directories:
Directory | Contains |
---|---|
.\src | The Java source files for the Java Bean, and the Server side Classes |
.\classes | The compiled classes for the UploadClient Java Bean that can
be used as a PJC in an Oracle Forms application. The compiled classed
for the Server side portion of the code. The Utility also includes three
JAR files in this directory:
|
.\doc | The JavaDoc generated documentation from the Java Bean and Server side Java source files. This documents the methods and attributes used within the code. |
.\misc | Contains files for creating a certificate to sign the UploadClient JAR file used to deploy the client side of the application. The JAR file signing utilities have been developed for use on a Windows operating system but should be easily ported to other operating systems. The digital certificate used to sign the JAR file (PJC.x509) is also stored in this directory. |
.\forms | Contains a PL/SQL library which contains the code required to incorporate the file upload utility into your modules. You will also find an example form demonstrating the use of the utility. |
This document covers the following tasks:
Installing and running the File Upload Demo
Reusing the File Upload Utility in your own Applications
Making changes to the File Upload Utility
This utility is designed to work only with Web deployed Oracle iAS Forms services 6i Release 2 and above. The utility can be used either with the Forms Listener, or the Forms Listener Servlet (Patch 4 and above). If using the Forms listener, then the various environment settings for CLASSPATH etc. will have to be set in the environment used by the listener as it starts. When using the listener servlet, then environment settings can be placed in the jserv.properties file or in a separate environment variables file if using Patch 5 or above.
In order to run the middle tier portion of the code you will need a version 1.2.2 JDK (or above) runtime available.
A sample environment file if using the Forms Listener Servlet with Patch 5 might look like:
#Environment file used to setup the FileUpload Demo
ORACLE_HOME=d:\oracle\dev6i
PATH=d:\oracle\dev6i\bin;d:\oracle\ias\Apache\jdk\jre\bin\classic
FORMS60_PATH=d:\FileUpload\forms
CLASSPATH=d:\oracle\dev6i\forms60\java\UploadServer.jar
javakey -c PJC true
javakey -ic PJC c:\temp\pjc.x509
[UploadDemo]
IE50=JInitiator
form=FileUpload
connectMode=http
archive_jini=f60all_jinit.jar,uploadclient.jar.sig
width=650
height=550
separateFrame=false
splashScreen=no
lookAndFeel=Oracle
colorScheme=Khaki
Using the Servlet:
http://<servername>/servlet/oracle.forms.servlet.FormsServlet?config=UploadDemo
Using the CGI:
http://<servername>/dev60cgi/ifcgi60?config=UploadDemo
If you use Static HTML files create a new file to run the Form FileUpload, with the ARCHIVE parameter including the uploadclient.jar.sig.
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. The certificate supplied with the packaged utility is provided for demonstration purposes and both the public and private keys are available as part of the distribution. This could allow malicious third parties to sign their own code with the same certificate and potentially execute it on any machine with the supplied demo PJC.x509 registered. Furthermore we would recommend that you removed the PJC identity from your identity database (using the command javakey -r PJC), once you have created and installed your own certificate. You can obtain a new certificate from a Certificate Authority or you can generate your own using the cert-maker.bat file supplied in the fileupload\misc directory
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\uploadclient and FileUpload\src\uploadserver respectively. In each of these directories you will find a batch file makepjc.bat which can be used to recompile and deploy the code. In the case of the UploadClient, it also creates a signed version of the JAR file automatically.
Makepjc generates the JavaDoc into the FileUpload\doc directory and the JAR and Class files into the FileUpload\classes directory. In each source directory(src) you will find a file called pjc.properties which drives the make process. This file should not be changed except in the case of signing the UploadClient.jar file, in which case you can change the SIGN_DIRECTIVE property to point to your signing directive file.
Makepjc can also deploy the JAR files to whatever directory is specified on the makepjc command line.
Before running the utility you will need to set two environment variables. The ORACLE_HOME directory contains your Forms installation and the JDK_HOME pointing to the home directory of the correct version of a Java development kit. UploadClient requires a 1.1.8 JDK for compilation. UploadServer requires a 1.2.2 JDK. Ensure that you set the JDK_HOME accordingly before running makepjc for either.
So as an example the commands to rebuild the UploadClient PJC and deploy to the d:\oracle\dev6i\forms60\Java directory would look like:
set ORACLE_HOME=d:\oracle\dev6i
set JDK_HOME=d:\tools\jdk1.1.8
makepjc d:\oracle\dev6i\forms60\Java
At the time of publication the FileUpload utility has the following restrictions:
When running the demo form (FileUpload) that is supplied with the utility, press Key-Listval (Control+L by default). This will pop up a dialog containing the current CLASSPATH. If this fails then this is because Forms cannot instanciate any Java code at all. Ensure that:
If you have ensured that your CLASSPATH is correct and you still get an error when running the demo form, then you should do a Recompile All on the supplied PLL and FMB file.