نام (NAME)

jar - ایجاد بایگانی برای کلاس‌ها و منابع، و دستکاری یا بازیابی کلاس‌ها یا منابع منفرد از یک بایگانی

خلاصه دستور (SYNOPSIS)

jar [OPTION ...] [ [--release VERSION] [-C dir] files] ...

توضیحات (DESCRIPTION)

دستور jar یک ابزار چندمنظوره برای بایگانی و فشرده‌سازی بر پایه قالب‌های فشرده‌سازی ZIP و ZLIB است. در ابتدا، دستور jar برای بسته‌بندی اپلت‌های جاوا (که از JDK 11 به بعد پشتیبانی نمی‌شوند) یا برنامه‌ها طراحی شده بود؛ با این حال، از JDK 9 به بعد، کاربران می‌توانند از دستور jar برای ایجاد JARهای ماژولار استفاده کنند. برای جابه‌جایی و استقرار، معمولاً بسته‌بندی ماژول‌ها به‌صورت JARهای ماژولار راحت‌تر است.

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

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

یک بایگانی زمانی به یک JAR ماژولار تبدیل می‌شود که توصیف‌کننده ماژول، یعنی module-info.class را در ریشه دایرکتوری‌های ارائه‌شده یا در ریشه بایگانی .jar قرار دهید. عملیات زیر که در بخش اصلاح‌کننده‌های عملیاتی معتبر فقط در حالت‌های ایجاد و به‌روزرسانی شرح داده شده‌اند، تنها هنگام ایجاد یا به‌روزرسانی یک jar ماژولار یا به‌روزرسانی یک jar غیرماژولار موجود معتبر هستند:

--module-version
--hash-modules
--module-path

نکته:

تمام آرگومان‌های اجباری یا اختیاری برای گزینه‌های طولانی، برای هر یک از گزینه‌های کوتاه متناظر نیز اجباری یا اختیاری هستند.

حالت‌های عملیاتی اصلی (MAIN OPERATION MODES)

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

-c یا --create: بایگانی را ایجاد می‌کند.
-i FILE یا --generate-index=FILE: اطلاعات نمایه (index) را برای فایل JAR مشخص‌شده تولید می‌کند. این گزینه منسوخ شده است و ممکن است در نسخه‌های بعدی حذف شود.
-t یا --list: فهرست محتویات بایگانی را نمایش می‌دهد.
-u یا --update: یک فایل JAR موجود را به‌روزرسانی می‌کند.
-x یا --extract: فایل‌های نام‌برده‌شده (یا همه فایل‌ها) را از بایگانی استخراج می‌کند. اگر فایلی با نام یکسان بیش از یک بار در بایگانی ظاهر شود، هر نسخه استخراج خواهد شد و نسخه‌های بعدی جایگزین نسخه‌های قبلی می‌شوند (رونویسی می‌شوند)، مگر اینکه -k مشخص شده باشد.
-d یا --describe-module: توصیف‌کننده ماژول یا نام خودکار ماژول را چاپ می‌کند.
--validate: محتویات فایل JAR را اعتبارسنجی می‌کند. برای جزئیات بیشتر، بخش Integrity of a JAR File را در زیر ببینید..SH "اصلاح‌کننده‌های عملیات معتبر در هر حالت (OPERATION MODIFIERS VALID IN ANY MODE)" می‌توانید از گزینه‌های زیر برای سفارشی‌سازی عملکرد هر یک از حالت‌های عملیاتی موجود در دستور jar استفاده کنید.
-C DIR: هنگامی که همراه با حالت عملیاتی ایجاد (create) استفاده می‌شود، به دایرکتوری مشخص‌شده تغییر مسیر داده و files (فایل‌های) مشخص‌شده در انتهای خط فرمان را شامل می‌شود.

jar [OPTION ...] [ [--release VERSION] [-C dir] files] هنگامی که با حالت عملیاتی استخراج (extract) استفاده شود، دایرکتوری مقصدی را مشخص می‌کند که فایل JAR در آن استخراج خواهد شد. برخلاف حالت عملیاتی create، این گزینه در حالت عملیاتی extract تنها یک‌بار می‌تواند مشخص شود.

-f FILE یا --file=FILE: نام فایل آرشیو را مشخص می‌کند.
--release VERSION: یک فایل JAR چندنسخه‌ای (multirelease) ایجاد می‌کند. تمام فایل‌های مشخص‌شده پس از این گزینه را در دایرکتوری نسخه‌بندی‌شده‌ای از فایل JAR با نام META-INF/versions/VERSION/ قرار می‌دهد؛ که در آن VERSION باید یک عدد صحیح مثبت با مقدار ۹ یا بزرگ‌تر باشد.

در زمان اجرا، هنگامی که بیش از یک نسخه از یک کلاس در JAR وجود داشته باشد، JDK از نخستین نسخه‌ای که پیدا کند استفاده خواهد کرد؛ به این ترتیب که ابتدا در درخت دایرکتوری‌ای جستجو می‌کند که شمارهٔ VERSION آن با شمارهٔ نسخهٔ اصلی (major version) مربوط به JDK مطابقت داشته باشد. سپس دایرکتوری‌هایی با شماره‌های VERSION به‌طور متوالی کمتر را بررسی کرده و در نهایت ریشهٔ فایل JAR را بررسی می‌کند.

-v یا --verbose: خروجی پرجزئیات را به خروجی استاندارد ارسال کرده یا چاپ می‌کند.

اصلاح‌کننده‌های عملیات معتبر تنها در حالت‌های CREATE و UPDATE (OPERATION MODIFIERS VALID ONLY IN CREATE AND UPDATE MODES)

می‌توانید از گزینه‌های زیر برای سفارشی‌سازی عملکرد حالت‌های عملیاتی اصلی create و update استفاده کنید:

-e CLASSNAME یا --main-class=CLASSNAME: نقطهٔ ورود برنامه (entry point) را برای برنامه‌های مستقلی که در یک فایل JAR پیمانه‌ای یا پیمانه‌ایِ قابل‌اجرا بسته‌بندی شده‌اند، مشخص می‌کند.
-m FILE یا --manifest=FILE: اطلاعات مانیفست را از فایل مانیفست داده‌شده در بر می‌گیرد.
-M یا --no-manifest: فایل مانیفست را برای مدخل‌ها ایجاد نمی‌کند.
--module-version=VERSION: هنگام ایجاد یا به‌روزرسانی یک فایل JAR پیمانه‌ای، یا به‌روزرسانی یک فایل JAR غیرپیمانه‌ای، نسخهٔ ماژول را مشخص می‌کند.
--hash-modules=PATTERN: هش‌های ماژول‌هایی را که با الگوی داده‌شده مطابقت دارند و به‌طور مستقیم یا غیرمستقیم به فایل JAR پیمانه‌ایِ در حال ایجاد یا فایل JAR غیرپیمانه‌ایِ در حال به‌روزرسانی وابسته هستند، محاسبه و ثبت می‌کند.
-p یا --module-path: مکان وابستگی ماژول را برای تولید هش مشخص می‌کند.
@file: گزینه‌ها و نام‌های فایل‌های jar را از یک فایل متنی می‌خواند، دقیقاً مانند اینکه در خط فرمان وارد شده باشند.

اصلاح‌کننده‌های عملیات معتبر تنها در حالت‌های CREATE، UPDATE و GENERATE-INDEX (OPERATION MODIFIERS VALID ONLY IN CREATE, UPDATE, AND GENERATE-INDEX MODES)

می‌توانید از گزینه‌های زیر برای سفارشی‌سازی عملکرد حالت‌های عملیاتی اصلی create (-c یا --create)، update (-u یا --update) و generate-index (-i یا --generate-index=FILE) استفاده کنید:

-0 یا --no-compress: بدون استفاده از فشرده‌سازی ZIP ذخیره می‌کند.
--date=TIMESTAMP: برچسب زمانی در قالب تاریخ-زمان با افست گسترش‌یافته بر اساس ISO-8601 همراه با منطقهٔ زمانی اختیاری، برای استفاده به عنوان برچسب زمانی مدخل‌ها؛ مانند: "2022-02-12T12:30:00-05:00"..SH "اصلاح‌کننده‌های عملیات فقط در حالت استخراج (OPERATION MODIFIERS VALID ONLY IN EXTRACT MODE)"
--dir DIR: دایرکتوری که فایل JAR در آن استخراج خواهد شد.
-k یا --keep-old-files: فایل‌های موجود را رونویسی نمی‌کند. اگر مدخلی با نام یکسان در فایل JAR در دایرکتوری مقصد وجود داشته باشد، فایل موجود رونویسی نخواهد شد. در نتیجه، اگر یک فایل بیش از یک بار در یک بایگانی ظاهر شود، نسخه‌های بعدی نسخه‌های قبلی را رونویسی نمی‌کنند. همچنین توجه داشته باشید که برخی از فایل‌سیستم‌ها ممکن است به کوچک و بزرگی حروف حساس نباشند.

سایر گزینه‌ها (OTHER OPTIONS)

گزینه‌های زیر توسط دستور jar شناسایی شده و همراه با حالت‌های عملیاتی به کار نمی‌روند:

-h یا --help[:compat]: راهنمای خط فرمان را برای دستور jar یا به صورت اختیاری راهنمای سازگاری را نمایش می‌دهد.
--help-extra: راهنمای مربوط به گزینه‌های اضافی را نمایش می‌دهد.
--version: نسخه برنامه را چاپ می‌کند.

یکپارچگی یک فایل JAR (INTEGRITY OF A JAR FILE)

از آنجا که یک فایل JAR بر پایه قالب ZIP است، امکان ساخت یک فایل JAR با ابزارهایی غیر از دستور jar نیز وجود دارد. گزینه --validate می‌تواند برای انجام بررسی‌های یکپارچگی زیر روی یک فایل JAR استفاده شود:

عدم وجود نام فایل‌های تکراری در میان مدخل‌های Zip
تأیید اینکه نام مدخل Zip:

یک مسیر مطلق نباشد
نام فایل '.' یا '..' نباشد
شامل یک بک‌اسلش، '\' نباشد
شامل حرف درایو نباشد
بخش مسیر شامل '.' یا '.. نباشد

•: واسط برنامه‌نویسی کاربردی (API) ارائه‌شده توسط یک بایگانی jar چندنسخه‌ای در میان تمام نسخه‌های مختلف انتشار سازگار باشد.

ابزار jar در صورتی که با هیچ مشکل یکپارچگی مواجه نشود با وضعیت 0 و در صورت بروز خطا/هشدار با وضعیتی بزرگتر از صفر (>0) خارج می‌شود.

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

مثال‌هایی از نحو دستور JAR (EXAMPLES OF JAR COMMAND SYNTAX)

•: ساخت یک بایگانی به نام classes.jar که شامل دو فایل کلاس Foo.class و Bar.class است.

jar --create --file classes.jar Foo.class Bar.class

•: ساخت یک بایگانی به نام classes.jar شامل دو فایل کلاس Foo.class و Bar.class همراه با تنظیم تاریخ و زمان آخرین تغییر روی 2021 Jan 6 12:36:00.

jar --create --date="2021-01-06T14:36:00+02:00" --file=classes.jar Foo.class Bar.class

•: ساخت یک بایگانی به نام classes.jar با استفاده از یک مانیفست موجود به نام mymanifest که شامل تمام فایل‌های موجود در دایرکتوری foo/ است.

jar --create --file classes.jar --manifest mymanifest -C foo/

•: ساخت یک بایگانی JAR ماژولار به نام foo.jar که در آن توصیف‌کننده ماژول در classes/module-info.class قرار دارد.

jar --create --file foo.jar --main-class com.foo.Main --module-version 1.0 -C foo/classes resources

•: به‌روزرسانی یک JAR غیرماژولار موجود به نام foo.jar به یک فایل JAR ماژولار.

jar --update --file foo.jar --main-class com.foo.Main --module-version 1.0 -C foo/module-info.class

•: ساخت یک JAR چندنسخه‌ای (multi-release) به نام foo.jar که فایل‌های موجود در دایرکتوری classes را در ریشه JAR و فایل‌های موجود در دایرکتوری classes-10 را در دایرکتوری META-INF/versions/10 مربوط به JAR قرار می‌دهد.

در این مثال، دایرکتوری classes/com/foo شامل دو کلاس است: com.foo.Hello (کلاس نقطه ورود) و com.foo.NameProvider که هر دو برای JDK 8 کامپایل شده‌اند. دایرکتوری classes-10/com/foo شامل نسخه متفاوتی از کلاس com.foo.NameProvider است؛ این نسخه شامل کدهای اختصاصی JDK 10 بوده و برای JDK 10 کامپایل شده است.

با در نظر گرفتن این پیکربندی، با اجرای دستور زیر از دایرکتوری حاوی دایرکتوری‌های classes و classes-10، فایل JAR چندنسخه‌ای foo.jar را ایجاد کنید.

jar --create --file foo.jar --main-class com.foo.Hello -C classes . --release 10 -C classes-10 .

فایل JAR با نام foo.jar اکنون شامل این موارد است:

% jar -tf foo.jar
META-INF/
META-INF/MANIFEST.MF
com/
com/foo/
com/foo/Hello.class
com/foo/NameProvider.class
META-INF/versions/10/com/
META-INF/versions/10/com/foo/
META-INF/versions/10/com/foo/NameProvider.class

علاوه بر سایر اطلاعات، فایل META-INF/MANIFEST.MF شامل خطوط زیر خواهد بود تا نشان دهد که این یک فایل JAR چندنسخه‌ای با نقطه ورود com.foo.Hello است.

...
Main-Class: com.foo.Hello
Multi-Release: true

با فرض اینکه کلاس com.foo.Hello متدی را روی کلاس com.foo.NameProvider فراخوانی می‌کند، اجرای برنامه با استفاده از JDK 10 تضمین خواهد کرد که کلاس com.foo.NameProvider نسخه موجود در META-INF/versions/10/com/foo/ خواهد بود. اجرای برنامه با استفاده از JDK 8 تضمین می‌کند که کلاس com.foo.NameProvider نسخه موجود در ریشه JAR، در com/foo خواهد بود.

•: ساخت یک بایگانی به نام my.jar با خواندن گزینه‌ها و فهرست فایل‌های کلاس از فایل classes.list.

نکته:

برای کوتاه‌تر کردن یا ساده‌سازی دستور jar، می‌توانید یک فایل آرگومان فراهم کنید که فایل‌های مورد نظر برای قرار گرفتن در فایل JAR را فهرست کند و آن را با علامت ات‌ساین (@) به عنوان پیشوند به دستور jar ارسال نمایید.

jar --create --file my.jar @classes.list

اگر یک یا چند مدخل در فایل آرگومان پیدا نشود، دستور jar بدون ساخت فایل JAR با شکست مواجه می‌شود.

•: استخراج فایل JAR به نام foo.jar در دایرکتوری /tmp/bar/:

jar -xf foo.jar -C /tmp/bar/

به‌عنوان روش جایگزین، می‌توانید این کار را نیز انجام دهید:

jar --extract --file foo.jar --dir /tmp/bar/