home *** CD-ROM | disk | FTP | other *** search
/ Programming Languages Suite / JBuilder8.iso / Solaris / resource / jre / man / sman1 / jar.1 < prev    next >
Encoding:
Text File  |  2002-09-06  |  16.0 KB  |  317 lines
  1. <!DOCTYPE REFENTRY PUBLIC "-//Sun Microsystems//DTD DocBook V3.0-Based SolBook Subset V2.0//EN" [
  2. <!--ArborText, Inc., 1988-1999, v.4002-->
  3. <!ENTITY % javaents SYSTEM "javaman.ent">
  4. %javaents;
  5. ]>
  6. <?Pub UDT _bookmark _target>
  7. <?Pub Inc>
  8. <refentry id="jar-1">
  9. <!--@(#)jar.1 1.19 01/03/14 SMI;-->
  10. <refmeta><refentrytitle>jar</refentrytitle><manvolnum>1</manvolnum>
  11. <refmiscinfo class="date">23 Apr 2001</refmiscinfo>
  12. <refmiscinfo class="sectdesc">&man1;</refmiscinfo>
  13. <refmiscinfo class="software">&java-release;</refmiscinfo>
  14. <refmiscinfo class="arch">generic</refmiscinfo>
  15. <refmiscinfo class="copyright"> Copyright 2001 Sun Microsystems, Inc. All
  16. rights reserved.  Copyright 2001 Sun Microsystems, Inc. Tous droits réservés.
  17. </refmiscinfo>
  18. </refmeta>
  19. <refnamediv><refname>jar</refname><refpurpose>Java archive tool</refpurpose>
  20. </refnamediv>
  21. <refsynopsisdiv><title>&synp-tt;</title>
  22. <cmdsynopsis><command>jar</command><arg choice="opt"><option>C</option></arg>
  23. <arg choice="opt">c</arg><arg choice="opt">f</arg><arg choice="opt">i</arg>
  24. <arg choice="opt">J</arg><arg choice="opt">M</arg><arg choice="opt">m</arg>
  25. <arg choice="opt">O</arg><arg choice="opt">t</arg><arg choice="opt">u</arg>
  26. <arg choice="opt">v</arg><arg choice="opt"><arg choice="plain">x</arg><arg
  27. choice="plain"><replaceable>file</replaceable></arg></arg><arg choice="opt"><replaceable>
  28. manifest-file</replaceable></arg><arg choice="plain"><replaceable>destination
  29. </replaceable></arg><arg choice="plain"><replaceable>input-file</replaceable></arg>
  30. <arg choice="opt"><replaceable>input-files</replaceable></arg>
  31. </cmdsynopsis></refsynopsisdiv>
  32. <refsect1><title>&desc-tt;</title>
  33. <indexterm id="jar-1-indx-1"><primary sortas="Java archive tool">Java archive
  34. tool — jar</primary></indexterm><indexterm id="jar-1-indx-2"><primary
  35. sortas="jar">jar — Java archive tool</primary></indexterm><para>The <command>
  36. jar</command> tool is a Java™ application that combines multiple files
  37. into a single <acronym>JAR</acronym> archive file. It is also a general-purpose
  38. archiving and compression tool, based on <acronym remap="small">ZIP</acronym>
  39. and the <acronym remap="small">ZLIB</acronym> compression format. However, <command>
  40. jar</command> was designed mainly to facilitate the packaging of Java applets
  41. or applications into a single archive. When the components of an applet or
  42. application (.class files, images and sounds) are combined into a single archive,
  43. they can be downloaded by a Java agent (like a browser) in a single <acronym
  44. remap="small">HTTP</acronym> transaction, rather than require a new connection
  45. for each piece. This dramatically improves download time. The <command>jar
  46. </command> tool also compresses files, which further improves download time.
  47. In addition, it allows individual entries in a file to be signed by the applet
  48. author so that their origins can be authenticated. The syntax for the <command>
  49. jar</command> tool is almost identical to the syntax for the <citerefentry>
  50. <refentrytitle>tar</refentrytitle><manvolnum>1</manvolnum></citerefentry>
  51. command. A <acronym>JAR</acronym> archive can be used as a class path entry,
  52. whether or not it is compressed.</para>
  53. <para>The three types of input files for the <command>jar</command> tool are:
  54. </para>
  55. <itemizedlist>
  56. <listitem><para>Manifest file (optional)</para></listitem>
  57. <listitem><para>Destination <acronym>JAR</acronym> file</para></listitem>
  58. <listitem><para>Files to be archived</para></listitem>
  59. </itemizedlist>
  60. <para>Typical usage is:</para>
  61. <informalexample>
  62. <screen>example% <userinput>jar cf myjarfile *.class</userinput> </screen>
  63. </informalexample>
  64. <para>In this example, all the class files in the current directory are placed
  65. in the file named <literal>myjarfile</literal>. A manifest file is automatically
  66. generated by the <command>jar</command> tool and is always the first entry
  67. in the <acronym>JAR</acronym> file. By default, it is named <literal remap="small and bold">
  68. META-INF/MANIFEST.MF</literal>. The manifest file is the place where any meta-information
  69. about the archive is stored. Refer to the <citetitle>Manifest Format</citetitle>
  70. in the &also-tt; section for details about how meta-information is stored
  71. in the manifest file.</para>
  72. <para>To use a pre-existing manifest file to create a new <acronym>JAR</acronym>
  73. archive, specify the old manifest file with the <option role="nodash">m</option>
  74. option:</para>
  75. <informalexample>
  76. <screen>example% <userinput>jar cmf myManifestFile myJarFile *.class</userinput></screen>
  77. </informalexample>
  78. <para>When you specify <option role="nodash">cfm</option> instead of  <option
  79. role="nodash">cmf</option> (that is, you invert the order of the  <option
  80. role="nodash">m</option> and <option role="nodash">f</option> options), you
  81. need to specify the name of the <acronym>JAR</acronym> archive first, followed
  82. by the name of the manifest file:</para>
  83. <informalexample>
  84. <screen>example% <userinput>jar cfm myJarFile myManifestFile *.class</userinput></screen>
  85. </informalexample>
  86. <para>The manifest uses RFC822 <acronym remap="small">ASCII</acronym> format,
  87. so it is easy to view and process manifest-file contents.</para>
  88. </refsect1>
  89. <refsect1><title>&opts-tt;</title>
  90. <para>The following options are supported:</para>
  91. <variablelist termlength="xtranarrow">
  92. <varlistentry><term><option>C</option></term><listitem><para>Changes directories
  93. during execution of the <command>jar</command> command. For example:<informalexample>
  94. <screen>example% <userinput>jar uf foo.jar –C classes *</userinput></screen>
  95. </informalexample></para>
  96. </listitem></varlistentry>
  97. <varlistentry><term><option role="nodash">c</option></term><listitem><para>
  98. Creates a new or empty archive on the standard output.</para>
  99. </listitem></varlistentry>
  100. <varlistentry><term><option role="nodash">f</option></term><listitem><para>
  101. The second argument specifies a <acronym>JAR</acronym> file to process. In
  102. the case of creation, this refers to the name of the <acronym>JAR</acronym>
  103. file to be created (instead of on <literal>stdout</literal>). For table or
  104. xtract, the second argument identifies the <acronym>JAR</acronym> file to
  105. be listed or extracted.</para>
  106. </listitem></varlistentry>
  107. <varlistentry><term><option role="nodash">i</option></term><listitem><para>
  108. Generates index information for the specified <acronym>JAR</acronym> file
  109. and its dependent <acronym>JAR</acronym> files. For example:<informalexample>
  110. <screen>example% <userinput>jar i foo.jar</userinput><?Pub Caret></screen>
  111. </informalexample>would generate an <literal remap="small and bold">INDEX.LIST
  112. </literal> file in <literal>foo.jar</literal> which contains location information
  113. for each package in <literal>foo.jar</literal> and all the <acronym>JAR</acronym>
  114. files specified in <literal>foo.jar</literal>'s Class-Path attribute.</para>
  115. </listitem></varlistentry>
  116. <varlistentry><term><option role="nodash">J</option><replaceable>option</replaceable></term>
  117. <listitem><para>Pass <replaceable>option</replaceable> to the Java virtual
  118. machine, where option is one of the options described on the man page for
  119. the java application launcher, java (1). For example, <literal>-J-Xms48m</literal>
  120. sets the startup memory to 48 megabytes. It is a common convention for <literal>
  121. -J</literal> to pass options to the underlying virtual machine.</para>
  122. </listitem></varlistentry>
  123. <varlistentry><term><option role="nodash">M</option></term><listitem><para>
  124. Does not create a manifest file for the entries.</para>
  125. </listitem></varlistentry>
  126. <varlistentry><term><option role="nodash">m</option></term><listitem><para>
  127. Includes manifest information from specified pre-existing manifest file. Example
  128. use:<informalexample>
  129. <screen>example% <userinput>jar cmf myManifestFile myJarFile *.class</userinput></screen>
  130. </informalexample>You can add special-purpose name-value attribute headers
  131. to the manifest file that are not contained in the default manifest. Examples
  132. of such headers are those for vendor information, version information, package
  133. sealing, and headers to make <acronym>JAR</acronym>-bundled applications executable.
  134. See the <citetitle>JAR Files</citetitle> trail in the <citetitle>Java Tutorial
  135. </citetitle> and the <citetitle>JRE Notes for Developers</citetitle> web page
  136. for examples of using the <option role="nodash">m</option> option.</para>
  137. </listitem></varlistentry>
  138. <varlistentry><term><option role="nodash">O</option></term><listitem><para>
  139. Stores only, without using <acronym remap="small">ZIP</acronym> compression.
  140. </para>
  141. </listitem></varlistentry>
  142. <varlistentry><term><option role="nodash">t</option></term><listitem><para>
  143. Lists the table of contents from standard output.</para>
  144. </listitem></varlistentry>
  145. <varlistentry><term><option role="nodash">u</option></term><listitem><para>
  146. Updates an existing <acronym>JAR</acronym> file by adding files or changing
  147. the manifest. For example:<informalexample>
  148. <screen>example% <userinput>jar uf foo.jar foo.class</userinput></screen>
  149. </informalexample>adds the file  <literal>foo.class</literal> to the existing <acronym>
  150. JAR</acronym> file <literal>foo.jar</literal>, and<informalexample>
  151. <screen>example% <userinput>jar umf foo.jar</userinput> </screen>
  152. </informalexample>updates <literal>foo.jar</literal>'s manifest with the information
  153. in manifest.</para>
  154. </listitem></varlistentry>
  155. <varlistentry><term><option role="nodash">v</option></term><listitem><para>
  156. Generates verbose output on <literal>stderr</literal>.</para>
  157. </listitem></varlistentry>
  158. <varlistentry><term><option role="nodash">x</option> <replaceable>file</replaceable></term>
  159. <listitem><para>Extracts all files, or just the named files, from standard
  160. input. If <replaceable>file</replaceable> is omitted, then all files are extracted;
  161. otherwise, only the specified file or files are extracted. If any of the <replaceable>
  162. file</replaceable>s is a directory, then that directory is processed recursively.
  163. </para>
  164. </listitem></varlistentry>
  165. </variablelist></refsect1>
  166. <refsect1><title>&exam-tt;</title>
  167. <example role="example">
  168. <title>Adding all of the files in a particular directory to an archive</title>
  169. <para><screen>example% <userinput>ls</userinput>
  170. <computeroutput>0.au         3.au         6.au          9.au            at_work.gif
  171. 1.au         4.au         7.au          Animator.class  monkey.jpg
  172. e.au         5.au         8.au          Wave.class      spacemusic.au
  173. example% jar cvf bundle.jar *
  174. adding: 0.au
  175. adding: 1.au
  176. adding: 2.au
  177. adding: 3.au
  178. adding: 4.au
  179. adding: 5.au
  180. adding: 6.au
  181. adding: 7.au
  182. adding: 8.au
  183. adding: 9.au
  184. adding: Animator.class
  185. adding: Wave.class
  186. adding: at_work.gif
  187. adding: monkey.jpg
  188. adding: spacemusic.au
  189. example%</computeroutput>
  190.  
  191. </screen></para>
  192. </example>
  193. <example role="example">
  194. <title>Archiving subdirectories</title>
  195. <para>If you already have subdirectories for images, audio files, and classes
  196. that already exist in an HTML directory, use <command>jar</command> to archive
  197. each directory to a single <acronym>JAR</acronym> file:</para>
  198. <para><screen>example% <userinput>ls</userinput>
  199. <computeroutput>audio classes images</computeroutput>
  200. example% <userinput>jar cvf bundle.jar audio classes images</userinput>
  201. <computeroutput>adding: audio/1.au
  202. adding: audio/2.au
  203. adding: audio/3.au
  204. adding: audio/spacemusic.au
  205. adding: classes/Animator.class
  206. adding: classes/Wave.class
  207. adding: images/monkey.jpg
  208. adding: images/at_work.gif
  209. example% ls –l
  210. total 142
  211. drwxr-xr-x   2 brown    green        512 Aug  1 22:33 audio
  212. -rw-r--r--   1 brown    green      68677 Aug  1 22:36 bundle.jar
  213. drwxr-xr-x   2 brown    green        512 Aug  1 22:26 classes
  214. drwxr-xr-x   2 brown    green        512 Aug  1 22:25 images</computeroutput>
  215. example% </screen></para>
  216. </example>
  217. <example role="example">
  218. <title>Finding entry names in the JAR file</title>
  219. <para>To see the entry names in the <acronym>JAR</acronym> file using the <command>
  220. jar</command> tool and the <option role="nodash">t</option> option:</para>
  221. <para><screen>example% <userinput>ls</userinput>
  222. <computeroutput>audio bundle.jar classes images</computeroutput>
  223. example% <userinput>jar tf bundle.jar</userinput>
  224. <computeroutput>META-INF/MANIFEST.MF
  225. audio/1.au
  226. audio/2.au
  227. audio/3.au
  228. audio/spacemusic.au
  229. classes/Animator.class
  230. classes/Wave.class
  231. images/monkey.jpg
  232. images/at_work.gif</computeroutput>
  233. example% </screen></para>
  234. </example>
  235. <example role="example">
  236. <title>Displaying more information about files in the archive</title>
  237. <para>To display more information about the files in the archive, such as
  238. their size and last modified date, use the <option role="nodash">v</option>
  239. option:</para>
  240. <para><screen>example% <userinput>jar tvf bundle.jar</userinput>
  241. <computeroutput>145 Thu Aug 01 22:27:00 PDT 1996 META-INF/MANIFEST.MF
  242. 946 Thu Aug 01 22:24:22 PDT 1996 audio/1.au
  243. 1039 Thu Aug 01 22:24:22 PDT 1996 audio/2.au
  244. 993 Thu Aug 01 22:24:22 PDT 1996 audio/3.au
  245. 48072 Thu Aug 01 22:24:23 PDT 1996 audio/spacemusic.au
  246. 16711 Thu Aug 01 22:25:50 PDT 1996 classes/Animator.class
  247. 3368 Thu Aug 01 22:26:02 PDT 1996 classes/Wave.class
  248. 12809 Thu Aug 01 22:24:48 PDT 1996 images/monkey.jpg
  249. 527 Thu Aug 01 22:25:20 PDT 1996 images/at_work.gif</computeroutput>
  250. example% </screen></para>
  251. </example>
  252. <example role="example">
  253. <title>Speeding up an application's class loading time</title>
  254. <para>If you bundled a stock trade application (applet) into the following <acronym>
  255. JAR</acronym> files:<informalexample>
  256. <screen>main.jar buy.jar sell.jar other.jar</screen>
  257. </informalexample>and you specified the <literal>Class-Path</literal> attribute
  258. in <literal>main.jar</literal>'s manifest as<informalexample>
  259. <screen>Class-Path: buy.jar sell.jar other.jar </screen>
  260. </informalexample>then you can use the <option role="nodash">i</option> option
  261. to speed up your application's class loading time:<informalexample>
  262. <screen>example$ <userinput>jar i main.jar</userinput></screen>
  263. </informalexample>An <literal remap="small and bold">INDEX.LIST</literal>
  264. file is inserted in the <literal remap="small and bold">META-INF</literal>
  265. directory which will enable the application class loader to download the right <acronym>
  266. JAR</acronym> files when it is searching for classes or resources.</para>
  267. </example>
  268. </refsect1>
  269. <refsect1><title>&attr-tt;</title>
  270. <para>See <citerefentry><refentrytitle>attributes</refentrytitle><manvolnum>
  271. 5</manvolnum></citerefentry> for a description of the following attributes:
  272. </para>
  273. <informaltable frame="all" orient="port">
  274. <tgroup cols="2" colsep="1" rowsep="1"><colspec colnum="1" colname="col1"
  275. colwidth="1*" colsep="1" align="left"><colspec colnum="2" colname="col2" colwidth="1*"
  276. align="left">
  277. <thead>
  278. <row><entry colname="col1" align="center" valign="top">ATTRIBUTE TYPE</entry>
  279. <entry colname="col2" align="center" valign="top">ATTRIBUTE VALUE</entry>
  280. </row>
  281. </thead>
  282. <tbody>
  283. <row><entry>Availability</entry><entry>SUNWj3dev</entry></row>
  284. </tbody>
  285. </tgroup>
  286. </informaltable>
  287. </refsect1>
  288. <refsect1><title>&also-tt;</title>
  289. <para><citerefentry><refentrytitle>keytool</refentrytitle><manvolnum>1</manvolnum>
  290. </citerefentry>, <citerefentry><refentrytitle>attributes</refentrytitle><manvolnum>
  291. 5</manvolnum></citerefentry></para>
  292. <variablelist termlength="wholeline">
  293. <varlistentry><term remap="10"><citetitle>JAR Files</citetitle> @</term><listitem>
  294. <para><ulink url="http://java.sun.com/docs/books/tutorial/jar">http://java.sun.com/docs/books/tutorial/jar
  295. </ulink></para>
  296. </listitem></varlistentry>
  297. <varlistentry><term remap="10"><citetitle>JRE Notes</citetitle> @</term><listitem>
  298. <para><ulink url="http://java.sun.com/j2se/1.4/runtime.html#example">http://java.sun.com/j2se/1.4/runtime.html#example
  299. </ulink></para>
  300. </listitem></varlistentry>
  301. <varlistentry><term remap="10"><citetitle>JAR Guide</citetitle> @</term><listitem>
  302. <para><ulink url="http://java.sun.com/j2se/1.4/docs/guide/jar/index.html">
  303. http://java.sun.com/j2se/1.4/docs/guide/jar/index.html</ulink></para>
  304. </listitem></varlistentry>
  305. <varlistentry><term>For information on related topics, use the search link
  306. @</term><listitem><para><ulink url="http://java.sun.com/">http://java.sun.com/
  307. </ulink></para>
  308. </listitem></varlistentry>
  309. </variablelist></refsect1>
  310. <!--+ 07/27/00 08:33:12
  311.     | tagMorph:  $Id: tagMorph-engine 1.54 1998/01/19 05:44:48 $
  312.     | tagMorph library:  $Id: libtagMorph.a 1.50 1998/01/19 22:02:51 $
  313.     | sunman-to-solbook 1.17
  314.     +-->
  315. </refentry>
  316. <?Pub *0000016358>
  317.