PC World Komputer 1999 March

home *** CD-ROM | disk | FTP | other *** search

/ PC World Komputer 1999 March / PCWK3A99.iso / Unixware / INFO / JAVA_DK / JDKNOTES.TXT < prev

Wrap

Text File | 1998-08-19 | 18.1 KB | 497 lines

RELEASE NOTES Java Development Kit 1.1.3 for SCO Operating Systems ---------------------------------------------------------------------------- Contents License Introduction Installation Documentation Using JDK 1.1.3 for SCO Extensions to Sun JDK 1.1.3 Native Methods Debugging Native Methods JDBC Implementation Notes Known Problems License Please read the license.txt file for the license terms of this SCO product. Introduction These are the release notes for the JavaTM Development Kit (JDK), Release 1.1.3 for SCO Operating Systems. This product is a full implementation of Sun Microsystems' Java Development Kit 1.1.3. It enables SCO OEMs, ISVs, and end users to develop and run applets and applications that conform to the Java 1.1 Core API. Note that in fact this release incorporates SunSoft's JDK 1.1.3A and 1.1.3D fixes and enhancements to JavaSoft's JDK 1.1.3; this is done to support the Java Workshop, Java Studio, and JIT compiler products found in the UnixWare/OpenServer Development Kit (UDK). This JDK product is being released on all three SCO operating system platforms: UnixWare 7, OpenServer (5.0.4), and UnixWare 2 (2.1.2). (The JDK should also work on OpenServer 5.0.0 and 5.0.2, but is not conformance tested on those platforms.) For the most part the JDK is identical for all three platforms, and everything in these release notes applies to all three platforms unless otherwise noted. The SCO JDK-1.1.3 is packaged in two separate packages: * jdk113: available both on the UnixWare 7 Base OS CD (part of BaseWeb) set and the UDK CD. * jdk113pls: available on the UDK CD. The jdk113 includes the essential runtime engine of Java, that is, the equivalent of an OS's kernel and libraries: * Java Virtual Machine, JVM (the java command) * appletviewer, the Java Applet Viewer * basic API libraries o language support o I/O o AWT o networking o utilities o images, media o math o compression o security The jdk113 also includes Java development tools: * javac, the Java Compiler * jdb, the command-line Java debugger * javah, the C Header and Stub File Generator for native methods * javap, the Java Class File Disassembler * javadoc, the JAVA API Documentation Generator * jar, the Java Archive (JAR) tool The jdk113 also includes additional components to support distributed applications and database access: * Remote Method Invocation (RMI) * Java Beans (component object model) * JDBC (database access) The jdk113pls includes * The JavaSoft documentation which contains a full description of the different parts of the JDK * Many interesting Java demo applets and applications including some native method demos * Debug versions of many commands, utilities and libraries Installation The SCO JDK-1.1.3 binary distribution is built on and for UnixWare 7, but is able to run on OpenServer by virtue of the Compatibility Module for OpenServer, and likewise on UnixWare 2.1.2 by virtue of the Compatibility Module for UnixWare. Because of this, there are a few differences in how the JDK is installed on each platform: OpenServer 5.0.4 If the UDK Compatibility Module for OpenServer (package name OSRcompat) is not already installed on our system, you need to mount the UDK CD-ROM and install the package OSRcompat: # mount -r /dev/cd0 /mnt # pkgadd -d /mnt OSRcompat When that installation is complete, install the core JDK-1.1.3 (package name jdk113): # pkgadd -d /mnt jdk113 Then you can install the JDK-1.1.3 Plus (package name jdk113pls): # pkgadd -d /mnt jdk113pls UnixWare 2.1.2 If the UDK Compatibility Module for UnixWare (package name UW2compat) is not already installed on our system, you need to mount the UDK CD-ROM and install the package UW2compat: # mount -F cdfs -r /dev/cdrom/* /mnt # pkgadd -d /mnt UW2compat If your machine has more than one CD-ROM drive, specify the CD-ROM device exactly (e.g. /dev/cdrom/c0b0t6l0). When that installation is complete, install the core JDK-113 (package name jdk113): # pkgadd -d /mnt jdk113 Then you can install the JDK-113 Plus (package name jdk113pls): # pkgadd -d /mnt jdk113pls Alternatively, the graphical desktop tool App_Installer may be used to install these packages. Note that you may need to increase certain system memory limits; see Using JDK 1.1 for SCO below. UnixWare 7 The jdk113 package is installed automatically during Initial System Load (ISL) of the UnixWare 7 Base OS. (The jdk113 package is part of the BaseWeb set which is on the Base OS CD). However, if you de-selected the jdk113 during ISL, you can install it from UnixWare 7 CD in the following way: Mount the CD-ROM and install the JDK (package name jdk113): # mount -F cdfs -r /dev/cdrom/* /mnt # pkgadd -d /mnt jdk113 If your machine has more than one CD-ROM drive, specify the CD-ROM device exactly (e.g. /dev/cdrom/c0b0t6l0). Documentation Documentation for the JDK 1.1.3 is contained in the jdk113pls package. All of the documentation is in HTML format and may be viewed with any browser you have installed on your system. Document File/Link Name these release notes ReleaseNotes.html JavaSoft documentation for JDK 1.1.3 (same as for 1.1.4)docs/index.html JavaSoft demos for JDK 1.1.3 demo/ documentation on SCO's JDBC implementation and SCO's SQL-Retriever product see JDBC section Note that these documents are not integrated into the graphical help system on your platform (e.g. the ScoHelp). Also note that much of this documentation is from JavaSoft, but should be read in an SCO context. For instance, for "Solaris" read any of the three SCO platforms (UnixWare 7, OpenServer 5.0.4, UnixWare 2.1.2). For customer support, any of the normal SCO support mechanisms should be used, rather than contacting Sun. Using JDK 1.1.3 for SCO In general, use of JDK 1.1.3 for SCO follows that which is described in the JavaSoft documentation. After the JDK packages are installed, you probably want to set PATH in your .profile to include the directory where the JDK commands are installed, /usr/java/bin. On UnixWare 7 systems, this will usually have been done for you already when your account was created. On UnixWare 2.1.2, applications of significant size are likely to get "out of memory" errors with the default memory limits provided by the operating system. To fix this, do the following as root: # /etc/conf/bin/idtune -m HVMMLIM 0x7FFFFFFF # /etc/conf/bin/idtune -m HDATLIM 0x7FFFFFFF # /etc/conf/bin/idtune -m SVMMLIM 0x7FFFFFFF # /etc/conf/bin/idtune -m SDATLIM 0x7FFFFFFF # /etc/conf/bin/idbuild and then reboot to rebuild the kernel. On all three platforms, you need to give an xhost command for your machine if you are using appletviewer (see Known Problems below). Extensions to Sun JDK 1.1.3 SCO has provided only one functional extension to Sun's JDK 1.1.3, and it is useful only on the UnixWare 7 platform. Java Classes as First-Class Executables When javac is used to compile one or more classes, it will set the execute permissions bit on for the .class file if the class contains a main method. (This happens on all three platforms.) Then, on UnixWare 7 only, you can execute a Java application simply by giving the name of the main class: $ foo.class UnixWare 7 will look for foo.class by use of the PATH environment variable, just as it would for any other executable. foo.class must also be in the CLASSPATH, as in normal execution. Furthermore, by making a hard link or symbolic link such as $ ln -s foo.class foo you will be able to execute the application simply by saying $ foo For instance, this gives you the ability let users invoke utilities without knowing the utilities are written in Java. For this to work you must keep the name prefix intact and the class file intact. That is, you have to keep foo.class somewhere, and then you can make a hard or soft link of foo to it. foo can be in another directory, but you can't change the name; i.e., you can't link bar to it. That's because once the system invokes the JVM, it expects to find a foo.class file there. For this same reason you also can't just rename foo.class to foo, because the JVM will still need a foo.class. (You could copy foo.class to foo, but that will of course waste disk space compared to a link.) Of course, you can always use the traditional way of executing a Java application: $ java foo In this case, java must be in the PATH, and foo.class must be in the CLASSPATH. Native Methods Both the JNI-style native methods added as of JDK 1.1 and the old-style, lower-level native methods from JDK 1.0.2 are supported in this release. C and C++ native methods must be compiled and linked with the SCO UnixWare/OpenServer Development Kit (UDK). This means that native methods cannot be built with the existing development kit on OpenServer or UnixWare 2. Some of the reasons for this requirement include: * native methods need the C/C++ 64-bit long long data type, to match the Java 64-bit long data type * C++ native methods need for the C++ standard library to be a dynamic library (libC.so) rather than an archive (libC.a) * native methods using X must reference X11R6 headers, since that is what the JDK AWT uses * native methods must use the same calling conventions, header files, and libraries as the JVM, which has itself been built with the UDK All of these items are in the UDK but not in the existing development kit on OpenServer and UnixWare 2.1.2. The UDK can be used either on OpenServer or UnixWare 2.1.2 itself, or native method dynamic libraries can be built with the UDK on UnixWare 7 Gemini then moved to OpenServer or UnixWare 2.1.2. Another important limitation with native methods is upon the kinds of system operations that a native method can do. In particular: * a native method cannot make use of the threads library, libthread.so from UnixWare 2.1.2 or UnixWare 7. * direct native methods access to commercial database systems is potentially hazardous due to inappropriate system-level usages by the DBMSes conflicting with the JVM; use JDBC instead SCO-specific examples of the commands needed to build old- and new-style native methods with C and C++ are included in the demos part of the JDK 1.1.3 (in the jdk113pls package), under the subdirectories native_c_demo, jni_c_demo, native_c++_demo, and jni_c++_demo. Debugging Native Methods Debugging of Java applications is done with the JDK-provided jdb debugger, as described in the relevant JavaSoft documentation. Debugging of C or C++ native methods, however, must be done with the UDK debugger. This section describes how to go about this. One thing you'll notice is that after-the-fact core dumps from the JVM (which might be caused by a native method bug) are pretty useless, because the traceback comes from a JVM signal handler rather than from the real point of failure. The solution to this is to run the application, i.e., the JVM, from within the debugger. Then when a segmentation violation occurs, for instance, the debugger will stop right there and the stack trace will be from the real point of failure. In order to run the JVM from within the debugger, you need to invoke the JVM executable directly. First, you should run the java_g version of the JVM, since that contains debugging information. Second, if you look at /usr/java/bin/java_g, you'll see that it's a link to a script called .java_wrapper, that sets up the LD_LIBRARY_PATH and CLASSPATH environment variables before calling the actual JVM executable in /usr/java/bin/x86at/green_threads/java_g. If you invoke /usr/java/bin/java_g through ksh -x you'll see the values LD_LIBRARY_PATH and CLASSPATH are set to; you can set those manually at the command line (store in a script that you "dot" if you debug frequently), then invoke the debugger: $ . setup_java # your script to set LD_LIBRARY_PATH and CLASSPATH $ debug -ic # or can use graphical version debug> create /usr/java/bin/x86at/green_threads/java_g my_app debug> run debug> Another complication sets in when you want to use symbols (to set breakpoints on, for instance) that are outside of the JVM, such as in native methods. The dynamic libraries that contain native methods are loaded by the JVM via the dlopen call, and until this happens, symbols in the native methods won't be visible to the debugger. The solution to this is to set a breakpoint inside the JVM at the point where the dynamic library has been loaded, but before code in the libraries is called. For JDK 1.1.3 the appropriate breakpoint is linker_md.c@207. Here is an example demonstrating both the problem and the solution: $ debug -ic debug> create /usr/java/bin/x86at/green_threads/java_g my_app debug> stop my_nativemethod_function Error: No entry "my_nativemethod_function" exists debug> stop linker_md.c@207 EVENT [1] assigned debug> run STOP EVENT TRIGGERED: linker_md.c@207 in p1 [sysAddDLSegment in ../../../../src/unixware/java/runtime/linker_md.c] 207: dlsegment[useddlsegments].fname = strdup(fn); debug> stop my_nativemethod_function EVENT [2] assigned debug> run STOP EVENT TRIGGERED: my_nativemethod_function in p1 [my_nativemethod_function in myfile.C] 68: bool finished = false; debug> You can debug normally from that point on. If you do a lot of this kind of debugging it can be useful to set up an alias in your ~/.debugrc file: alias cnm create /usr/java/bin/x86at/green_threads/java_g ; run -u linker_md.c@207 Then just giving the cnm command to the debugger will bring you to the point where you can set breakpoints in your native method code. JDBC Java Database Connectivity is a standard SQL database access interface for Java, providing uniform access for Java applications to a wide range of relational databases. The JDK 1.1.3 for SCO contains SCO's implementation of JDBC and includes the SCO JDBC driver. SCO's JDBC implementation is built upon SCO's SQL-Retriever product. For more information on SCO SQL-Retriever, please visit www.vision.sco.com . There is no need to separately install the SCO JDBC implementation, since it is part of the jdk113 installation. It is necessary to separately install the SQL-Retriever product if you are interested in using JDBC. Implementation Notes In general one of the important characteristics of Java is that it behaves in exactly the same fashion on all platforms. However there are a few areas where it may be useful to know how the JDK has been implemented on SCO platforms. System Properties If it is necessary for application code to determine which of the three SCO platforms it is running on, the Java class System.Properties can be queried. Here are some of the values that will be returned on all SCO platforms: java.home=/usr/java java.vendor=SCO java.vendor.url=http://www.sco.com/ java.class.version=45.3 while here are values that are specific to OpenServer 5.0.4: os.arch=IA32 os.name=OpenServer os.version=5.0.4 UnixWare 2.1.2: os.arch=IA32 os.name=UnixWare os.version=2.1.2 and UnixWare 7: os.arch=IA32 os.name=UnixWare os.version=7 Abstract Windowing Toolkit This implementation uses the X Windows System, version X11R6.1, to implement the Java Abstract Windowing Toolkit. Threads This implementation uses Sun's "green threads" implementation of Java threads rather than "native threads" implementation. This means the Java VM controls the scheduling and context switching of Java threads. In a native threads implementation, Java threads would be mapped onto an operating system library and the scheduling and context switching would be done by the operating system. Performance This implementation uses an assembly-coded main interpreter loop for faster bytecode execution. [However, the debug version java_g uses the C-language interpreter.] Conformance This release of JDK 1.1.3 for SCO has passed Sun's Java Compatibility Kit (JCK) 1.1.2a test suite. Known Problems This section contains known problems with SCO's port of JDK 1.1.3 to SCO platforms. For known problems with Sun's JDK 1.1.x releases themselves, see the list at JavaSoft's website. 1. On all three platforms, the X11R6 implementation is currently built to only use TCP/IP as a connection mechanism. This means that even when working locally, you need to issue an xhost +your_machine_name command. 2. On OpenServer (5.0.4) and UnixWare (2.1.2) when appletviewer or java are invoked you may see the following message which may be ignored: current locale is not supported in X11, locale is set to CX locale modifiers are not supported, using default 3. Old-style C++ native method stubs created by javah do not compile with the UDK C++ compiler if the methods involved have class or array parameters, or if the method is not static (meaning it has a class this parameter). The problem is that the generated stub code expects that a void* value can be implicitly converted to a pointer-to-struct, which is not allowed in C++. As a workaround, edit the generated stub code to insert a cast of the void* to the proper pointer-to-struct type. Alternatively, use JNI native methods, which do not have this problem. SCO will be preparing a PTF to the javah command for this problem. 4. The jdb command does not work when given a class name on the command line. Instead, a spurious invalid password message is given. As a workaround, the program under test can be started using the java_g -debug command, and then jdb can be invoked separately using the -host and -password options. Alternatively, Java WorkShop can be used to debug Java programs. SCO will be preparing a PTF to the jdb command for this problem. 5. Large file support (for files > 2GB in size) is not yet present in the java.io package, or anywhere else in the JDK. Copyright ⌐ 1997 The Santa Cruz Operation, Inc. All Rights Reserved.