home *** CD-ROM | disk | FTP | other *** search
/ PC Plus SuperCD 12 / 12_pcplus_supercd.iso / COMUN / JVM / IBM_ENU / README.TXT < prev   
Encoding:
Text File  |  1997-06-12  |  11.3 KB  |  285 lines
  1.                    Java Runtime Environment
  2.  
  3.                            Information
  4.  
  5.                             5/21/97
  6.  
  7.  
  8.   1.0 Introduction
  9.   2.0 Using the JRE 1.1.1
  10.   3.0 Questions and Answers
  11.  
  12.  
  13.  
  14. 1.0 Introduction
  15.  
  16.   The Java Runtime Environment (also known as the Java Runtime
  17.   or JRE) consists of the Java Virtual Machine, Java Core
  18.   Classes, and supporting files. It is the runtime part of the
  19.   JDK--no compiler, no debugger, no tools. It is the smallest
  20.   set of executables and files that form the standard Java
  21.   Platform. This product satisfies the demands for the smallest
  22.   runtime to be bundled with Java applications.
  23.  
  24.  
  25.  
  26. 2.0 Using the JRE 1.1.1
  27.  
  28.  
  29.   The JRE provides three built-in places to put classes, as
  30.   shown in the following diagram.
  31.  
  32.                             <runtime-dir>
  33.                    _________________|________________
  34.                   |            |              |
  35.                  bin          lib          classes 
  36.                   |        ____|____          |
  37.                           |         |      *.class
  38.                           |         |    
  39.                         rt.jar  classes.jar
  40.  
  41.  
  42.   lib/rt.jar          Java runtime core classes provided by Sun
  43.  
  44.   lib/classes.jar     Vendor-defined classes in jar format  
  45.  
  46.   classes/*.classes Vendor-defined individual .class files 
  47.  
  48.  
  49. 2.1 Setting Up the JRE with an Application
  50.   
  51.   The following steps are necessary to set up the JRE 1.1.1
  52.   with an application:
  53.  
  54.       1.   Install JRE in its own subdirectory (referred to here
  55.            as <runtime-dir>).  Include all the the required files
  56.            listed above in the bin and lib subdirectories of
  57.            <runtime-dir>, following the same directory hierarchy
  58.            and relative placement of files (the default classpath
  59.            depends on this).  The internationalization files
  60.            marked as optional can be included for non-native
  61.            language support.
  62.  
  63.       2.   Place all application-specific classes either as
  64.            individual .class files in the classes directory or
  65.            zipped in a file at lib/classes.jar.
  66.  
  67.            Both locations are automatically included in the
  68.            default runtime class path, so they will be found
  69.            even if you do not explicitly set the CLASSPATH
  70.            environment variable. The file classes.jar can be
  71.            created using the JAR tool included with JDK 1.1 or
  72.            any PKZIP-compatible ZIP archiving tool that
  73.            supports DEFLATE compression, such as InfoZIP or
  74.            WinZIP.
  75.  
  76.       3.   If native code support is required, the native library
  77.            must be located in LD_LIBRARY_PATH on Solaris or the
  78.            executable search PATH on Win32. The best way to do
  79.            this is to install the native libraries in either
  80.            <runtime-dir>/lib/<sys> on Solaris or <runtime-
  81.            dir>\bin on Win32.
  82.  
  83.       4.   If installing a pure Java application, use the runtime 
  84.            executable program (<runtime-dir>\bin\java.exe on
  85.            Windows or <runtime-dir>/bin/java on Solaris) to
  86.            invoke the application's main class. For example:
  87.  
  88.               <runtime-dir>/bin/java <app-main>
  89.   
  90.            For applications that require the invocation API to
  91.            start the Java runtime, it is necessary to write a
  92.            custom C wrapper that uses the JNI invocation API. 
  93.  
  94.  
  95.  
  96.   2.2 Creating and Bundling a Java Application on Top of JRE
  97.  
  98.       The following is an extended example of how to create and
  99.       bundle a simple Java application which runs on top of a
  100.       JRE included with it. 
  101.  
  102.       It is worthwhile to note the directory structure of JRE
  103.       components. The structure of the JRE is intentionally
  104.       almost identical to that of the JDK (with some files
  105.       missing and a few files renamed). The intention is to
  106.       allow for a simple, seamless transition from developing
  107.       an application with the JDK to deploying it with the more
  108.       lightweight JRE. 
  109.  
  110.  
  111.       1.   Develop an application.
  112.  
  113.            Developing an application requires a copy of the
  114.            JDK, or some other development tool. Our example
  115.            application is a simple GUI, jre.demo.HelloWorld.
  116.            The HelloWorld.java source is included.
  117.  
  118.            To invoke the example, change to the "bin"
  119.            directory and execute "hello".
  120.   
  121.       2.   From the JRE Download Page, download the JRE for each
  122.            platform you intend to deploy on. 
  123.  
  124.  
  125.       3.   Compile into shareable Native libraries.
  126.   
  127.            Should your application require native methods, you
  128.            should first compile these into a shareable native
  129.            library specific to your target
  130.            platform/architecture. 
  131.  
  132.            Our example program has a simple native method to
  133.            illustrate the point. These Solaris and Win32
  134.            Makefiles demonstrate how this compilation might be
  135.            done. (Here is the source for the JNI-style native
  136.            method. On win32, once you have built a .DLL, it
  137.            should be placed in the $(JRE_TOP)\bin directory
  138.            (next to all the java runtime's dll's). On Solaris,
  139.            your .SO should be placed in the 
  140.            $(JRE_TOP)/lib/$(ARCH)/$(THREADS_TYPE)
  141.            subdirectory, where $(ARCH) denotes the target
  142.            architecture (for this example, the architecture is
  143.            "sparc") and $(THREADS_TYPE) is the type of threads
  144.            the Solaris VM is using (for now, this must be
  145.            "green_threads").
  146.  
  147.            In the example programs, you'll see files called
  148.            $(JRE_TOP)\bin\HelloWorld.dll on Win32 and
  149.            $(JRE_TOP)/lib/sparc/green_threads/HelloWorld.so on
  150.            Solaris. Make sure the names of your native
  151.            libraries do not overwrite any of the JRE's native
  152.            libraries. 
  153.  
  154.  
  155.       4.   Build a platform-specific executable.
  156.  
  157.            Your application needs some kind of starting point,
  158.            a simple program that is the first thing the end
  159.            user executes. This program, in turn, invokes the
  160.            public static void main(String[] argv) method of
  161.            your Java class. 
  162.  
  163.            On Windows, if you have access to a C compiler
  164.            during development, a small C program is the best
  165.            way to do this. The sample program, hello.c, will
  166.            do nicely. You can compile this with a macro
  167.            defining JAVA_ARGS to be the name of your Java
  168.            class that defines main(String[] argv). An added
  169.            benefit of using a small C program like this one on
  170.            Windows is that, when compiled with DWINMAIN, you
  171.            can have a purely Windows application (that is, one
  172.            that does not pop up a console when started by
  173.            double-clicking on the desktop), if it is GUI-
  174.            based. 
  175.  
  176.            On UNIX, a wrapper Korn-shell script like this can
  177.            be used to invoke the Java interpreter on your main
  178.            class. 
  179.  
  180.  
  181.            These Makefiles for Win32 and Solaris were used to
  182.            build the example programs. Both these simple
  183.            wrapper programs should be located in the
  184.            $(JRE_TOP)/bin directory. These wrappers look very
  185.            much like the wrappers that invoke the Java
  186.            interpreter in the JDK. However, there's one main
  187.            difference you should note, described in the
  188.            following paragraphs. 
  189.  
  190.            Both the wrappers make sure to unset the CLASSPATH
  191.            and JAVA_HOME environment variables before invoking
  192.            the interpreter. These variables can be convenient
  193.            while doing development on top of the JDK, but they
  194.            can cause trouble when your application is
  195.            installed on a user's machine. The reason is
  196.            simple: There might be several Java applications
  197.            installed on that machine. If a user has installed
  198.            a Java development tool that modified the
  199.            AUTOEXEC.BAT or .login script, then CLASSPATH and
  200.            JAVA_HOME might point at a JDK1.0.2-based java
  201.            runtime. 
  202.  
  203.            If these environment variables are left intact when
  204.            the Java interpreter is invoked, then it pulls
  205.            1.0.2 classes. If you rely on 1.1 features, your
  206.            program fails in serious ways. Worse, it's unlikely
  207.            that the classes for your app will even be found in
  208.            that CLASSPATH. Unsetting CLASSPATH and JAVA_HOME
  209.            before invoking the JRE interpreter sanitizes your
  210.            application against unpredictable results. 
  211.  
  212.            The default CLASSPATH used by the JRE is: 
  213.              
  214.            $(JRE_TOP)/lib/rt.jar:$(JRE_TOP)/lib/i18n.jar:$(JRE
  215.            _TOP)/lib/
  216.                
  217.            classes.jar:$(JRE_TOP)/lib/classes.zip:$(JRE_TOP)/c
  218.            lasses
  219.  
  220.            where the variable $(JRE_TOP) is defined to be the
  221.            directory where the JRE is installed (it has bin
  222.            and lib directories underneath it). rt.jar and
  223.            i18n.jar are used to hold the runtime's (required)
  224.            core classes and (optional) internationalization
  225.            classes, so it is recommended that you store the
  226.            classes specific to your application either in
  227.            $(JRE_TOP)/lib/classes.jar or else as individual
  228.            class files in the $(JRE_TOP)/classes subdirectory. 
  229.  
  230.  
  231.       5.   Build, test, and ship.
  232.  
  233.            Once you have built your wrapper executables and
  234.            put them in the (JRE_TOP)/bin subdirectory, your
  235.            application should be ready.
  236.  
  237.            As with any software product, a final round of
  238.            testing is advisable, now that your program has
  239.            taken its finished form atop the JRE. 
  240.  
  241.  
  242.  
  243. 3.0 Questions and Answers
  244.  
  245.         Question: How should my application find other
  246.         resources, such as images, sounds, and other files,
  247.         when it runs on top of the JRE? Where should I store
  248.         these things? 
  249.  
  250.         Answer: Running the JDK's interpreter, you can always
  251.         find the top directory where the JDK is installed from
  252.         Java by: 
  253.  
  254.            String javaHome = System.getProperty("java.home");
  255.            /** This is the runtime directory path to the top
  256.            of where * the Java runtime is installed.  It has
  257.            the bin and lib * directories underneath it. */
  258.       
  259.  
  260.         The mechanism is identical when your application is
  261.         running on top of the JRE. In fact, our sample
  262.         application HelloWorld.java uses this mechanism at
  263.         runtime to find the image it displays. The image is
  264.         stored in the lib directory below $(JRE_TOP) (or
  265.         $(JAVA_HOME); the two are equivalent): 
  266.  
  267.              void loadImage() throws IOException {
  268.                 URL imgURL;
  269.  
  270.                 String jh = System.getProperty("java.home");
  271.                 String file = jh + File.separator+"lib"+
  272.                     File.separator+"smooch.gif";
  273.                 imgURL = new URL("file", "", file);
  274.                 ....
  275.               }      
  276.       
  277.  
  278.         As an aside, the lib subdirectory is the usual place
  279.         to store and find such resources--as long as the file
  280.         names don't collide with any of the files already
  281.         there in the JRE. 
  282.  
  283.  
  284.  
  285.