home *** CD-ROM | disk | FTP | other *** search
/ Java Programmer's Toolkit / Java Programmer's Toolkit.iso / solaris2 / jdk / readme < prev    next >
Encoding:
Text File  |  1995-10-30  |  10.1 KB  |  295 lines
  1.                  README: The Java Developers Kit
  2.  
  3.  
  4. This Beta release of the Java Developers Kit (JDK) lets you
  5. write applets that conform to the new, frozen Java applet API.  
  6.  
  7.  
  8. The JDK helps you to:
  9. ---------------------
  10.     - Develop applets that conform to the final applet API
  11.     - Convert existing 1.0 Alpha 3 applets 
  12.     - Create applets that run in all Java-enabled browsers
  13.     - Develop Java applications
  14.     - Experiment with the new debugger API (and a prototype
  15.       command-line debugger)
  16.  
  17.  
  18. Supported platforms
  19. -------------------
  20. The JDK is available for SPARC Solaris, Windows NT, and Windows 95.
  21.   
  22.  
  23. The JDK contains:
  24. -----------------
  25.     - Java Applet Upgrade Utility, 
  26.            for help in converting applets to the new API
  27.  
  28.     - Java Applet Viewer, 
  29.            for testing and running applets
  30.  
  31.     - Java Debugger API and Prototype Debugger,
  32.              an API (java.tools.debug) and early prototype
  33.              of a command-line debugger that uses the API
  34.  
  35.     - Java Compiler
  36.  
  37.     - Java Interpreter
  38.         
  39. NOTE: This release does NOT include a Web browser. 
  40.  
  41.  
  42. What is the final applet API?
  43. ------------------------------
  44. The final applet API consists of the following packages:  java.lang,
  45. java.util, java.io, java.net, java.awt, java.awt.peer, java.awt.image,
  46. and java.applet.  We and our partners are committed to supporting
  47. this API.
  48.  
  49.  
  50. ----------------------------------------------------------------------
  51. IMPORTANT: Please make sure you understand the Copyright and License
  52. information (in the file named COPYRIGHT) before using this release.
  53. ----------------------------------------------------------------------
  54.  
  55.  
  56. The rest of this document has the following sections:
  57.  
  58. - Where to find more information
  59. - Converting existing applets
  60. - Running applets with the Applet Viewer
  61. - The APPLET tag
  62. - Debugging programs with JDB
  63.  
  64.  
  65. Where to find more information
  66. ------------------------------
  67. This file is the only documentation included in this release.  The
  68. rest of the information you need is on our website:
  69.  
  70.     http://java.sun.com/JDK-beta/
  71.  
  72. It includes the following:
  73.  
  74. - More help on converting Alpha 3 applets 
  75. - Frequently asked questions
  76. - Changes since the last release
  77. - Applet examples (some of which are in this release, as well)
  78. - API documentation 
  79. - Documentation for the Java programming tools (including java,
  80.   javac, and jdb)
  81. - The latest Java Language Specification 
  82. - Known bugs in the JDK 
  83.  
  84. If you have questions, problems, or comments:
  85.  
  86. 1. Check out the FAQ at:
  87.  
  88.     http://java.sun.com/JDK-beta/faq.html
  89.  
  90. 2. Before filing a bug report, please check the known bugs at:
  91.  
  92.     http://java.sun.com/JDK-beta/KnownBugs-JDK.html
  93.  
  94.    File bug reports using the form at:
  95.  
  96.     http://java.sun.com/GettingInTouch/BugReport.html
  97.  
  98. 3. The Java/HotJava mailing lists are active forums for posting
  99.    questions and exchanging information with other Java users.
  100.    See http://java.sun.com/mail.html for information on accessing
  101.    the mailing lists.
  102.  
  103. 4. Other questions can be sent to java@java.sun.com.
  104.  
  105.  
  106. Converting existing applets
  107. ---------------------------
  108. The first step in converting any applet is to run the upgrade script
  109. on it.  The upgrade script uses the sed utility to perform some simple
  110. substitutions.  The sed utility is available on all UNIX systems,
  111. but not on most PCs.  If your system has sed, run the upgrade script
  112. like this:
  113.  
  114.   bin/upgrade < SomeOldApplet.java > SomeNewApplet.java
  115.  
  116. If your system doesn't have sed, you need to make the substitutions
  117. by hand.  You can find out which substitutions to make either by 
  118. looking at the upgrade file or by reading the conversion documentation
  119. at our website (http://java.sun.com/JDK-beta/converting/).
  120.  
  121. Once you've run the upgrade script (or performed the equivalent
  122. subsitutions by hand), compile the applet to see what happens.  Maybe
  123. you'll be lucky -- maybe it will compile cleanly and you won't have
  124. to do anything else to make it work.
  125.  
  126. Chances are, however, that you will have to make more changes to your
  127. applet.  Some of the reasons:
  128.  
  129. - Applets are now integrated with the AWT -- in fact, Applet is now a
  130.   subclass of the AWT Panel class, making Applets inherently graphical
  131.   objects that can contain other graphical objects.  This means that
  132.   applets can (and should) use the the standard graphical user
  133.   interface classes, such as Button, TextArea, List, and so on.  It
  134.   also means that Applets use the same event-handling and drawing
  135.   interfaces as other graphical objects.
  136.  
  137. - The Applet class no longer has any public instance variables.
  138.  
  139. - The AWT API has changed significantly.
  140.  
  141. - Images are now processed asynchronously, which can greatly improve
  142.   perceived performance.  It means, however, that whenever you send a
  143.   message to an Image object (asking it for the image's width, for
  144.   example), you need to be aware that the image might not be loaded
  145.   yet.
  146.  
  147. - Exceptions have changed.  First, the exception hierarchy has
  148.   changed.  Second, the Java language has changed so that methods
  149.   must declare the exceptions that they can throw.  For example:
  150.  
  151.     void doSomething() throws AnException, AnotherException {
  152.         . . .
  153.     }
  154.  
  155. For more information on converting applets, see
  156.  
  157.     http://java.sun.com/JDK-beta/converting/
  158.  
  159.  
  160. Running applets with the Applet Viewer
  161. --------------------------------------
  162. Here are two examples of using the Applet Viewer:
  163.  
  164.   bin/appletviewer demo/GraphLayout/example1.html
  165.   bin/appletviewer http://java.sun.com/JDK-prebeta1/applets/NervousText/example1.html 
  166.   (On the PC, use "bin\appletviewer" instead of "bin/appletviewer".)
  167.  
  168. The argument is a filename or URL that refers to an HTML file that
  169. contains one or more APPLET tags.  The Applet Viewer finds the APPLET
  170. tags in the HTML file and runs the applets as specified by the tags
  171. (in separate windows).
  172.  
  173.  
  174. The APPLET tag
  175. --------------
  176. The APP tag of previous releases is gone, replaced by the APPLET tag. 
  177. Here is an example of a simple APPLET tag:
  178.  
  179.   <applet code="MyApplet.class" width=100 height=140></applet>
  180.  
  181. This tells the viewer or browser to load the applet whose compiled
  182. code is in MyApplet.class (in the same directory as the current HTML
  183. document), and to set the initial size of the applet to 100 pixels
  184. wide and 140 pixels high.
  185.  
  186. Here's a more complex example of an APPLET tag:
  187.  
  188.   <applet codebase="http://java.sun.com/JDK-prebeta1/applets/NervousText"
  189.     code="NervousText.class" width=400 height=75 align=center >
  190.   <param name="text" value="This is the Applet Viewer.">
  191.   <blockquote>
  192.   <hr>
  193.   If you were using a Java-enabled browser,
  194.   you would see dancing text instead of this paragraph.
  195.   <hr>
  196.   </blockquote>
  197.   </applet>
  198.  
  199. This tells the viewer or browser to load the applet whose compiled
  200. code is at the URL
  201. http://java.sun.com/JDK-prebeta1/applets/NervousText/NervousText.class,
  202. to set the initial size of the applet to 400x75 pixels, and to align
  203. the applet in the center of the line.  The viewer/browser must also
  204. set the applet's "text" attribute (which customizes the text this
  205. applet displays) to be "This is the Applet Viewer."  If the page is
  206. viewed by a browser that can't execute Java applets, then the browser
  207. will ignore the APPLET and PARAM tags, displaying the HTML between
  208. the <blockquote> and </blockquote> tags.  Java-enabled browsers
  209. *ignore* that HTML.
  210.  
  211. Here's the complete syntax for the APPLET tag:
  212.  
  213.     '<' 'APPLET'
  214.         ['CODEBASE' '=' codebaseURL]
  215.         'CODE' '=' appletFile
  216.     ['ALT' '=' alternateText]
  217.     ['NAME' '=' appletInstanceName]
  218.     'WIDTH' '=' pixels 'HEIGHT' '=' pixels
  219.     ['ALIGN' '=' alignment]
  220.     ['VSPACE' '=' pixels] ['HSPACE' '=' pixels]
  221.     '>'
  222.     ['<' 'PARAM' 'NAME' '=' appletAttribute1 'VALUE' '=' value '>']
  223.     ['<' 'PARAM' 'NAME' '=' appletAttribute2 'VALUE' '=' value '>']
  224.     . . .
  225.     [alternateHTML]
  226.     '</APPLET>'
  227.  
  228. 'CODEBASE' '=' codebaseURL
  229.     This optional attribute specifies the base URL of the applet --
  230.     the directory that contains the applet's code.  If this attribute
  231.     is not specified, then the document's URL is used.
  232.  
  233. 'CODE' '=' appletFile
  234.     This required attribute gives the name of the file that contains
  235.     the applet's compiled Applet subclass.  This file is relative to
  236.     the base URL of the applet.  It cannot be absolute.
  237.     
  238. 'ALT' '=' alternateText
  239.     This optional attribute specifies any text that should be
  240.     displayed if the browser understands the APPLET tag but can't
  241.     run Java applets.
  242.  
  243. 'NAME' '=' appletInstanceName
  244.     This optional attribute specifies a name for the applet instance,
  245.     which makes it possible for applets on the same page to find (and
  246.     communicate with) each other.
  247.  
  248. 'WIDTH' '=' pixels 'HEIGHT' '=' pixels
  249.     These required attributes give the initial width and height (in
  250.     pixels) of the applet display area, not counting any windows or
  251.     dialogs that the applet brings up.  
  252.  
  253. 'ALIGN' '=' alignment
  254.     This required attribute specifies the alignment of the applet.
  255.     The possible values of this attribute are the same as those for
  256.     the IMG tag: left, right, top, texttop, middle, absmiddle,
  257.     baseline, bottom, absbottom.
  258.  
  259. 'VSPACE' '=' pixels 'HSPACE' '=' pixels
  260.     These option attributes specify the number of pixels above and
  261.     below the applet (VSPACE) and on each side of the applet (HSPACE).
  262.     They're treated the same way as the IMG tag's VSPACE and HSPACE
  263.     attributes.
  264.  
  265. '<' 'PARAM' 'NAME' '=' appletAttribute1 'VALUE' '=' value '>' . . .
  266.     This tag is the only way to specify an applet-specific attribute.
  267.     Applets access their attributes with the getParameter() method.
  268.  
  269.  
  270. Debugging programs with JDB
  271. ---------------------------
  272. This release contains the Java Debugger (JDB), an alpha-quality
  273. prototype of a command-line debugger for Java classes.  It is
  274. designed to test the Java Debugger API, which is in the package
  275. java.tools.debug.  We look forward to getting your feedback on
  276. the debugger API.
  277.  
  278. You can debug applets using the -debug option of appletviewer.
  279. When debugging applets, it's best to invoke appletviewer from
  280. the directory that contains the applet's HTML file.  For example,
  281. on Solaris:
  282.  
  283.     cd demo/TicTacToe
  284.     ../../bin/appletviewer -debug example1.html 
  285.  
  286. On the PC:
  287.  
  288.     cd demo\TicTacToe
  289.     ..\..\bin\appletviewer -debug example1.html 
  290.     
  291. You can find documentation on the debugger and its API at:
  292.  
  293.     http://java.sun.com/JDK-beta/debugging/
  294.  
  295.