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:
    <Java class that was being compiled> : ORA-04031:
        unable to allocate <some number of> 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('<classname>') ;

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<sid>.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=<your hostname>)
         (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=<your directory with wallet>)))

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=<your directory with wallet>)))

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 <ejb-name> specified in the Oracle
specific deployment descriptor corresponds to the <ejb-name> 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.

         <container-transaction>
         <description>no description</description>
         <method>
            <ejb-name>/test/purchase</ejb-name>
            <method-name>*</method-name>
         </method>
         <trans-attribute>Required</trans-attribute>
      </container-transaction>

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://<machine_name>:8080/. As part of this installation, a portion from 
the "Java Tools Reference" is accessible through http://<machine_name>: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 <service_name>
  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_<OperatingSystem>.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 <<EOJAVA

package oracle.jaccelerator.utl;
import oracle.aurora.rdbms.Schema;
import oracle.aurora.rdbms.ClassHandle;
import oracle.aurora.rdbms.Handle;
import oracle.aurora.rdbms.ObjectTypeChangedException;
import oracle.sql.CHAR;

import java.io.*;
import java.util.Date;

import java.sql.*;
import oracle.jdbc.driver.*;

public class DLLsReport {
  public static String dll (String schemaAndName) 
    throws SQLException
  {
    int colonIdx = schemaAndName.indexOf(':');
    String name = schemaAndName.substring(colonIdx + 1);
    String schema = schemaAndName.substring(0, colonIdx);
    String  result = "bad handle";

    ClassHandle h = Handle.lookupClass(name, Schema.lookup(schema));
    if (h == null) {
      result = "null handle" + h;
    }
    else {
      result = h.getNcompDllNameAsCHAR().toString();
    }
    return result;
  }
}
EOJAVA

set -x

loadjava -oci8 -resolve -user internal/change_on_install  $DIR/DLLsReport.java

svrmgrl  <<EOI

connect internal/change_on_install

create or replace function isvnc_get_class_dll (pkg varchar2) return VARCHAR2 as
  language java name 'oracle.jaccelerator.utl.DLLsReport.dll(java.lang.String) return java.lang.String';
/
show errors;
select distinct isvnc_get_class_dll(OWNER || ':'  || dbms_java.longname(OBJECT_NAME)) from all_objects where OBJECT_TYPE = 'JAVA CLASS' and dbms_java.longname(OBJECT_NAME) like '$1%' ;

EOI





--  End of README  --

