Oracle8i Java Virtual Machine, EJB/CORBA and Oracle Servlet Engine README Release 8.1.7 Table of Contents 1. Oracle's Enterprise Java Server Platform -- JServer 1.1 Documentation 1.2 Getting Started 1.3 Configuration 1.4 Java Compatibility 1.5 Compatibility Mode 2. CORBA and Enterprise JavaBeans 3. Known Problems 3.1 Memory Usage 3.2 Accessibility of Server-Resident Java Source 3.3 DESCRIBE Problems with Java 3.4 Loadjava and Dropjava 3.5 Error Reporting 3.6 java.version, oracle.jserver.version, and oracle.server.version 3.7 Java && in SQL*PLUS 3.9 RMI and Sockets 3.10 Bug #895586 -- Multibyte Character Output Truncation at 255 Bytes 3.11 Java Calling SQL and Vice Versa 3.12 Java and PL/SQL 3.13 EJB/CORBA -- Setting your CLASSPATH, LD_LIBRARY_PATH and PATH 3.14 SSL setup for CORBA and EJB 3.15 CORBA and EJB Examples 3.16 EJB Limitations 3.17 CORBA Limitations 3.18 SSL Limitations 3.19 EJB Differences with 8.1.6 3.20 Upgrading from 8.1.5 or 8.1.6 to 8.1.7 3.21 Patches included with 8.1.7 4. Oracle Servlet Engine 4.1 Introduction 4.2 General OSE Management 4.3 Troubleshooting 4.3.1 If a 404 is encountered 4.3.2 Problems In General 4.4 File Permissions and Servlet Context Ownership 5. Apache Module for OSE (mod_ose) 5.1 Introduction 5.2 Configuration Issues 5.3 mod_ose and SSL 5.4 Know Issues 6. Natively Compiled Java Code 6.1 Upgrade, Downgrade, Import, Export 6.2 Security 6.3 Acceptable C Compiler Versions 6.4 Known issues 1. Oracle's Enterprise Java Server Platform -- JServer Release 8.1.7 includes a fully functional Java virtual machine (VM), as well as the Java class libraries for Sun's Java Development Kit (JDK) 1.2.1. When combined with Oracle's JDBC, SQLJ, Enterprise JavaBeans (EJB), Aurora/ORB, Oracle Servlet Engine and Native Compilation implementations, this release provides an enterprise class platform, JServer, for developing and deploying server-based Java applications. 1.1 Documentation Separate hardcopy and on-line documentation are provided for the major Java-related components of this release. - Oracle8i Java Developer's Guide - Oracle8i Java Tools Reference - Oracle Java Server Pages Developer's Guide and Reference - Oracle8i Enterprise JavaBean Developer's Guide and Reference - Oracle8i CORBA Developer's Guide and Reference - Oracle8i Oracle Servlet Engine User's Guide - Oracle8i JDBC Developer's Guide and Reference - Oracle8i SQLJ Developer's Guide and Reference - Oracle8i JPublisher User's Guide - Oracle8i Java Stored Procedures Developer's Guide Always refer to http://www.oracle.com/java for the most up-to-date information on Oracle Java products, including documentation and known problems. The Oracle8i Java Developer's Guide provides an overview of all Java products and is an excellent starting point for exploring the Java capabilities of Oracle8i. In addition, it contains Oracle-specific details of Java that span the individual products: JDBC, SQLJ, and EJB/CORBA. Please refer to these documents and their respective README files for detailed information on each area. Information on JVM, CORBA, EJB, OSE and NComp information is covered in this README file. Note that Java Server Pages have a separate README that can be found at $ORACLE_HOME/jsp/doc/releasenotes_11000 1.2 Getting Started We recommend that you follow the examples presented in the Oracle8i Java Developer's Guide to begin. The demonstrations and examples in ORACLE_HOME/javavm/demo.tar (or demo.zip) include a HelloWorld example. Execution of this and other examples will ensure that your installation was complete and that JServer is properly enabled in your database. 1.3 Configuration The Java Developer's Guide provides details of installing and configuring a Java-enabled database. Also, refer to the discussion in Known Problems, Section 3.1, Memory Usage. The primary init.ora parameters that can affect Java usage and performance are shared_pool_size and java_pool_size. The memory specified in shared_pool_size is consumed transiently during use of loadjava. The database initialization process (i.e., executing initjvm.sql against a clean database, as opposed to the installed seed database) requires shared_pool_size to be set to 50MB as it loads the Java binaries for approximately 8000 classes and resolves them. Shared_pool resource is also consumed as call-specifications are defined, and as dynamically loaded Java classes are tracked at runtime. All other Java state during runtime execution of Java is taken from the amount allocated using java_pool_size. This memory includes the shared in-memory representation of Java method and class definitions, as well as the Java objects that are migrated to session space at end-of-call. In the former case, the memory cost is shared among all users. In the latter case, in MTS mode, you will need to adjust java_pool_size allocations based on the actual amount of state held in static variables for each session. As in Sun's JDK, the Java compiler (i.e., the compiler, written in Java, that compiles Java source code to Java binaries) is known to be a voracious consumer of memory. If you intend to compile significant amounts of Java source on the JServer, or you will be deploying complex EJB's (which use the Compiler on the server), you should consider increasing java_pool_size. The default value for java_pool_size is 20MB. NOTE: The seed database is configured to use dedicated server for Net8 clients and MTS for CORBA/EJB. MTS is required for CORBA/EJB (i.e., IIOP connections) but is not needed for Net8 clients. See the Net8 Administrator's Guide for more details on installation and configuration. 1.4 Java Compatibility This release has been thoroughly tested with Sun's Java Compatibility Kit for the JDK 1.2.1. As discussed in the Java Developer's Guide, the only platform-specific exception to compatibility applies to materialization of user interfaces. It is not appropriate for Java developers to be able to display user interface componentry within the Oracle server. User interfaces by definition imply the presence of a user to interact with Oracle on the server. Since no such user is, in general, present while Oracle is executing, it would be inappropriate to allow arbitrary user code to bring up a user interface which might require a response. Remember, this restriction does not prevent you from writing Java code that references or uses AWT or Swing classes, as long as you do not execute code on the server that attempts to materialize a user interface. Oracle is committed to JServer keeping pace with Java and other Internet standards. 1.5 Compatibility Mode To use Java in the Oracle8i server, you must set compatibility = 8.1.0 or higher. 2. CORBA and Enterprise JavaBeans Oracle8i Release 8.1.7 provides an integrated ORB and support for Enterprise JavaBeans (EJB). Please see the hardcopy or online documentation for in-depth information about deploying CORBA or EJB objects in 8.1.7. Oracle8i Release 8.1.7 integrates a development and a runtime version of Visibroker for Java, in order to provide support for building and deploying CORBA servers objects through Oracle tools. Oracle does not support stand alone CORBA objects development and deployment using Visibroker for Java, outside Oracle tools and products; Customers should get a valid Visibroker licence from Inprise. 3. Known Problems The following known problems encompass the VM itself, Java Stored Procedures, and the utilities used by most Java developers, loadjava and dropjava. Known problems with EJB and CORBA are also covered. Java interaction with SQL, particularly known problems with support for SQL-Java type translations, are discussed in the JDBC README. 3.1 Memory Usage Java introduces a significant development-time vs. runtime memory usage difference that is not reflected in the installation-time configuration assistance that is provided. Specifically, the installed configuration is limited to minimum, typical, and custom installs, but there is no means in this release of querying at install time to determine how you anticipate using Java. During development of JServer applications, you will be using tools such as loadjava, which consume memory in different ways than a runtime Java application. These tools are development-time only tools and do not enter into the world of runtime applications. As discussed in the Java Developer's Guide, you may choose a style of development using a client-side IDE, or you may choose to use the Java compiler on the JServer. The Compiler, which is adapted from Sun's JDK compiler, is very memory-intensive, and may require you to increase java_pool_size from the installed configuration value. The following rules of thumb apply: - You will need more java_pool_size if you are compiling code on the server than if you are compiling on the client and loading to the server. EJB deployment uses the Java compiler on the server, and therefore requires java_pool_size to be large. - You will need more shared_pool_size to handle loading large numbers of classes to the server and resolving them. - Under MTS, you will need to increase java_pool_size based on both the number of sessions and the amount of memory held in Java static variables at end-of-call. - Your runtime memory requirements at runtime will most likely be different than those required for Java development. If you are doing Java development, we recommend the following settings: shared_pool_size = 50000000 java_pool_size = 20000000 These are the default installation values for the Oracle8i JServer custom install. If you are deploying a Java application, the memory requirements will be dependent on the application itself and the number of users executing it concurrently. 3.1.1 Insufficient Memory or Resources During initjvm.sql Execution If initjvm.sql executed properly, the total count of Java schema objects should be greater than 8,000, as shown by: connect internal select count (*) from user_objects where object_type='JAVA CLASS'; All classes should be marked VALID, so the number of invalid classes should be zero, as shown by: select count(*) from user_objects where object_type='JAVA CLASS' and status != 'VALID'; If initjvm failed you should check your init.ora file to ensure that the shared_pool_size and java_pool_size are at least 50MB and 20MB respectively. These values may be set incorrectly if you chose the minimal or typical installation, which assumes you are starting with a Java-enabled database. 3.1.2 Insufficient Memory During Compilation If during use of the Compiler under loadjava, or during deployejb, you have insufficient memory, you should see an error: A SQL exception occurred while compiling: : ORA-04031: unable to allocate bytes of shared memory ("shared pool","unknown object","joxlod: init h", "JOX: ioc_allocate_pal") The cure is to shut down your database and to reset java_pool_size to a larger value. The mention of "shared pool" in the error message is misleading. Reset java_pool_size, not shared_pool_size. 3.1.3 Insufficient Memory During Java Class Loading When shared_pool_size is too low to handle the creation of class schema objects, the operation may fail silently, leaving invalid classes in the database. During subsequent runtime execution, the system will attempt to resolve any classes that are not VALID. If it is unsuccessful, you may see a ClassNotFoundException or a NoClassDefFoundException at runtime. Note that these are valid runtime exceptions that can occur because you failed to install a class on the server. They do not necessarily indicate there was any problem with shared_pool_size during loading. You should always verify that the class was included in the set you are loading to the server, and you should consider using the -force option of loadjava to force the class you're loading to replace the server-resident one. Use the -resolve options of loadjava to request that loadjava attempt resolution of a class when it is loaded. Normally loadjava will print error messages when resolution fails. If these messages indicate a memory problem or failures such as "connection lost", you can increase the size of shared_pool_size and java_pool_size and try again. To double check the status of a class that you have created with loadjava, you can connect to the database in the schema containing the class and do: select * from user_objects where object_name = dbms_java.shortname('') ; Among the columns of user_objects is a status. 3.2 Accessibility of Server-Resident Java Source In previous JServer releases, server-resident Java source was not accessible by the standard means used for PL/SQL. In release 8.1.7, if you create Java source schema objects, you can view the source using user_source. Specifically: select distinct type from user_source; now shows Java source. Note, however, that Java's binary standard allows you to compile Java code on the client and only load binary to the server. This is the approach recommended for Java development with JServer. 3.3 DESCRIBE Problems with Java DESCRIBE of package.procedure gives "object does not exist" when the method has a Java rather than PL/SQL implementation. DESCRIBE of package lists only PL/SQL procedures and excludes the Java Stored Procedures. 3.4 Loadjava and Dropjava Loadjava and Dropjava are java-based utilities you run on the client-side to load java binaries, source, or jar files to the server, and to drop the corresponding libunits. They are documented in the hardcopy as well as the online documentation (e.g., the Oracle8i Java Developer's Guide). 3.4.1 We recommend that you not load source and binaries together in a jar file. You cannot load source (.java) and binary (.class) files for the same class in the same jar file. 3.4.2 An important aspect of Java is its support for a binary standard. The Java binary standard allows you to do client-side development and only load the Java binaries to the server. You may find that use of a client-side compiler and loadjava to load the resulting binaries provides better performance than use of loadjava with source. 3.4.4 It would be desirable to allow dropjava to drop a package, but no such capability exists. 3.4.5 Loading large jar files may require additional shared_pool. The creation of java schema objects consumes memory specified in shared_pool_size. If you experience a problem loading large jar files, consider increasing the value of SHARED_POOL_SIZE as a workaround. If you feel that there is a problem with loadjava having not properly loaded and resolved a class, you can examine the state of loaded classes by connecting as the user who loaded the class (e.g., scott/tiger) and executing: select * from user_objects; Properly loaded and resolved classes should show up with status of VALID. A shorthand alternative to determine if any classes are not VALID is: select dbms_java.longname(object_name) from user_objects where object_type = 'JAVA CLASS' and status != 'VALID'; 3.5 Error Reporting Errors are often reported in a trace file. Please examine the trace file as your first step in isolating problems. 3.6 java.version, oracle.jserver.version, and oracle.server.version In release 8.1.7, we return "1.2.1" for java.version property, to correspond to the JDK default. If you have been using the presence of "Oracle" in java.version to determine whether your code is running on JServer as opposed to the client, then you should switch to testing whether the oracle.jserver.version property is non-null. (In release 8.1.5, the value of java.version was "Oracle Server 1.1.6". In release 8.1.6, the value of java.version was "1.2.1"). The property oracle.server.version is now deprecated. It was set in 8.1.5, and it is also set in 8.1.6 for compatibility reasons only. 3.7 Java && in SQL*PLUS SQL*PLUS interprets Java && as substitution variables. The workaround is to use loadjava to load source or to use loadjava to load binaries. If you want to write Java source in SQL*Plus, you can "set define off" first. 3.9 RMI and Sockets Please refer to the Java Developer's Guide for information on O/S Resources, Sockets, and RMI support in this release. RMI is fully supported, but you need to understand the implications of its use on your ability to build scalable server applications. Socket support beyond end-of-call is discussed in the Java Developer's Guide. 3.10 Bug #895586 -- Multibyte Character Output Truncation at 255 Bytes If you use dbms_java.set_output to redirect System.out.println() to standard output, and the 255th byte is part of a multibyte character, this character will be broken into 2 one byte characters in the output. The workaround is to break your output into smaller pieces. 3.11 Java Calling SQL and Vice Versa Please refer to the JDBC README for details on limitations in "SQL Call-in". There are known problems with usage of some data types and their translation between Java and SQL. In general, these are not JDBC problems, but are the responsibility of the Aurora runtime machinery. We have chosen to document the problems in the JDBC README (ORACLE_HOME\jdbc\readme.txt) because JDBC users are the most likely to encounter the problems. 3.12 Java and PL/SQL Refer to the "Java Stored Procedures" documentation for details of PL/SQL and Java interaction. It is a known feature of call-spec definition that there is no checking at definition time between the method signature provided in the call-spec and the method which will be invoked at runtime. The design is such that mismatches are only detected at runtime. 3.13 EJB/CORBA -- Setting your CLASSPATH, LD_LIBRARY_PATH and PATH To run the idl2java compiler or to deploy EJBs you need to have the commands "java" and "javac" from the JDK in your PATH. You can use JDK 1.1.3 and higher. Java2 (JDK 1.2.x) is supported but not required. PATH -> jdk1.1.x/bin or PATH -> jdk1.2.x/bin To be able to compile and run CORBA Objects or EJBs you need to have the following three jars in your CLASSPATH: CLASSPATH -> ORACLE_HOME/lib/aurora_client.jar ORACLE_HOME/lib/vbjapp.jar ORACLE_HOME/lib/vbjorb.jar If you use the JDK 1.1.x you also have to have the following. CLASSPATH -> jdk1.1.x/lib/classes.zip If you want to access CORBA Objects or EJBs over an SSL connection you need to configure your database for GIOP SSL as documented in the Net8 documentation. You also need to have the following jar in your CLASSPATH and, on Solaris, you need to have ORACLE_HOME/lib in your LD_LIBRARY_PATH. JDK 1.1.x CLASSPATH -> ORACLE_HOME/jlib/javax-ssl_1.1.jar:ORACLE_HOME/jlib/jssl-1_1.jar JDK 1.2.x CLASSPATH -> ORACLE_HOME/jlib/javax-ssl_1.2.jar:ORACLE_HOME/jlib/jssl-1_2.jar For either case, you need to have $ORACLE_HOME/lib in your LD_LIBRARY_PATH: LD_LIBRARY_PATH -> ORACLE_HOME/lib If your server objects are using classes in the oracle.aurora.rdbms package, such as DbmsJava, you need to add the following zip to your CLASSPATH to be able to compile them on the client side: CLASSPATH -> ORACLE_HOME/javavm/lib/aurora.zip Note that this material (setting CLASSPATH, etc.) is also covered in the individual readme's for the EJB and CORBA example programs. 3.14 SSL setup for CORBA and EJB If you want to connect to JServer with IIOP over SSL you have to configure your database for SSL as described in the documentation. Here is a summary of what needs to be done: 1. In init.ora uncomment the line that says: mts_dispatchers = "(PROTOCOL=TCPS)(PRE=oracle.aurora.server.SGiopServer)" 2. Add the following line in $TNS_ADMIN/listener.ora: (LISTENER = (DESCRIPTION_LIST= ... (DESCRIPTION = (ADDRESS= (PROTOCOL=tcps) (HOST=) (PORT=2482) ) (PRESENTATION=GIOP) ) ... )) # For client side Authentication, uncomment the below line #SSL_CLIENT_AUTHENTICATION= TRUE # For client side Authentication, comment the below line SSL_CLIENT_AUTHENTICATION=FALSE oss.source.my_wallet= (SOURCE=(METHOD=FILE)(METHOD_DATA= (DIRECTORY=))) 3. Add the following lines in $TNS_ADMIN/sqlnet.ora: # For client side Authentication, uncomment the below line #SSL_CLIENT_AUTHENTICATION= TRUE # For client side Authentication, comment the below line SSL_CLIENT_AUTHENTICATION=FALSE oss.source.my_wallet= (SOURCE=(METHOD=FILE)(METHOD_DATA= (DIRECTORY=))) Once you have made these changes, you will need to restart your database and listener. 3.15 CORBA and EJB Examples We provide numerous examples showing how to use CORBA and EJB in Oracle 8i. The examples are in the tar file ORACLE_HOME/javavm/demo/demo.tar. The examples are categorized by the technology being demonstrated (for example, CORBA or EJB). Within each of these directories, the samples are divided by usage (basic usage, session management, transaction management, RMI over IIOP, and so on). There are also some larger and more complex demos, which showcase these technologies in use. In each case, there is a README file provided which explains the objective of the sample, as well as a Makefile to compile, load and run it. Before running these examples, you need to have the JDK commands for java, javac in your PATH as decribed above in 3.13. You also need to have ORACLE_HOME, CLASSPATH, JAVA_HOME, LD_LIBRARY_PATH set correctly. Lastly, you should check the values for java_pool_size and shared_poll_size, in the init.ora file. These should be at least 50mb. There are known problems, or extra steps, required when using the following examples. All the other samples should work, without any modifications, as described in their individual readme. corba/basic/pureCorba ===================== For this example to work, you must configure your database to listen for Giop. You have to configure a dispatcher with "PRE=oracle.aurora.server.GiopServer" instead of "PRE=oracle.aurora.server.SGiopServer" and restart your database. corba/transaction ejb/transaction ================= JTA examples now require that you bind a JTA transaction manager, and/or JTA DataSource into the namespace. Therefore the makefile requires that you pass in more than one variable. Please check with the README files for more details. corba/transaction/jta/twophase ejb/transaction/jta/twophase ============================== Many JTA 2 phase commit examples require you to set up DBLinks and pass in more than one variables for the makefile to run. Please read the REAEDME files carefully before trying the JTA 2 phase commit examples. ejb/ssl/* corba/ssl/* =========== These examples require SSL setup as described in 3.15. 3.16 EJB Limitations 3.16.1 Our entity bean implementation currently does not support returning Collection for finder methods. The work around is to use Enumeration. You can use the following piece of code to convert collections to enumerations to be returned by the finder methods. import java.util.Collection; import java.util.Enumeration; import java.util.Iterator; public class CollectionEnumeration implements Enumeration { Collection coll; Iterator it; public CollectionEnumeration (Collection coll) { this.it = coll.iterator(); } public boolean hasMoreElements() { return it.hasNext (); } public Object nextElement() { return it.next (); } public Collection getCollection () { return coll; } } 3.16.2 Currently you can only deploy one bean at a time although the xml deployment descriptor allows you to specify for more than one bean. If you have a deployment descriptor that contains several beans, you will need to break it up into several xml deployment descriptor files, each containing information on one bean only. 3.16.3 During deployejb for deploying a Container Managed Persistence bean, if you get the following error: An exception occurred during code generation: null Check to make sure that the specified in the Oracle specific deployment descriptor corresponds to the in the standard deployment descriptor. 3.16.4 #1334001 If you specify a role for the access control list in the ejb deployment descriptor, and grant that role to a user. The user still doesn't have access to the bean. 3.16.5 #1379854 Trying to save an EJB handle and reuse it later does not work. 3.16.6 #1378775 In the XML deployment descriptor, you must specify a default transaction attribute for your bean. no description /test/purchase * Required 3.16.7 If a client continues to use an EJBObject after invoking its "remove" method the exception CORBA.OBJECT_NOT_FOUND is raised instead of the specified javax.ejb.ObjectNotFoundException. 3.16.8 deployejb will wrongly refuse to deploy a bean that does not have an ejbCreate method with no arguments. Just put a no-arguments ejbCreate in your EJBs: the method will only be called if you also have a no-arguments "create" method in your Home interface. public class myBean extends SessionBean { ... void ejbCreate(){} } 3.16.9 You can call an EJB from a Java Store Procedure or a Servlet in the same session by doing: InitialContext ic = new InitialContext(); HelloHome = (HelloHome)ic.lookup("/test/helloworld"); ..... However, this usage is only limited to calling session Beans that do not implement sessionSynchronization(bug 1390678). For calling entity beans from a java store procedure or from a servlet, you need to create an initial context and do a lookup like you do from a client. This will create a second database session for running the EJB. You cannot do RMI/IIOP callbacks to the session running the stored procedure or the servlet because pure SQL or http sessions cannot also be accessed through CORBA or RMI/IIOP. 3.16.10 You cannot deploy an EJB whose Home interface, Remote interface and Bean Implementation class are not in a package. This is bug number 951186. Always put your bean interfaces and classes in a package. 3.16.11 #1268913 deployejb fails if you include java.awt.color.ColorSpace in the remote interface. 3.17 CORBA Limitations 3.17.1 The SSL IIOP listener and dispatchers are not configured in the seed database. You have to configure SSL yourself as described in the Net8 Administrator's Guide. 3.17.2 Server applications can call ORB.init() with or without parameters and will always get a new instance of the ORB. This is usually not what you want. If you need to access the ORB instance created by JServer you should use the method "oracle.aurora.jndi.orb_dep.Orb.init()" that will always return the singleton ORB instance. This interface will also take care of appropriately installing any application interceptors. 3.17.3 If your database is configured to use a "shared" passwd file and the SYS password in the database is not the same as the SYS password in the password file you won't be able to connect as SYS through CORBA or SQLPLUS. Use the ALTER USER.. command to make the passwords match again. 3.17.4 If you configured your database for regular IIOP instead of Session IIOP you have to put the following property in the InitialContext of the CORBA or EJB clients. import oracle.aurora.jndi.sess_iiop.ServiceCtx; ... env.put("TRANSPORT_TYPE", ServiceCtx.IIOP); In addition, you have to configure a dispatcher with "PRE=oracle.aurora.server.GiopServer" instead of "PRE=oracle.aurora.server.SGiopServer" and use the corresponding in your sess_iiop URL. Note that all the tools we provide (publish, deployejb, sess_sh) support the "-iiop" option that make them use pure IIOP. Pass this argument if you want to connect to a dispatcher setup with PRE=oracle.aurora.server.GiopServer. 3.17.5 Note bug #1359098, in session lookup of /etc/IFR doesn't work. 3.18 SSL Limitations 3.18.1 Using SSL client side authentication when making an SSL callout from one server into another server is not supported in this release. 3.18.2 In this release, "SSL_CREDENTIAL" login is not supported. For example, the code: env.put (Context.SECURITY_AUTHENTICATION, ServiceCtx.SSL_CREDENTIAL) does not work and should be replaced with: env.put (Context.SECURITY_AUTHENTICATION, ServiceCtx.SSL_LOGIN) 3.19 EJB Differences with 8.1.6 We now support EJB 1.1 in Oracle 8i Release 8.1.7. You can use XML deployment descriptor instead of the text version for 8.1.6. We also have support for entity beans, both Bean Managed Persistence, and Container Managed Persistence. The CMP out of box uses a Persistence Service Interface Reference Implementation for its persistence solution. It is a very simple persistence layer that maps a bean into a table and has many restrictions. For a more complex and rich set of functionality support for persistence, please refer to JDeveloper 3.2. We now also have full support for JTA which includes 2 phase commit capability. Because we have redesign the way our client side tools work, we have renamed the old tools that work with 816 with toolname_816. This is to maintain backward compatiblity if you are using an 817 client to talk to an 816 server. Here are a list of them: sess_sh_816 publish_816 Syntax for the client tool sess_sh has changed. You can now access the namespace in the server using three different protocols, http, sess_iiop, and jdbc. Please refer to the 817 documentation for more details. 3.20 Upgrading from 8.1.5 or 8.1.6 to 8.1.7 XML Parser for PL/SQL & Class Generator for Java are not being loaded into the 8.1.7 database while upgrading from 8.1.5/8.1.6. In order to use XML Parser for PL/SQL, you need to load $ORACLE_HOME/lib/xmlplsql.jar and run $ORACLE_HOME/xdk/plsql/parser/bin/load.sql. To use Class Generator for Java, you need to load $ORACLE_HOME/lib/classgen.jar. 3.21 Patches that are available on the CD 3.21.1 C++ version of the login object is now available for C++ client Orbs. The patch is located at $ORACLE_HOME/jis/patch/c++. Please go through the readme for more detail. 3.21.2 #1169155 8.1.6 clients that have previously published corba or ejb objects into the 8.1.6 server and decides to upgrade the server, will run into this compatibility problem. This patch is to be included in the classpath of the 8.1.6 client to continue communicate with the 8.1.7 server. However, to republish a corba object or to redeploy an ejb into 8.1.7 you must use the 8.1.7 tools and libraries. The patch is located at $ORACLE_HOME/jis/patch/816. 4. Oracle Servlet Engine 4.1 Introduction: Welcome to the first release of the Oracle Servlet Engine (OSE). This OSE release is part of Oracle 8.1.7. OSE is compliant with the Servlet Specification, v2.2. OSE is a Java servlet engine that executes within the database. It receives HTTP requests either through a connection from an Apache mod, or directly to the database itself through registered endpoints. OSE is built to serve stateful servlets in a highly scalable fashion, though it is capable of serving static content as well. OSE derives its configuration information from the JNDI namespace accessible with tools in the session shell as described in "Java Tools Reference". Included in this release is the Apache mod, mod_ose, used to connect an Apache installation and OSE. We recommend you use OSE through Apache, such that requests for static content are served by Apache and requests for stateful servlets are forwarded through mod_ose to OSE. Please refer to the "Java Tools Reference" and the "Oracle Servlet Engine User's Guide" for more complete documentation. An "admin" service is installed as part of the OSE installation. This service should only be used for OSE administrative purposes. This service can be made available through port 8080 by the following steps: cd $ORACLE_HOME/jis/install sess_sh -s jdbc:oracle:oci8:@ -u internal/knl_test7 @serverendp.ssh admin 8080 9090 -register exit Please note, the above steps have to be run first before any webserver demos can be run. An example of how to create and configure other services is located in $ORACLE_HOME/javavm/demo/examples/web/service. With the above mentioned steps, the admin service is accessible through http://:8080/. As part of this installation, a portion from the "Java Tools Reference" is accessible through http://:8080/doc/index.htm The administration server runs as the OSE$HTTP$ADMIN user. For security purposes, the admin domain is shipped with a randomized password. To manage your administration server, you will need to set the password of the OSE$HTTP$ADMIN: (from SQLPLUS, connected as internal) sqlplus> alter user ose$http$admin identified by foo; where "foo" is the desired password. Running as SYS, you can of course publish the required servlets and maintain the necessary servlet contexts in the administration server. However, because the administration service runs as the OSE$HTTP$ADMIN user, all accessible servlets and servlet contexts under the domains control must be granted read access to the OSE$HTTP$ADMIN user. 4.2 General OSE Management * If you want to talk to OSE directly, i.e. not through Apache/mod_ose, you need to have an MTS enabled database, i.e., they should have generic MTS dispatchers and MTS servers. * Use the 'addendpoint' tool to dynamically configure the database to listen on user specified ports for incoming HTTP Requests. * It is also possible to declare web server endpoint definitions within the init.ora file with mts_dispatchers declarations. However, 'addendpoint' still needs to be used so that the namespace configuration is consistent, just don't use the -register flag. We have found that the following configurations is helful under heavy laod. 1. SESSIONS parameter in init.ora has to be 1.1 * total_number_of_database_sessions_at_any_particular_moment. (1 database session could have several HTTP session objects - OSE User's Guide page 4.8) 2. JAVA_POOL_SIZE = 1M * total_number_of_database_sessions_at_any_particular_moment 3. For heavy load with mod_ose and tcps protocol we recommend to use several tcps dispatchers and you may have to increase the queuesize for the dispatcher as follows: mts_dispatchers="(address=(protocol=tcps)(queuesize=128))(dispatchers=2)" * For examples of how to set up error, event and access logging, please see the demo located in $ORACLE_HOME/javavm/demo. 4.3 Troubleshooting If the connection is refused by the server: * Check that the proper port was being used for the request. * Check that the correct host name is being used for the request. * Check that the correct port number is configured for the Web Service. This is best done by examining the results of "getgroup endpoint" from the session shell. There should be a list of entries for each named endpoint configured for the service. One of those entries will end with ".port", this indicates that that service should be serving requests that come in on that specified port. 4.3.1 If a 404 is encountered: * Check that that proper port was being used for the request. * Check the URL contains the proper virtual path string that specifies the correct ServletContext. * Check the URL contains the proper virtual path string that specifies the correct servlet within the ServletContext. * Disable (as much as possible) caching in any web browsers being used to test HTTP content. * If the servlet was just published, or configuration information just changed, wait for any active sessions to timeout or close all current browsers and start a completely new browser. 4.3.2 Problems In General: * Use the session shell to explore the namespace and examine the service, domain and serlvet context configurations. * Check namespace permissions against the effective user that is attempting the operation. * Check the error logs and look at trace file content for indications that something went wrong. * It may be helpful to set mts_servers and mts_max_servers in init.ora to both be '1' for specific development troubleshooting. 4.4 File Permissions and Servlet Context Ownership: The user who owns a servlet context should have certain file access rights to avoid some misleading error situations. If no file permissions are granted and the error codes for the servlet context are configured such that the error pages are to be read from the file system (the default configuration) then the owner of that context must have permissions to read those files. Without such permissions, the original error causes another error to occur indicating the lack of file permissions. This will mask the original error code. File access can be obtained multiple ways. The more insecure way to do this is to grant the role JAVAUSERPRIV to the user. For a more secure environment with fine grained control, only grant access to the exact files using the JServer permission calls. Keep in mind that when granting this permission, the canonical path must be used. The canonical path can be found programmatically. Given the following class definition is compiled and loaded into JServer: import java.io.*; public class FileTest { public FileTest() { super(); } public static void main(String[] argv) throws IOException { for (int i = 0; i < argv.length; i++) { File f = new File(argv[i]); System.out.println("file: " + f + " -> " + f.getCanonicalFile()); } } } Then from a session shell, the following command will output the canonical path for the example file '/home/scott/somefile': java FileTest /home/scott/somefile file: /home/scott/somefile -> /private/scott/somefile This means that in the permission grant, '/private/scott/somefile' must be used: dbms_java.grant_permission('SCOTT','SYS:java.io.FilePermission','/private/scott/somefile','read'); 5.0 Apache Module for Oracle Servlet Engine (mod_ose) 5.1 Introduction: The mod_ose module in the Oracle HTTP server (powered by Apache) serves as a conduit between Apache and OSE. It uses HTTP tunneling over Net8 as the protocol between Apache and OSE, thus, leveraging Net8 features such as load balancing, firewall support, connection manager. Unlike mod_jserv which closes connection for every request, mod_ose holds on to the connection to the OSE for the duration of the client connection for stateful application. For, stateless connections, the connection survives for the scope of Apache process. mod_ose uses HTTP chunking for efficient data transfer. (Please refer to Chapter 5 of Oracle Servlet Engine User's Guide for more details on mod_ose). 5.2 Configuration Issues: * The default configuration (the minimum needed Apache directives and location directives for servlets in default configuration) for mod_ose is in the file mod__ose.conf under $APACHE_HOME/Apache/conf. This file is included in oracle_apache.conf, which in turn is included in httpd{s}.conf. The configuration needs to be regenerated using exportwebdomain, if new servlets have been published in the OSE's JNDI namespace. Apache has to be restarted for the new configurations to be effective. * mod_ose is pre-installed and configured, but won't run out of box unless minor changes are made to the configuration file. o For a MTS enabled database, make sure you have an alias name in tnsnames.ora with PRESENTATION, SERVICE_NAME and SERVER set in the CONNECT_DATA clause and use this entry for AuroraService command (in IfModule directive) in mod__ose.conf. Ex: In tnsnames.ora : inst1_http = (DESCRIPTION= (ADDRESS=(PROTOCOL=tcp)(HOST=server27)(PORT=5521)) (CONNECT_DATA= (SERVICE_NAME=rdbms817.rdbms.dev.us.oracle.com) (SERVER=shared) (PRESENTATION=http://admin) ) ) In mod__ose.conf : AuroraService inst1_http o For a non MTS enabled database, mod_ose needs MTS to run and hence won't run if the database doesn't have any MTS dispatchers/servers. Here is the recommended work around: + Create a MTS dispatcher and server with a MODOSE service nam (as a matter of fact we can have any service name other than database service name) as follows: mts_dispatchers="(PROTOCOL=tcp) (SER=MODOSE)" mts_dispatchers="(PROTOCOL=tcps)(SER=MODOSE)" + The alias in the tnsentry should use this service name rather than the database service name. inst1_http = (DESCRIPTION= (ADDRESS=(PROTOCOL=tcp)(HOST=server27)(PORT=5521)) (CONNECT_DATA= (SERVICE_NAME=MODOSE) (SERVER=shared) (PRESENTATION=http://admin) ) ) Thus, we will have MTS dispatcher and server that won't be used by other clients and just used be mod_ose. 5.3 mod_ose and SSL: You can have SSL connection between mod_ose and OSE just like SSL connection between client and the Apache. Make sure you have the following to get this working : * correct Wallet * tcps listener * Aurora service referenced to a tns alias name with tcps protocol and tcps listener port. Ex : inst1_https = (DESCRIPTION= (ADDRESS=(PROTOCOL=tcps)(HOST=server27)(PORT=5524)) (CONNECT_DATA= (SERVICE_NAME=rdbms817.rdbms.dev.us.oracle.com) (SERVER=shared) (PRESENTATION=http://admin) ) ) 5.4 Know Issues: * admin webserver doesn't have index.html and instead has index.htm. Apache by default will send the index.html if you have asked for the admin webservice root through mod_ose and hence will fail. The solution is to explicitly request for index.html. * Because of an Apache bug, if you requested a jsp file with mod_ose that also exist in the local Apache htdocs in the same path, your request will fail. For example, if you have hellouser.jsp under $APACHE_DOCUMENT_ROOT/demo/basic, then a request to mod_ose for /demo/basic/hellouser.jsp (http://server27:3000/demo/basic/hellouser.jsp) will fail. The solution is to make sure that there is no local copy in the same path. 6. JAccelerator ("NComp"). Natively Compiled Java Code This release contains all core Java classes, plus the Aurora/ORB, JDBC, and SQLJ Java classes in natively compiled form. (Note: swing and awt classes, which are included only for compatibility on the server, are not natively compiled). As described in the Java Developer's Guide, the natively compiled code is dynamically opened at runtime using shared object libraries from the ORACLE_HOME/javavm/admin directory. If you need to turn off the use of natively compiled code, please do the following: connect internal alter java class "java/io/Serializable" check; alter system flush shared_pool; alter system flush shared_pool; alter system flush shared_pool; Executing these expressions will "turn off" the use of natively compiled code as classes are loaded at runtime. It will remain turned off until you turn it back on using: alter java class "java/io/Serializable" if needed check; You should consider "turning off" the native compiler for debugging purposes only, or to verify that behavior is consistent between natively compiled and interpreted cases, when you can find no other explanation for anomalous behavior. There are no known problems in this regard in this release. Also note that all Java Compatibility Kit testing performed by Oracle for this release has been done using the same fully natively compiled core classes, ORB, etc, which are delivered; i.e., all testing is done with native compilation "turned on". 6.1 Upgrade, Downgrade, Import, Export Java code that you natively compile in this release will not be automatically upgraded in future Oracle releases. To move to a new Oracle release, you will need to upgrade and then natively compile the code again in the upgraded server. Similarly, import and export of Java code between Oracle databases does not include the natively compiled form of your Java code. In these cases, as long as the O/S and platform are the same, you should redeploy the deployment jar files that you created originally to install natively compiled Java code in another location. 6.2 Security Deployment of natively compiled code in the server is protected by a Java privilege, as described in the documentation. You should understand that this privilege should only be granted when the party installing or supplying the natively compiled code is well-known and trusted. The code generation process employed to produce the shared libraries is provided by and tested extensively by Oracle; however, unlike interpreted Java code and PL/SQL programs, native code is executed from shared libraries that are dynamically opened at runtime. The right to install such shared libraries should be closely controlled. 6.3 Acceptable C Compiler Versions Please review the Settings_.properties file on your platform to determine what C compiler Oracle has certified for supported use with JServer Accelerator in this release. Oracle has continuing work to certify more C compilers against this and future releases and will make such information available on Oracle TechNet on an ongoing basis. 6.4 Known issues 6.4.1 JDK releases to avoid. If there is a choice, avoid, for the purpose of ncomping, Solaris releases of JDK 1.1.7p, 1.2, 1.2.1p and 1.1.3 with native threads. We found problems using these releases. 6.4.2 Java out of memory during translation During translation of very large packages, java may run out of memory. You can work around this problem by forcing Java to grab more memory, by specifying -ms30000000 -mx100000000 in macro 'translate.command' defined in file $ORACLE_HOME/javavm/jahome/Settings.properties 6.4.3 C compiler out of memory during C compilation During compilation of very large packages, C compilers may be getting out of memory. You can switch to the non-bundling mode, compiling each class separately, by omitting makefile.maker = $(one.c.unit.per.dll.makefile.maker) in files javavm/jahome/Settings_solaris.properties and javavm/jahome/Settings_sunos.properties 6.4.4 The flag -update does not work with jdk 1.1.x command-line option -update of 'ncomp' does not work with jdk 1.1.x because the 'jar' facility in these releases does not provide command-line option -u. 6.4.5 KNOWN BUG: Having a dot in directory name of deployment jar aborts deployment If you pass a full-path deployment jar name to deploync, you'll get incorrect results if the directories in the path or the deployment jar contain '.': deploync ... /foo.bar/mydepl.jar deploync ... /foo_bar/my.depl.jar Workaround(1) avoid using '.' in directories and jar names, Workaround(2): use -d: deploync ... -d /foo.bar mydepl.jar 6.4.6 Half of my package previously ncomped now is not! If your app is in 2 jars, and for package P half of its classes are in the first jar and half in the second, then after ncomping the second jar you'll find the classes from the first jar un-ncomped. This is because ncomp deploys dlls on a per-package basis. To avoid such situations, structure the source jars in such way that all classes for a given package P are in a single jar. This also offers the best possible performance. 6.4.7 All toplevels are in the same package UnnamedPackage! Beware of toplevel classes: if you have a toplevel class X, previously ncomped, and then you separately ncomped a toplevel class Y, X will become un-ncomped. This is because all toplevel classes are considered in a special package "UnnamedPackage". 6.4.8 "nothing needs ncomping because nothing is in package P" If your source jar contains packages with non of classes present onto the server, ncomp will report that each individual class is NOT_FOUND_IN_SCHEMA yet each packages is ALREADY_NCOMPED: NOT_FOUND_IN_SCHEMA oracle/aurora/mts/iiop/ORB NOT_FOUND_IN_SCHEMA oracle/aurora/mts/iiop/SessIiopService ... ALREADY_NCOMPED oracle/aurora/mts/iiop/ In this particular case the meaning of this ALREADY_NCOMPED is more like "nothing needs ncomping because nothing is there" 6.4.9 ncomp says NEED_NCOMPING, and then it freezes? After reporting a series of NEED_NCOMPING, ncomp keeps silent until it creates the deployment jar and is ready to deploy. Depending on the machine, this delay can look like a freeze. To see what is going on, tail file ncomp.log. Another variant is to redirect the output to the screen with -verbose. 6.4.10 Solaris-specific Settings_*.properties files On Solaris we ship two platform-specific Settings_*.properties files. Settings_solaris.properties and Settings_sunos.properties File Settings_solaris.properties is picked up by JDKs 1.1.x, file Settings_sunos.properties is picked up by JDKs 1.2.x 6.4.11 Safe levels of C optimizations Some C optimizers generate wrong code for translated java methods with heavy use of try-catch-finally. We found problems with Sunpro 4.2 starting with -O level of optimizations. Therefore we recommend using Sunpro 4.2 with -xO1. If your compiler of choice is Sunpro 6.0, you can use -O. 6.4.12 Managing filespace in javavm/admin The 8.1.7 release of user interface to ncomp does not attempt to manage the dlls in javavm/admin directory. Because dlls have unique names, over time there javavm/admin might accumulate a number of obsolete dlls. For each given package in a given schema, only the most recently deployed dll is in use. You can detect which dlls are in use by analyzing table jaccelerator$dlls) or by running the following script: #!/bin/sh # list of ncomp dlls in use usage () { echo "libs used by ncomped classes foo/bar*" echo "usage: $0 foo/bar" exit 1 } if [ $# -lt 1 ]; then usage; fi DIR=`dirname $0` cat >$DIR/DLLsReport.java <