jar(1) Basic Tools jar(1)

jar - دستکاری و مدیریت فایل‌های آرشیو جاوا (JAR).

ایجاد فایل JAR

jar c[efmMnv0] [entrypoint] [jarfile] [manifest] [-C dir] file ... [-Joption ...] [@arg-file ...]

به‌روزرسانی فایل JAR

jar u[efmMnv0] [entrypoint] [jarfile] [manifest] [-C dir] file ... [-Joption ...] [@arg-file ...]

استخراج فایل JAR

jar x[vf] [jarfile] file ... [-Joption ...] [@arg-file ...]

فهرست کردن محتویات فایل JAR

jar t[vf] [jarfile] file ... [-Joption ...] [@arg-file ...]

افزودن نمایه (Index) به فایل JAR

jar i jarfile [-Joption ...] [@arg-file ...]

دستور jar یک ابزار همه‌منظوره برای آرشیو و فشرده‌سازی است که بر پایه قالب‌های فشرده‌سازی ZIP و ZLIB طراحی شده است. با این حال، هدف اصلی از طراحی دستور jar، بسته‌بندی اپلت‌ها (applets) یا برنامه‌های کاربردی جاوا در قالب یک آرشیو واحد بوده است. هنگامی که اجزای یک اپلت یا برنامه (فایل‌ها، تصاویر و صداها) در یک آرشیو واحد گرد هم می‌آیند، می‌توانند توسط یک عامل جاوا (مانند یک مرورگر وب) در قالب یک تراکنش واحد HTTP بارگیری شوند، به‌جای آن‌که برای هر قطعه به برقراری یک اتصال جدید نیاز باشد. این امر زمان بارگیری را به‌طور چشمگیری کاهش می‌دهد. همچنین دستور jar فایل‌ها را فشرده می‌کند که این خود باعث بهبود بیشتر زمان بارگیری می‌شود. علاوه‌بر این، دستور jar به پدیدآورنده اپلت امکان می‌دهد که مدخل‌های مجزا در فایل را امضا کند تا هویت و اصالت آن‌ها قابل اعتبارسنجی باشد. یک فایل JAR، صرف‌نظر از اینکه فشرده شده باشد یا خیر، می‌تواند به‌عنوان یک مدخل class path مورد استفاده قرار گیرد.

نحو دستور jar به نحو دستور tar شباهت دارد. این دستور چندین حالت عملیاتی دارد که توسط یکی از آرگومان‌های عملیات اجباری مشخص می‌شوند. سایر آرگومان‌ها یا گزینه‌ها هستند که رفتار عملیات را تغییر می‌دهند، یا عملوندها هستند که برای اجرای عملیات مورد نیازند.

هنگام استفاده از دستور jar، باید با تعیین یکی از آرگومان‌های عملیات زیر، عملیاتی را که مایل به اجرای آن هستید مشخص کنید. می‌توانید آن‌ها را با سایر گزینه‌های تک‌حرفی در خط فرمان ترکیب کنید، اما معمولاً آرگومان عملیات نخستین آرگومانی است که مشخص می‌شود.

یک آرشیو JAR جدید ایجاد می‌کند.
اطلاعات نمایه (index) را برای یک آرشیو JAR تولید می‌کند.
محتویات یک آرشیو JAR را فهرست می‌کند.
یک آرشیو JAR موجود را به‌روزرسانی می‌کند.
فایل‌ها را از یک آرشیو JAR استخراج می‌کند.

از گزینه‌های زیر برای سفارشی‌سازی نحوه ایجاد، به‌روزرسانی، استخراج یا مشاهده فایل JAR استفاده کنید:

کلاس مشخص‌شده توسط عملوند entrypoint را به‌عنوان نقطه ورود (entry point) برنامه مستقل جاوا که درون یک فایل JAR اجرایی بسته‌بندی شده است، تنظیم می‌کند. استفاده از این گزینه، مقدار صفت Main-Class را در فایل مانیفست ایجاد کرده یا آن را بازنویسی می‌کند. گزینه e را می‌توان هنگام ایجاد (c) یا به‌روزرسانی (u) فایل JAR به کار برد.

برای نمونه، دستور زیر آرشیو Main.jar را به همراه فایل Main.class ایجاد می‌کند که در آن مقدار صفت Main-Class در مانیفست بر روی Main تنظیم شده است:

jar cfe Main.jar Main Main.class

محیط زمان اجرای جاوا (JRE) می‌تواند با اجرای دستور زیر مستقیماً این برنامه را فراخوانی کند:

java -jar Main.jar

اگر نام کلاس نقطه ورود درون یک بسته (package) قرار داشته باشد، می‌تواند از نقطه (.) یا اسلش (/) به‌عنوان جداکننده استفاده کند. برای نمونه، اگر Main.class درون بسته‌ای به نام mydir باشد، نقطه ورود را می‌توان به یکی از روش‌های زیر مشخص کرد:

jar -cfe Main.jar mydir/Main mydir/Main.class
jar -cfe Main.jar mydir.Main mydir/Main.class

نکته

مشخص کردن هم‌زمان هر دو گزینه m و e در صورتی که مانیفست مورد نظر از قبل دارای صفت Main-Class باشد، منجر به مشخص‌سازی مبهم Main-Class خواهد شد. این ابهام سبب بروز خطا شده و عملیات ایجاد یا به‌روزرسانی دستور jar متوقف می‌شود.

فایل مشخص‌شده توسط عملوند jarfile را به‌عنوان نام فایل JAR که ایجاد (c)، به‌روزرسانی (u)، استخراج (x) یا مشاهده (t) می‌شود تنظیم می‌کند. نادیده گرفتن گزینه f و عملوند jarfile باعث می‌شود دستور jar نام فایل JAR را از stdin دریافت کند (برای x و t) یا فایل JAR را به stdout بفرستد (برای c و u).
نام‌ها و مقادیر صفت‌ها را از فایلی که با عملوند manifest مشخص شده، در فایل مانیفست دستور jar (واقع در مسیر META-INF/MANIFEST.MF در آرشیو) می‌گنجاند. دستور jar نام و مقدار صفت را به فایل JAR می‌افزاید مگر آن‌که مدخلی با همان نام از پیش موجود باشد؛ در این حالت، دستور jar مقدار صفت را به‌روزرسانی می‌کند. گزینه m می‌تواند هنگام ایجاد (c) یا به‌روزرسانی (u) فایل JAR مورد استفاده قرار گیرد.

می‌توانید جفت‌های صفت نام-مقدار با کاربرد ویژه را که در فایل مانیفست پیش‌فرض وجود ندارند به مانیفست بیفزایید. برای مثال، می‌توانید صفت‌هایی را اضافه کنید که اطلاعات سازنده، اطلاعات نسخه انتشار، مهروموم بسته (package sealing) را مشخص می‌کنند یا برنامه‌های موجود در بسته JAR را قابل اجرا می‌سازند. برای دیدن مثال‌هایی از کاربرد گزینه m، به بخش Packaging Programs در http://docs.oracle.com/javase/tutorial/deployment/jar/index.html مراجعه کنید.

هیچ مدخلی برای فایل مانیفست ایجاد نمی‌کند (برای c و u)، یا در صورت وجود، مدخل فایل مانیفست را حذف می‌کند (برای u). گزینه M می‌تواند هنگام ایجاد (c) یا به‌روزرسانی (u) فایل JAR استفاده شود.
هنگام ایجاد (c) یک فایل JAR، این گزینه آرشیو را نرمال‌سازی می‌کند تا محتوای آن تحت تأثیر عملیات بسته‌بندی و باز کردن دستور pack200(1) قرار نگیرد. بدون این نرمال‌سازی، ممکن است امضای دیجیتال یک JAR امضاشده نامعتبر شود.
خروجی پرگو و مشروح (verbose) در خروجی استاندارد تولید می‌کند. بخش «مثال‌ها» را ببینید.
0
(صفر) فایل JAR را بدون استفاده از فشرده‌سازی ZIP ایجاد (c) یا به‌روزرسانی (u) می‌کند.

هنگام ایجاد (c) یا به‌روزرسانی (u) یک فایل JAR، این گزینه در زمان پردازش فایل‌های تعیین‌شده توسط عملوندهای file، دایرکتوری جاری را به‌طور موقت تغییر می‌دهد. عملکرد آن مشابه گزینه -C در ابزار tar یونیکس است. برای نمونه، دستور زیر مسیر را به دایرکتوری classes تغییر داده و فایل Bar.class را از آن دایرکتوری به my.jar اضافه می‌کند: 
jar uf my.jar -C classes Bar.class

دستور زیر به دایرکتوری classes رفته و تمامی فایل‌های درون آن را به my.jar می‌افزاید (بدون ایجاد دایرکتوری classes در فایل JAR)، سپس پیش از رفتن به دایرکتوری bin برای افزودن Xyz.class به my.jar، به دایرکتوری اولیه بازمی‌گردد.

jar uf my.jar -C classes . -C bin Xyz.class

اگر دایرکتوری classes شامل فایل‌های bar1 و bar2 باشد، پس از اجرای دستور فوق فایل JAR حاوی موارد زیر خواهد بود:

% jar tf my.jar
META-INF/
META-INF/MANIFEST.MF
bar1
bar2
Xyz.class
-Joption گزینه مشخص‌شده JVM را برای استفاده در هنگام اجرای فایل JAR توسط JRE تعیین می‌کند. گزینه‌های JVM در صفحه مرجع دستور java(1) شرح داده شده‌اند. برای نمونه، -J-Xms48m حافظه راه‌اندازی را روی ۴۸ مگابایت تنظیم می‌کند.

عملوندهای زیر توسط دستور jar شناسایی می‌شوند.

هنگام ایجاد (c) یا به‌روزرسانی (u) یک فایل JAR، عملوند file مسیر و نام فایل یا دایرکتوری را که باید به بایگانی افزوده شود، تعیین می‌کند. هنگام استخراج (x) یا فهرست کردن محتویات (t) یک فایل JAR، عملوند file مسیر و نام فایلِ مورد نظر برای استخراج یا فهرست شدن را مشخص می‌کند. حداقل باید یک فایل یا دایرکتوری معتبر مشخص شود. چندین عملوند file را با فاصله از هم جدا کنید. اگر از عملوندهای entrypoint، jarfile یا manifest استفاده شده باشد، عملوندهای file باید پس از آن‌ها مشخص شوند.
هنگام ایجاد (c) یا به‌روزرسانی (u) یک فایل JAR، عملوند entrypoint نام کلاسی را مشخص می‌کند که باید نقطه ورود (entry point) برای یک برنامه مستقل Java بسته‌بندی‌شده در یک فایل JAR اجرایی باشد. اگر گزینه e وجود داشته باشد، تعیین عملوند entrypoint الزامی است.
نام فایلی را مشخص می‌کند که قرار است ایجاد (c)، به‌روزرسانی (u)، استخراج (x) یا مشاهده (t) شود. اگر گزینه f وجود داشته باشد، تعیین عملوند jarfile الزامی است. حذف گزینه f و عملوند jarfile به دستور jar اعلام می‌کند که نام فایل JAR را از stdin دریافت کند (برای x و t) یا فایل JAR را به stdout بفرستد (برای c و u).

هنگام ایندکس‌گذاری (i) یک فایل JAR، عملوند jarfile را بدون گزینه f مشخص کنید.

هنگام ایجاد (c) یا به‌روزرسانی (u) یک فایل JAR، عملوند manifest فایل‌های مانیفست از پیش‌موجود را با نام‌ها و مقادیر مشخصه‌هایی که باید در MANIFEST.MF فایل JAR گنجانده شوند، مشخص می‌کند. اگر گزینه f وجود داشته باشد، تعیین عملوند manifest الزامی است.
@arg-file
برای کوتاه‌تر یا ساده‌تر کردن دستور jar، می‌توانید آرگومان‌ها را در یک فایل متنی جداگانه مشخص کرده و آن را با پیشوند علامت اتساین (@) به دستور jar ارسال کنید. هنگامی که دستور jar با آرگومانی مواجه می‌شود که با علامت اتساین شروع شده است، محتویات آن فایل را به درون فهرست آرگومان‌ها بسط می‌دهد.

یک فایل آرگومان می‌تواند شامل گزینه‌ها و آرگومان‌های دستور jar باشد (به جز گزینه‌های -J، چرا که آن‌ها به اجراکننده منتقل می‌شوند و اجراکننده از فایل‌های آرگومان پشتیبانی نمی‌کند). آرگومان‌های درون فایل می‌توانند با فاصله یا نویسه‌های خط جدید (newline) از هم جدا شوند. نام‌های فایل درون یک فایل آرگومان، نسبت به دایرکتوری جاری که دستور jar را از آن اجرا می‌کنید سنجیده می‌شوند، نه نسبت به مکان قرارگیری فایل آرگومان. نویسه‌های عام (wildcard) مانند ستاره (*)، که در شرایط دیگر ممکن است توسط شل سیستم‌عامل بسط یابند، بسط داده نمی‌شوند.

مثال زیر نشان می‌دهد چگونه می‌توان یک فایل classes.list با نام‌های فایل‌های حاصل از خروجی دستور find در دایرکتوری جاری ایجاد کرد:

find . -name '*.class' -print > classes.list

سپس می‌توانید دستور jar را اجرا کرده و فایل classes.list را با استفاده از ساختار نحوی @arg-file به آن ارسال کنید:

jar cf my.jar @classes.list

فایل آرگومان می‌تواند همراه با یک مسیر مشخص شود، اما هر نام فایلی درون فایل آرگومان که دارای مسیر نسبی است، نسبت به دایرکتوری کاری جاری دستور jar سنجیده می‌شود، نه نسبت به مسیری که به آن داده شده است؛ برای مثال:

jar @dir/classes.list

گزینه‌های e، f و m در خط فرمان باید دقیقاً به همان ترتیبی ظاهر شوند که عملوندهای entrypoint، jarfile و manifest قرار می‌گیرند؛ برای مثال:

jar cmef myManifestFile MyMainClass myFile.jar *.class

مثال ۱ افزودن تمام فایل‌ها از دایرکتوری جاری با خروجی پرجزئیات

% ls
1.au          Animator.class    monkey.jpg
2.au          Wave.class        spacemusic.au
3.au          at_work.gif
% jar cvf bundle.jar *
added manifest
adding: 1.au(in = 2324) (out= 67)(deflated 97%)
adding: 2.au(in = 6970) (out= 90)(deflated 98%)
adding: 3.au(in = 11616) (out= 108)(deflated 99%)
adding: Animator.class(in = 2266) (out= 66)(deflated 97%)
adding: Wave.class(in = 3778) (out= 81)(deflated 97%)
adding: at_work.gif(in = 6621) (out= 89)(deflated 98%)
adding: monkey.jpg(in = 7667) (out= 91)(deflated 98%)
adding: spacemusic.au(in = 3079) (out= 73)(deflated 97%)

مثال ۲ افزودن فایل‌ها از زیردایرکتوری‌ها

% ls -F
audio/ classes/ images/
% jar cvf bundle.jar audio classes images
added manifest
adding: audio/(in = 0) (out= 0)(stored 0%)
adding: audio/1.au(in = 2324) (out= 67)(deflated 97%)
adding: audio/2.au(in = 6970) (out= 90)(deflated 98%)
adding: audio/3.au(in = 11616) (out= 108)(deflated 99%)
adding: audio/spacemusic.au(in = 3079) (out= 73)(deflated 97%)
adding: classes/(in = 0) (out= 0)(stored 0%)
adding: classes/Animator.class(in = 2266) (out= 66)(deflated 97%)
adding: classes/Wave.class(in = 3778) (out= 81)(deflated 97%)
adding: images/(in = 0) (out= 0)(stored 0%)
adding: images/monkey.jpg(in = 7667) (out= 91)(deflated 98%)
adding: images/at_work.gif(in = 6621) (out= 89)(deflated 98%)
% ls -F
audio/ bundle.jar classes/ images/

مثال ۳ فهرست کردن محتویات JAR

% jar tf bundle.jar
META-INF/
META-INF/MANIFEST.MF
audio/1.au
audio/2.au
audio/3.au
audio/spacemusic.au
classes/Animator.class
classes/Wave.class
images/monkey.jpg
images/at_work.gif

مثال ۴ افزودن ایندکس.PP هنگامی که کلاس‌های وابسته به یکدیگر را برای یک برنامه دادوستد سهام به سه فایل JAR تقسیم می‌کنید، از گزینه i استفاده کنید: main.jar، buy.jar، و sell.jar. اگر صفت Class-Path را در مانیفست main.jar مشخص کنید، می‌توانید از گزینه i برای افزایش سرعت بارگذاری کلاس در برنامه خود استفاده کنید:

Class-Path: buy.jar sell.jar
jar i main.jar

یک فایل INDEX.LIST در دایرکتوری META-INF درج می‌شود. این کار به بارگذار کلاس برنامه امکان می‌دهد تا هنگام جستجو به دنبال کلاس‌ها یا منابع، فایل‌های JAR مشخص‌شده را بارگیری کند.

بارگذار کلاس برنامه از اطلاعات ذخیره‌شده در این فایل برای بارگذاری کارآمد کلاس‌ها استفاده می‌کند. برای رونوشت دایرکتوری‌ها، ابتدا فایل‌های موجود در dir1 را به stdout فشرده کرده، سپس از طریق خط لوله، آن‌ها را از stdin در dir2 استخراج کنید (با حذف گزینه -f از هر دو دستور jar):

(cd dir1; jar c .) | (cd dir2; jar x)

•
pack200(1).
•
بخش JAR در The Java Tutorials در http://docs.oracle.com/javase/tutorial/deployment/jar/index.html
21 November 2013 JDK 8