home *** CD-ROM | disk | FTP | other *** search
/ PC World Komputer 1999 mARCH / PCWK3A99.iso / Unixware / INFO / JAVA_DK / JDKNOTES.TXT < prev   
Text File  |  1998-08-19  |  19KB  |  497 lines
  1.                                RELEASE NOTES
  2.  
  3.             Java Development Kit 1.1.3 for SCO Operating Systems
  4.  
  5. ----------------------------------------------------------------------------
  6.  
  7. Contents
  8.  
  9. License
  10. Introduction
  11. Installation
  12. Documentation
  13. Using JDK 1.1.3 for SCO
  14. Extensions to Sun JDK 1.1.3
  15. Native Methods
  16. Debugging Native Methods
  17. JDBC
  18. Implementation Notes
  19. Known Problems
  20.  
  21. License
  22.  
  23. Please read the license.txt file for the license terms of this SCO product.
  24.  
  25. Introduction
  26.  
  27. These are the release notes for the JavaTM Development Kit (JDK), Release
  28. 1.1.3 for SCO Operating Systems.
  29.  
  30. This product is a full implementation of Sun Microsystems' Java Development
  31. Kit 1.1.3. It enables SCO OEMs, ISVs, and end users to develop and run
  32. applets and applications that conform to the Java 1.1 Core API.
  33.  
  34. Note that in fact this release incorporates SunSoft's JDK 1.1.3A and 1.1.3D
  35. fixes and enhancements to JavaSoft's JDK 1.1.3; this is done to support the
  36. Java Workshop, Java Studio, and JIT compiler products found in the
  37. UnixWare/OpenServer Development Kit (UDK).
  38.  
  39. This JDK product is being released on all three SCO operating system
  40. platforms: UnixWare 7, OpenServer (5.0.4), and UnixWare 2 (2.1.2).
  41.  
  42. (The JDK should also work on OpenServer 5.0.0 and 5.0.2, but is not
  43. conformance tested on those platforms.)
  44.  
  45. For the most part the JDK is identical for all three platforms, and
  46. everything in these release notes applies to all three platforms unless
  47. otherwise noted.
  48.  
  49. The SCO JDK-1.1.3 is packaged in two separate packages:
  50.  
  51.    * jdk113: available both on the UnixWare 7 Base OS CD (part of BaseWeb)
  52.      set and the UDK CD.
  53.    * jdk113pls: available on the UDK CD.
  54.  
  55. The jdk113 includes the essential runtime engine of Java, that is, the
  56. equivalent of an OS's kernel and libraries:
  57.  
  58.    * Java Virtual Machine, JVM (the java command)
  59.    * appletviewer, the Java Applet Viewer
  60.    * basic API libraries
  61.         o language support
  62.         o I/O
  63.         o AWT
  64.         o networking
  65.         o utilities
  66.         o images, media
  67.         o math
  68.         o compression
  69.         o security
  70.  
  71. The jdk113 also includes Java development tools:
  72.  
  73.    * javac, the Java Compiler
  74.    * jdb, the command-line Java debugger
  75.    * javah, the C Header and Stub File Generator for native methods
  76.    * javap, the Java Class File Disassembler
  77.    * javadoc, the JAVA API Documentation Generator
  78.    * jar, the Java Archive (JAR) tool
  79.  
  80. The jdk113 also includes additional components to support distributed
  81. applications and database access:
  82.  
  83.    * Remote Method Invocation (RMI)
  84.    * Java Beans (component object model)
  85.    * JDBC (database access)
  86.  
  87. The jdk113pls includes
  88.  
  89.    * The JavaSoft documentation which contains a full description of the
  90.      different parts of the JDK
  91.    * Many interesting Java demo applets and applications including some
  92.      native method demos
  93.    * Debug versions of many commands, utilities and libraries
  94.  
  95. Installation
  96.  
  97. The SCO JDK-1.1.3 binary distribution is built on and for UnixWare 7, but is
  98. able to run on OpenServer by virtue of the Compatibility Module for
  99. OpenServer, and likewise on UnixWare 2.1.2 by virtue of the Compatibility
  100. Module for UnixWare. Because of this, there are a few differences in how the
  101. JDK is installed on each platform:
  102.  
  103. OpenServer 5.0.4
  104.  
  105. If the UDK Compatibility Module for OpenServer (package name OSRcompat) is
  106. not already installed on our system, you need to mount the UDK CD-ROM and
  107. install the package OSRcompat:
  108.  
  109.      # mount -r /dev/cd0 /mnt
  110.      # pkgadd -d /mnt  OSRcompat
  111.  
  112. When that installation is complete, install the core JDK-1.1.3 (package name
  113. jdk113):
  114.  
  115.      # pkgadd -d /mnt  jdk113
  116.  
  117. Then you can install the JDK-1.1.3 Plus (package name jdk113pls):
  118.  
  119.      # pkgadd -d /mnt  jdk113pls
  120.  
  121. UnixWare 2.1.2
  122.  
  123. If the UDK Compatibility Module for UnixWare (package name UW2compat) is not
  124. already installed on our system, you need to mount the UDK CD-ROM and
  125. install the package UW2compat:
  126.  
  127.      # mount -F cdfs -r /dev/cdrom/* /mnt
  128.      # pkgadd -d /mnt  UW2compat
  129.  
  130. If your machine has more than one CD-ROM drive, specify the CD-ROM device
  131. exactly (e.g. /dev/cdrom/c0b0t6l0).
  132.  
  133. When that installation is complete, install the core JDK-113 (package name
  134. jdk113):
  135.  
  136.      # pkgadd -d /mnt  jdk113
  137.  
  138. Then you can install the JDK-113 Plus (package name jdk113pls):
  139.  
  140.      # pkgadd -d /mnt  jdk113pls
  141.  
  142. Alternatively, the graphical desktop tool App_Installer may be used to
  143. install these packages.
  144.  
  145. Note that you may need to increase certain system memory limits; see Using
  146. JDK 1.1 for SCO below.
  147.  
  148. UnixWare 7
  149.  
  150. The jdk113 package is installed automatically during Initial System Load
  151. (ISL) of the UnixWare 7 Base OS. (The jdk113 package is part of the BaseWeb
  152. set which is on the Base OS CD).
  153.  
  154. However, if you de-selected the jdk113 during ISL, you can install it from
  155. UnixWare 7 CD in the following way:
  156.  
  157. Mount the CD-ROM and install the JDK (package name jdk113):
  158.  
  159.      # mount -F cdfs -r /dev/cdrom/* /mnt
  160.      # pkgadd -d /mnt  jdk113
  161.  
  162. If your machine has more than one CD-ROM drive, specify the CD-ROM device
  163. exactly (e.g. /dev/cdrom/c0b0t6l0).
  164.  
  165. Documentation
  166.  
  167. Documentation for the JDK 1.1.3 is contained in the jdk113pls package. All
  168. of the documentation is in HTML format and may be viewed with any browser
  169. you have installed on your system.
  170.  
  171.                          Document                          File/Link Name
  172.  these release notes                                     ReleaseNotes.html
  173.  JavaSoft documentation for JDK 1.1.3 (same as for 1.1.4)docs/index.html
  174.  JavaSoft demos for JDK 1.1.3                            demo/
  175.  documentation on SCO's JDBC implementation
  176.  and SCO's SQL-Retriever product                         see JDBC section
  177.  
  178. Note that these documents are not integrated into the graphical help system
  179. on your platform (e.g. the ScoHelp).
  180.  
  181. Also note that much of this documentation is from JavaSoft, but should be
  182. read in an SCO context. For instance, for "Solaris" read any of the three
  183. SCO platforms (UnixWare 7, OpenServer 5.0.4, UnixWare 2.1.2). For customer
  184. support, any of the normal SCO support mechanisms should be used, rather
  185. than contacting Sun.
  186.  
  187. Using JDK 1.1.3 for SCO
  188.  
  189. In general, use of JDK 1.1.3 for SCO follows that which is described in the
  190. JavaSoft documentation.
  191.  
  192. After the JDK packages are installed, you probably want to set PATH in your
  193. .profile to include the directory where the JDK commands are installed,
  194. /usr/java/bin. On UnixWare 7 systems, this will usually have been done for
  195. you already when your account was created.
  196.  
  197. On UnixWare 2.1.2, applications of significant size are likely to get "out
  198. of memory" errors with the default memory limits provided by the operating
  199. system. To fix this, do the following as root:
  200.  
  201.      # /etc/conf/bin/idtune -m HVMMLIM 0x7FFFFFFF
  202.      # /etc/conf/bin/idtune -m HDATLIM 0x7FFFFFFF
  203.      # /etc/conf/bin/idtune -m SVMMLIM 0x7FFFFFFF
  204.      # /etc/conf/bin/idtune -m SDATLIM 0x7FFFFFFF
  205.      # /etc/conf/bin/idbuild
  206.  
  207. and then reboot to rebuild the kernel.
  208.  
  209. On all three platforms, you need to give an xhost command for your machine
  210. if you are using appletviewer (see Known Problems below).
  211.  
  212. Extensions to Sun JDK 1.1.3
  213.  
  214. SCO has provided only one functional extension to Sun's JDK 1.1.3, and it is
  215. useful only on the UnixWare 7 platform.
  216.  
  217. Java Classes as First-Class Executables
  218.  
  219. When javac is used to compile one or more classes, it will set the execute
  220. permissions bit on for the .class file if the class contains a main method.
  221. (This happens on all three platforms.)
  222.  
  223. Then, on UnixWare 7 only, you can execute a Java application simply by
  224. giving the name of the main class:
  225.  
  226.      $ foo.class
  227.  
  228. UnixWare 7 will look for foo.class by use of the PATH environment variable,
  229. just as it would for any other executable. foo.class must also be in the
  230. CLASSPATH, as in normal execution.
  231.  
  232. Furthermore, by making a hard link or symbolic link such as
  233.  
  234.      $ ln -s foo.class foo
  235.  
  236. you will be able to execute the application simply by saying
  237.  
  238.      $ foo
  239.  
  240. For instance, this gives you the ability let users invoke utilities without
  241. knowing the utilities are written in Java. For this to work you must keep
  242. the name prefix intact and the class file intact. That is, you have to keep
  243. foo.class somewhere, and then you can make a hard or soft link of foo to it.
  244. foo can be in another directory, but you can't change the name; i.e., you
  245. can't link bar to it. That's because once the system invokes the JVM, it
  246. expects to find a foo.class file there. For this same reason you also can't
  247. just rename foo.class to foo, because the JVM will still need a foo.class.
  248. (You could copy foo.class to foo, but that will of course waste disk space
  249. compared to a link.)
  250.  
  251. Of course, you can always use the traditional way of executing a Java
  252. application:
  253.  
  254.      $ java foo
  255.  
  256. In this case, java must be in the PATH, and foo.class must be in the
  257. CLASSPATH.
  258.  
  259. Native Methods
  260.  
  261. Both the JNI-style native methods added as of JDK 1.1 and the old-style,
  262. lower-level native methods from JDK 1.0.2 are supported in this release.
  263.  
  264. C and C++ native methods must be compiled and linked with the SCO
  265. UnixWare/OpenServer Development Kit (UDK). This means that native methods
  266. cannot be built with the existing development kit on OpenServer or UnixWare
  267. 2.
  268.  
  269. Some of the reasons for this requirement include:
  270.  
  271.    * native methods need the C/C++ 64-bit long long data type, to match the
  272.      Java 64-bit long data type
  273.  
  274.    * C++ native methods need for the C++ standard library to be a dynamic
  275.      library (libC.so) rather than an archive (libC.a)
  276.  
  277.    * native methods using X must reference X11R6 headers, since that is what
  278.      the JDK AWT uses
  279.  
  280.    * native methods must use the same calling conventions, header files, and
  281.      libraries as the JVM, which has itself been built with the UDK
  282.  
  283. All of these items are in the UDK but not in the existing development kit on
  284. OpenServer and UnixWare 2.1.2. The UDK can be used either on OpenServer or
  285. UnixWare 2.1.2 itself, or native method dynamic libraries can be built with
  286. the UDK on UnixWare 7 Gemini then moved to OpenServer or UnixWare 2.1.2.
  287.  
  288. Another important limitation with native methods is upon the kinds of system
  289. operations that a native method can do. In particular:
  290.  
  291.    * a native method cannot make use of the threads library, libthread.so
  292.      from UnixWare 2.1.2 or UnixWare 7.
  293.    * direct native methods access to commercial database systems is
  294.      potentially hazardous due to inappropriate system-level usages by the
  295.      DBMSes conflicting with the JVM; use JDBC instead
  296.  
  297. SCO-specific examples of the commands needed to build old- and new-style
  298. native methods with C and C++ are included in the demos part of the JDK
  299. 1.1.3 (in the jdk113pls package), under the subdirectories native_c_demo,
  300. jni_c_demo, native_c++_demo, and jni_c++_demo.
  301.  
  302. Debugging Native Methods
  303.  
  304. Debugging of Java applications is done with the JDK-provided jdb debugger,
  305. as described in the relevant JavaSoft documentation.
  306.  
  307. Debugging of C or C++ native methods, however, must be done with the UDK
  308. debugger. This section describes how to go about this.
  309.  
  310. One thing you'll notice is that after-the-fact core dumps from the JVM
  311. (which might be caused by a native method bug) are pretty useless, because
  312. the traceback comes from a JVM signal handler rather than from the real
  313. point of failure.
  314.  
  315. The solution to this is to run the application, i.e., the JVM, from within
  316. the debugger. Then when a segmentation violation occurs, for instance, the
  317. debugger will stop right there and the stack trace will be from the real
  318. point of failure.
  319.  
  320. In order to run the JVM from within the debugger, you need to invoke the JVM
  321. executable directly. First, you should run the java_g version of the JVM,
  322. since that contains debugging information. Second, if you look at
  323. /usr/java/bin/java_g, you'll see that it's a link to a script called
  324. .java_wrapper, that sets up the LD_LIBRARY_PATH and CLASSPATH environment
  325. variables before calling the actual JVM executable in
  326. /usr/java/bin/x86at/green_threads/java_g.
  327.  
  328. If you invoke /usr/java/bin/java_g through ksh -x you'll see the values
  329. LD_LIBRARY_PATH and CLASSPATH are set to; you can set those manually at the
  330. command line (store in a script that you "dot" if you debug frequently),
  331. then invoke the debugger:
  332.  
  333.      $ . setup_java  # your script to set LD_LIBRARY_PATH and CLASSPATH
  334.      $ debug -ic     # or can use graphical version
  335.      debug> create /usr/java/bin/x86at/green_threads/java_g my_app
  336.      debug> run
  337.      debug>
  338.  
  339. Another complication sets in when you want to use symbols (to set
  340. breakpoints on, for instance) that are outside of the JVM, such as in native
  341. methods. The dynamic libraries that contain native methods are loaded by the
  342. JVM via the dlopen call, and until this happens, symbols in the native
  343. methods won't be visible to the debugger.
  344.  
  345. The solution to this is to set a breakpoint inside the JVM at the point
  346. where the dynamic library has been loaded, but before code in the libraries
  347. is called. For JDK 1.1.3 the appropriate breakpoint is linker_md.c@207. Here
  348. is an example demonstrating both the problem and the solution:
  349.  
  350.      $ debug -ic
  351.      debug> create /usr/java/bin/x86at/green_threads/java_g my_app
  352.      debug> stop my_nativemethod_function
  353.      Error: No entry "my_nativemethod_function" exists
  354.  
  355.      debug> stop linker_md.c@207
  356.      EVENT [1] assigned
  357.      debug> run
  358.      STOP EVENT TRIGGERED: linker_md.c@207  in p1 [sysAddDLSegment in ../../../../src/unixware/java/runtime/linker_md.c]
  359.      207:        dlsegment[useddlsegments].fname = strdup(fn);
  360.      debug> stop my_nativemethod_function
  361.      EVENT [2] assigned
  362.      debug> run
  363.      STOP EVENT TRIGGERED: my_nativemethod_function in p1 [my_nativemethod_function in myfile.C]
  364.      68:         bool finished = false;
  365.      debug>
  366.  
  367. You can debug normally from that point on.
  368.  
  369. If you do a lot of this kind of debugging it can be useful to set up an
  370. alias in your ~/.debugrc file:
  371.  
  372.      alias cnm create /usr/java/bin/x86at/green_threads/java_g ; run -u linker_md.c@207
  373.  
  374. Then just giving the cnm command to the debugger will bring you to the point
  375. where you can set breakpoints in your native method code.
  376.  
  377. JDBC
  378.  
  379. Java Database Connectivity is a standard SQL database access interface for
  380. Java, providing uniform access for Java applications to a wide range of
  381. relational databases.
  382.  
  383. The JDK 1.1.3 for SCO contains SCO's implementation of JDBC and includes the
  384. SCO JDBC driver. SCO's JDBC implementation is built upon SCO's SQL-Retriever
  385. product. For more information on SCO SQL-Retriever, please visit
  386. www.vision.sco.com .
  387.  
  388. There is no need to separately install the SCO JDBC implementation, since it
  389. is part of the jdk113 installation. It is necessary to separately install
  390. the SQL-Retriever product if you are interested in using JDBC.
  391.  
  392. Implementation Notes
  393.  
  394. In general one of the important characteristics of Java is that it behaves
  395. in exactly the same fashion on all platforms. However there are a few areas
  396. where it may be useful to know how the JDK has been implemented on SCO
  397. platforms.
  398.  
  399. System Properties
  400.  
  401. If it is necessary for application code to determine which of the three SCO
  402. platforms it is running on, the Java class System.Properties can be queried.
  403. Here are some of the values that will be returned on all SCO platforms:
  404.  
  405.      java.home=/usr/java
  406.      java.vendor=SCO
  407.      java.vendor.url=http://www.sco.com/
  408.      java.class.version=45.3
  409.  
  410. while here are values that are specific to OpenServer 5.0.4:
  411.  
  412.      os.arch=IA32
  413.      os.name=OpenServer
  414.      os.version=5.0.4
  415.  
  416. UnixWare 2.1.2:
  417.  
  418.      os.arch=IA32
  419.      os.name=UnixWare
  420.      os.version=2.1.2
  421.  
  422. and UnixWare 7:
  423.  
  424.      os.arch=IA32
  425.      os.name=UnixWare
  426.      os.version=7
  427.  
  428. Abstract Windowing Toolkit
  429.  
  430. This implementation uses the X Windows System, version X11R6.1, to implement
  431. the Java Abstract Windowing Toolkit.
  432.  
  433. Threads
  434.  
  435. This implementation uses Sun's "green threads" implementation of Java
  436. threads rather than "native threads" implementation. This means the Java VM
  437. controls the scheduling and context switching of Java threads. In a native
  438. threads implementation, Java threads would be mapped onto an operating
  439. system library and the scheduling and context switching would be done by the
  440. operating system.
  441.  
  442. Performance
  443.  
  444. This implementation uses an assembly-coded main interpreter loop for faster
  445. bytecode execution. [However, the debug version java_g uses the C-language
  446. interpreter.]
  447.  
  448. Conformance
  449.  
  450. This release of JDK 1.1.3 for SCO has passed Sun's Java Compatibility Kit
  451. (JCK) 1.1.2a test suite.
  452.  
  453. Known Problems
  454.  
  455. This section contains known problems with SCO's port of JDK 1.1.3 to SCO
  456. platforms. For known problems with Sun's JDK 1.1.x releases themselves, see
  457. the list at JavaSoft's website.
  458.  
  459.   1. On all three platforms, the X11R6 implementation is currently built to
  460.      only use TCP/IP as a connection mechanism. This means that even when
  461.      working locally, you need to issue an xhost +your_machine_name command.
  462.  
  463.   2. On OpenServer (5.0.4) and UnixWare (2.1.2) when appletviewer or java
  464.      are invoked you may see the following message which may be ignored:
  465.      current locale is not supported in X11, locale is set to CX locale
  466.      modifiers are not supported, using default
  467.  
  468.   3. Old-style C++ native method stubs created by javah do not compile with
  469.      the UDK C++ compiler if the methods involved have class or array
  470.      parameters, or if the method is not static (meaning it has a class this
  471.      parameter). The problem is that the generated stub code expects that a
  472.      void* value can be implicitly converted to a pointer-to-struct, which
  473.      is not allowed in C++.
  474.  
  475.      As a workaround, edit the generated stub code to insert a cast of the
  476.      void* to the proper pointer-to-struct type.
  477.  
  478.      Alternatively, use JNI native methods, which do not have this problem.
  479.  
  480.      SCO will be preparing a PTF to the javah command for this problem.
  481.  
  482.   4. The jdb command does not work when given a class name on the command
  483.      line. Instead, a spurious invalid password message is given.
  484.  
  485.      As a workaround, the program under test can be started using the java_g
  486.      -debug command, and then jdb can be invoked separately using the -host
  487.      and -password options.
  488.  
  489.      Alternatively, Java WorkShop can be used to debug Java programs.
  490.  
  491.      SCO will be preparing a PTF to the jdb command for this problem.
  492.  
  493.   5. Large file support (for files > 2GB in size) is not yet present in the
  494.      java.io package, or anywhere else in the JDK.
  495.  
  496. Copyright ⌐ 1997 The Santa Cruz Operation, Inc. All Rights Reserved.
  497.