|
ROB Configuration Guide 2nd Edition October 2004 |
The following are prerequisites for installing Repository Object Browser (ROB):
If you want to enable file uploads to the repository using ROB, see the additional prerequisites at Configuring File Upload.
The files required by ROB will be installed automatically during Oracle Designer installation, and the database objects required for ROB will be installed automatically during the repository installation.
The following additional manual configuration steps are covered by this guide:
When the database installation of ROB has been completed, a webserver must be configured to provide access to ROB PL/SQL procedures using any browser on your network. Also the files in the <ORACLE_HOME>\rob61\gif directories created by the Oracle Universal Installer need to be available on this webserver's file system. ROB has been tested with Oracle Application Server and WebDB. Please note that if you want to use the "File Upload" feature of ROB, which allows you to upload files from client machines to the repository from within your browser, you will also need a Java servlet webserver (see Configuring File Upload).
Configuring a PL/SQL webserver for ROB requires three steps: copying the required files to the webserver, defining directory mappings ("virtual directories" or "aliases") to give access to the ROB image files, and defining a DAD (Database Access Descriptor) that will provide access to the ROB stored PL/SQL packages.
If your webserver is on a different file system than the one you installed the ROB files on, you will have to ensure that all files in the <ORACLE_HOME>\rob61\gif directory are available on the webserver's file system. Create a ROB gif directory on the webserver and ensure that the user running the webserver has read access to it. Then copy all files of the gif folder from your client PC to the webserver's file system. If the webserver is a Unix system, it is probably convenient to use an FTP tool for this.
A directory mapping is what a webserver needs to translate a 'virtual directory', i.e. a directory label that can be used in a URL, to a physical directory that is accessible to the computer that the webserver is running on. ROB needs the following directory mapping:
Virtual Directory: /rob_images/
Physical Directory: <ORACLE_HOME>\rob\gif\
The value for virtual directory entered in the web server configuration must match the value of the ROB preference "Virtual Directory path for ROB Images". The default value of this preference is "/rob_images/".
If your webserver is running on a different file system than the one you installed Designer on, map the virtual directory /rob_images/ to the new folders that you created in the previous step. If the webserver is on the same file system as the original installation, you can use the <ORACLE_HOME>\rob61\gif directories created by the Oracle Installer.
Each webserver has its own method of specifying directory mappings. The steps needed for creating these directory mappings for both Oracle Application Server and WebDB are listed below.
With Oracle Application Server you have to define the virtual directory mappings (= aliases) in Apache. You need to edit the file httpd.conf, which can generally be found in the following directory: <IAS_HOME>\Apache\Apache\conf. Open the file in a text editor, and append the lines that are displayed bold in the example below :
.. .. # # Aliases: Add here as many aliases as you need (with no limit). The format is # Alias fakename realname # # Note that if you include a trailing / on fakename then the server will # require it to be present in the URL. So "/icons" isn't aliased in this # example, only "/icons/".. # Alias /icons/ "D:\oraias9i\Apache\Apache\icons/" Alias /jservdocs/ "D:\oraias9i\Apache\Jserv\docs/" # Unix example: Alias /rob_images/ "/u01/app/rob/gif/" # NT example: Alias /rob_images/ "c:\orant\rob61\gif/" Alias /rob_images/ "<ROB gif directory>/" .. ..
Note that although it doesn't matter where you put the two lines in the file, it might be wise to group all "Alias" statements together, as the above example shows.
After you have saved these changes, you will need to restart the Apache webserver for these new settings to take effect.
WebDB has a set of management pages you can access through a browser, that will allow you to configure it. These pages can normally be found by typing in the following URL:
http://<your_server>/admin_/gateway.htm
From here, perform the following steps:
Before continuing, you might verify that the virtual directories are set up correctly by entering the following URL in your browser: http://<your_server:your port>/rob_images/rob_splash.gif
The majority of the HTML pages of ROB are so called "dynamic documents". This means they are not stored in files on the filesystem, but are created 'on the fly' by PL/SQL code in your database. To be able to call this code from your browser, the webserver needs to be able to obtain the following information from the URL you provide in the browser:
The connectstring of the user as which it should log in to the database.
The name of the stored procedure it should invoke.
Providing the entire connect string in the URL could obviously create a security gap. Therefore, an intermediate object called a "Database Access Descriptor", or "DAD" is created in the configuration of the webserver that can translate URLs that follow a specific formatting convention to a connectstring and a stored procedure to execute. Such a URL could look like this:
http://<your_server:your port>/pls/rob/cdwp.startup
We can divide this URL into the following parts:
The string "/pls/" indicates that this URL is not addressing a file, but a stored PL/SQL procedure. The exact string is dependent on the webserver that is being used (in this example: IAS).
The string "/rob/" is the name of a DAD, that has been entered in the configuration of the webserver. From this DAD name, the webserver will retrieve the connect string from its configuration, and use it to connect to a database.
Finally, the string "/cdwp.startup", that would ordinarily indicate a filename, now stands for a stored PL/SQL object. In this case, the procedure "startup" in the package "cdwp" will be executed, and its output will be redirected back to the browser that submitted the URL.
It is not mandatory to store username and password in a DAD. When they are not supplied, the web server will display a logon dialog when an end user launches the application.
You can have two types of access to ROB:
DAD type 1 - ROB users log in with their own repository user. In this case you need to create a DAD without any Oracle username/password. You only need to create one DAD of this type, which can then be used for any repository user.
DAD type 2 - ROB users are automatically logged in with a special purpose repository user. In this case you need to specify the username/password of this special purpose repository user in the DAD. You will need a separate DAD for every special purpose repository user.
You can have both a DAD of type 1, and one or more DADs of type 2.
Each webserver has its own method of specifying database access descriptors. The steps needed for creating these DADs for both Oracle Application Server and WebDB are listed below.
Oracle Application Server has a set of management pages you can access through a browser, that will allow you to configure it. These pages can normally be found by typing in the following URL:
http://<your_server>/
From here, perform the following steps:
Database Access Descriptor Name: (for example) rob
Oracle User Name: leave this empty (DAD type 1) or specify repository username (DAD type 2)
Oracle Password: leave this empty (DAD type 1) or specify password (DAD type 2)
Oracle Connect string: <your_database>
Authentication Mode: Basic
Create a stateful session: No
Enable Connection Pooling: Yes
Default (Home) Page: cdwp.startup
If you have completed these steps, you should be able to launch ROB by supplying the following URL to your browser:
http://<your_server:your_port>/<DAD name>/cdwp.startup
WebDB has a set of management pages you can access through a browser, that will allow you to configure it. These pages can normally be found by typing in the following URL:
http://<your_server>/admin_/gateway.htm
From here, the steps you need to perform depend slightly on the version of WebDB you are using. Copy the fields of an existing DAD, except for the following fields:
name: choose a DAD name, for example rob
username/password: either leave them empty (DAD type 1) or specify a special (read only) repository username/password (DAD type 2)
default page: cdwp.startup
If you have completed registering the DAD, you should be able to launch ROB by supplying the following URL to your browser:
http://<your_server:your_port>/<DAD name>/cdwp.startup
By default, ROB file upload is disabled. To configure it, you need to follow the additional steps described in this section.
You need to have installed a WebServer with support for Java Servlets. For example Apache JServ, which is available as part of Oracle Application Server. You can also download either Apache JServ or Tomcat JavaServer from http://www.apache.org/. The Java RunTimeEngine must be at least version 1.2, since it needs to support JDBC 2.0. Note that this Java Servlet support is completely independent of the support for PL/SQL stored procedure calls. You could have the PL/SQL calls interpreted by WebDB, while the Java Servlets are handled by Apache JServ.
You need to have Oracle's JDBC classes, specifically the file classes12.zip. You get this file with JDeveloper 3.1 or 3.2, or you can download it from the Oracle Technology Network website (from where you choose Software in the left hand navigation bar, and in the poplist 'Select a Utility or Driver', you choose Oracle JDBC Drivers). Note that you need to have the version for Oracle 8.1.6 or higher.
You need to have a directory available (with write privileges) at the file system of the WebServer for temporary storage of uploaded files.
You need to have a database account at the repository database (username, password and connectstring valid for connecting to the database from the webserver's file system). This database account needs to have UPDATE privileges on the I$SDD_FILES repository table and EXECUTE privilege on the ROBowner's CDWP_FIL package and will be used for uploading all files, even when the uploads are requested by other repository users. Note that the user also needs to be able to access these database objects through synonyms (for e.g., repos owner).
When you satisfy these requirements, you are able to configure File Upload. You have to perform some installation steps on the Java servlet webserver, and tell ROB that file upload can be enabled.
Create a directory on the webserver to hold the files from the <ORACLE_HOME>\rob61\lib directory, or, if you performed the ROB client installation on the webserver itself, you can use the existing <ORACLE_HOME>\rob61\lib folder. You can choose any directory, these are just examples.
Unix example: /u01/app/ROB/lib
NT example: c:\orant\rob\lib
The files that are uploaded in ROB to the repository are stored in an intermediate holding stage on the webserver's file system. You must create this directory, make it read/write accessible to the webserver and specify it in the rob.properties file (see one of the next steps).
Unix example: /u01/app/rob/upload
NT example: c:\orant\rob\upload
If you created a new servlet library on the webserver, copy the servlet library rob.jar, the rob.properties file and the rob_zone.properties file from the <ORACLE_HOME>\rob61\lib folder to the Servlet directory you had prepared on the webserver. If you have to copy the files to Unix, an FTP tool is probably useful. Note that these files must be accessible to the user account that runs the webserver (the user that starts the webserver software). If you use the existing <ORACLE_HOME>\rob61\lib folder, you already have these files there.
The rob.properties file is used by the servlets to connect to the repository. You will have to edit this file to correspond with your own repository and file system environment. Do not mistake this file with the rob_zone.properties file. That file is part of the JServ zone configuration and is not used by the servlets themselves.
The following parameters must be set to match your environment:
# Database Connect details for a Repository User account that will be used for uploading and downloading # files. This user needs UPDATE privileges on the table I$SDD_FILES and execute privilege on package CDWP_FIL; # the user also needs synonyms for these two objects drivers=oracle.jdbc.driver.OracleDriver default.url=jdbc:oracle:thin:@<database machine's IP address>:<Database TNS Port>:<database connect alias> default.loglevel=error default.user=<username> default.password=<password> default.initconns=1 default.maxconns=30 # logfile for connection pooling mechanism (note: on NT double backslashes are needed) # Unix example: logfile=/u01/app/rob/upload/robConnections.log # NT example: logfile=c:\\orant\\rob\\upload\\robConnections.log logfile=<Connection Pooling Logfile> # directory into which files will be downloaded from the repository before being served to the browser # or uploaded by the webserver from browser before being uploaded into the repository # Note that ROB will delete files after sending to the browser. # Unix example: downloadDirectory=/u01/app/rob/upload # NT example: downloadDirectory=c:\\orant\\rob\\upload downloadDirectory=<upload/download directory> # full path+filename for the log files that will record details and problems of the most recent file upload # and download operations. Note that currently these paths must exist and be writable by the user under # which the JServ process runs. # Unix example: uploadlogfile=/u01/app/rob/upload/robUploadLog.txt # NT example: uploadlogfile=c:\\orant\\rob\\upload\\robUploadLog.txt uploadlogfile=<upload logfile, folder path + file name> downloadLogfile=<download logfile, folder path + file name>
If you are using OC4J server (or Oracle Application Server release 2 or above), proceed to Configuring OC4J.
The shipped rob_zone.properties file should be edited to reflect the proper directories where the libraries (rob.jar) are stored. Also, be careful to include in the repositories parameter the directory that contains the rob.properties file:
# The list of servlet repositories controlled by this servlet zone # Syntax: repositories=[repository],[repository]... # Default: NONE # Note: The classes you want to be reloaded upon modification should be put # here. # Unix example: repositories=/u01/app/rob/lib/rob.jar,/u01/app/rob/lib # NT example: repositories=c:\orant\rob\lib\rob.jar,c:\orant\rob\lib repositories=<path of rob.jar,path of Servlet Directory>
This description assumes you have Apache JServ. In the jserv.conf file, one or more ApJServMount points can be defined for each of the Servlet Zones supported by this instance of the JServ. Add an entry that looks like this:
#Servlet Zone for rob production release (note the space before each slash) ApJServMount /rob /rob
In the case of IAS 1.0.2.2 (or above) and when the following line is present in the jserv.conf.file
ApJServManual auto
The following line should be added to the conf file ApJServGroupMount /rob balance://group1/rob
This description assumes you have Apache JServ. In the jserv.properties file, the servlet zones are listed together with their zone-properties file. Add the zone rob to the list of zones:
# List of servlet zones Apache JServ manages # Syntax: zones=[servlet zone],[servlet zone]... (Comma separated list of String) # Default: NONE zones=root,rob
Now add a reference to the rob_zone.properties file (note this depends on the file system that holds your JServ instance):
# Configuration file for each servlet zone (one per servlet zone) # Syntax: [servlet zone name as on the zones list].properties=[full path to configFile] (String) # Default: NONE # Note: if the file could not be opened, try using absolute paths. root.properties=/u01/app/oracle/product/ias1.0.2/Apache/Jserv/etc/zone.properties # Unix example: rob.properties=/u01/app/rob/lib/rob_zone.properties # NT example: rob.properties=c:\orant\rob\lib\rob_zone.properties rob.properties=<path of rob_zone.properties>
This description assumes you have Apache JServ. In the jserv.properties file, find where the CLASSPATH environment value is passed to the JVM. For each directory in the path, a line starting with wrapper.classpath= will be present. If not already there, add a line for classes12.zip:
# CLASSPATH environment value passed to the JVM # Syntax: wrapper.classpath=[path] (String) # Default: NONE (Sun's JDK/JRE already have a default classpath) # Note: if more than one line is supplied these will be concatenated using # ":" or ";" (depending whether Unix or Win32) characters. JVM must be # able to find JSDK and JServ classes and any utility classes used by # your servlets. # Note: the classes you want to be automatically reloaded upon modification # MUST NOT be in this classpath or the classpath of the shell # you start the Apache from. # wrapper.classpath=/u01/app/oracle/product/ias1.0.2/Apache/Jserv/libexec/ApacheJServ.jar wrapper.classpath=/u01/app/oracle/product/ias1.0.2/Apache/Jsdk/lib/jsdk.jar # Unix example: wrapper.classpath=/u01/app/oracle/product/ias1.0.2/Apache/bc4j_jdev32/classes12.zip # NT example: wrapper.classpath=c:\oracle\JDev32\jdbc\lib\oracle8.1.7\classes12.zip wrapper.classpath=<path of classes12.zip>
To have the webserver notice the new servlet zone and respond adequately to requests for this zone, it needs to be reinitialized by restarting.
A first and very simple test of the successful configuration of the new servlet zone and the properties-files can be performed by trying to execute a test servlet:
http://<host:port>/rob/TestROBServlets
Here host is your hostname and port is the port number of the webserver (default port number is 80). The zone is called rob. The servlet alias is TestROBServlets whose associated servlet is packaged in the file rob.jar.
The result of this call should be a simple page with the text: "Repository Object Browser - Servlets. Congratulations, the ROB Servlets can be accessed. Apparently both installation and configuration are OK!"
The ROB servlets are packaged into an Enterprise archive file (rob.ear). This file, located in <ORACLE_HOME>\rob61\lib, needs to be deployed to the OC4J server so that the servlets are hosted in it. Follow the steps below to deploy the ROB enterprise archive to OC4J.
java -jar admin.jar ormi://<host>:<port> <username> <password> -deploy -file <path to rob.ear> -deploymentName robapp
Where the host, port are the Host name and OC4J's RMI port number (default = 23791) in which OC4J is running . A typical command would look like the following:
java -jar admin.jar ormi://localhost admin manager -deploy -file d:\orant\rob61\rob.ear -deploymentName robapp
Note: The port number can be omitted if the RMI server is running in its default port.
The OC4J server would deploy the EAR file by expanding the archive file into the <OC4J_HOME>\application-deployments folder.
The rob.properties file can be found under the folder "<OC4J_HOME>\applications\rob\rob\WEB-INF\classes".
In order to reference the ROB servlets through URL, the application has to be assigned to a virtual-path through the admin utility.
java -jar admin.jar ormi://localhost admin manager -bindWebApp <App-Name> <webapp-Name> <web-site> <virtual-path>
A typical command would look like the following:
java -jar admin.jar ormi://localhost admin manager -bindWebApp robapp rob default-web-site /rob
A very simple test of the successful deployment of the application can be performed by trying to execute a test servlet from a web browser:
http://<host:port>/rob/servlet/TestROBServlets
Here "host" is your host name, "port" is the port number of the webserver (default port number is 80) and the application virtual path is rob. TestROBServlets is the alias to a test servlet whose associated servlet is packaged in the file rob.jar.
The result of this call should be a simple page with the text:
"Repository Object Browser - Servlets. Congratulations, the ROB Servlets can be accessed. Apparently both installation and configuration are OK!".
The final step now that the servlets are installed, configured and seem to be executable, is to make all of this known to Repository Object Browser. By default, ROB assumes servlets are not enabled and therefore File Upload is not a supported operation. If however you have followed the steps in this document and you have enabled the servlets and the File Upload functionality, you need to update the value of two ROB preferences.
From the startup page go to the Management Facility tool, then to Manage ROB preferences page. Enable the checkbox against the preference "Enable File upload / download Servlets?", this will make the servlets available to the ROB. Now type in the value for the preference "Complete URL base to the File Upload / Download Servlets", the value is the base part of the URL (host, port and ServletZone) to access the ROB Servlets (e.g., http://localhost/rob/servlet/ - the '/' at the end must be provided).
In order to enable File Upload/Download, the preference "Enable File upload / download Servlets?" should be enabled and the preference "Complete URL base to the File Upload / Download Servlets" should have a non-null value.
Note: After a DAD has been configured in Oracle Application Server (versions from 9.0.2 onwards) it can be accessed through a URL like http://<Host name>:<Port>/<DAD_NAME>. This URL is different to that of Application Server version 1.0.2 in that it doesn't include "/pls/" as a prefix to the DAD name. Hence in the case of Application Server from version 9.0.2 onwards a conflict can occur between the DAD URL and the servlet binding URL. To avoid this, make sure that the DAD and the servlet URL binding have different values.
<ias_home>\j2ee\home\application\<application_name>\rob\WEB-INF\classes
|
|
|
|
