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 ...]

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

jar i jarfile [-Joption ...] [@arg-file ...]
دستور jar یک ابزار همه‌منظوره برای بایگانی و فشرده‌سازی بر پایهٔ ZIP و قالب فشرده‌سازی ZLIB است. با این حال، دستور jar اساساً برای بسته‌بندی اپلت‌ها یا برنامه‌های Java در یک بایگانی واحد طراحی شده است. زمانی که اجزای یک اپلت یا برنامه (فایل‌ها، تصاویر و صداها) در یک بایگانی واحد ترکیب می‌شوند، می‌توانند توسط یک کارگزار Java (مانند یک مرورگر) در یک تراکنش HTTP واحد بارگیری شوند، به‌جای اینکه برای هر قطعه به یک اتصال جدید نیاز باشد. این امر زمان بارگیری را به‌طور چشمگیری بهبود می‌بخشد. دستور jar همچنین فایل‌ها را فشرده می‌کند که این نیز زمان بارگیری را بیش از پیش کاهش می‌دهد. این دستور به نویسندهٔ اپلت امکان می‌دهد که مدخل‌های منفرد فایل را امضا کند تا اصالت مبدأ آن‌ها قابل تأیید باشد. یک فایل JAR، فارغ از اینکه فشرده شده باشد یا نه، می‌تواند به عنوان یک مدخل class path استفاده شود.

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

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

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

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

کلاس مشخص‌شده توسط عملوند entrypoint را به عنوان نقطهٔ ورود (entry point) برای یک برنامهٔ مستقل Java که درون یک فایل 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

اگر نام کلاس نقطهٔ ورود درون یک پکیج باشد، می‌توان از نقطه (.) یا ممیز (/) به عنوان جداکننده استفاده کرد. برای نمونه، اگر 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 به کار برد.

می‌توانید جفت‌های نام-مقدارِ مشخصه با کاربردهای ویژه را که در فایل مانیفست پیش‌فرض وجود ندارند به مانیفست بیفزایید. برای نمونه، می‌توانید مشخصه‌هایی برای تعیین اطلاعات سازنده (vendor)، اطلاعات انتشار، مهروموم کردن پکیج (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، این گزینه بایگانی را عادی‌سازی (normalize) می‌کند تا محتوای آن تحت تأثیر عملیات بسته‌بندی و باز کردنِ دستور pack200(1) قرار نگیرد. بدون این عادی‌سازی، ممکن است امضای یک فایل JAR دارای امضا نامعتبر شود.
خروجی پرگو (verbose) را در خروجی استاندارد تولید می‌کند. بخش «مثال‌ها» را ببینید.
0
(صفر) فایل JAR را بدون استفاده از فشرده‌سازی ZIP ایجاد (c) یا به‌روزرسانی (u) می‌کند.

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

دستور زیر به دایرکتوری classes تغییر مسیر داده و تمام فایل‌های درون آن دایرکتوری را (بدون ایجاد دایرکتوری classes در فایل JAR) به my.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
گزینهٔ مشخص‌شدهٔ JVM را برای استفاده در زمان اجرای فایل JAR توسط JRE تنظیم می‌کند. گزینه‌های JVM در صفحهٔ راهنمای مرجع دستور java(1) شرح داده شده‌اند. برای نمونه، -J-Xms48m مقدار حافظهٔ اولیه هنگام راه‌اندازی را روی 48 مگابایت تنظیم می‌کند..SH "عملوندها (OPERANDS)" عملوندهای زیر توسط دستور jar شناسایی می‌شوند.
هنگام ایجاد (c) یا به‌روزرسانی (u) یک فایل JAR، عملوند file مسیر و نام فایل یا دایرکتوری‌ای را که باید به آرشیو افزوده شود مشخص می‌کند. هنگام استخراج (x) یا فهرست کردن محتویات (t) یک فایل JAR، عملوند file مسیر و نام فایل مورد نظر برای استخراج یا فهرست شدن را مشخص می‌کند. حداقل یک فایل یا دایرکتوری معتبر باید مشخص شود. عملوندهای چندگانهٔ file را با فاصله از هم جدا کنید. در صورت استفاده از عملوندهای entrypoint، jarfile یا manifest، عملوندهای file باید پس از آن‌ها مشخص شوند.
هنگام ایجاد (c) یا به‌روزرسانی (u) یک فایل JAR، عملوند entrypoint نام کلاسی را مشخص می‌کند که باید نقطهٔ ورود برای یک برنامهٔ مستقل 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، زیرا آن‌ها به اجراکننده (launcher) ارسال می‌شوند که از فایل‌های آرگومان پشتیبانی نمی‌کند). آرگومان‌های درون فایل را می‌توان با فاصله یا نویسه‌های خط جدید از یکدیگر جدا کرد. نام‌های فایل درون یک فایل آرگومان نسبت به دایرکتوری جاری که دستور 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

مثال ۴: افزودن یک نمایه

از گزینهٔ i زمانی استفاده کنید که کلاس‌های وابسته به یکدیگر را برای یک برنامهٔ دادوستد سهام به سه فایل JAR تقسیم می‌کنید: 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