نام (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 بگنجانید. عملیات زیر که در بخش تغییردهنده‌های عملیات معتبر فقط در حالت‌های ایجاد و به‌روزرسانی (Operation Modifiers Valid Only in Create and Update Modes) توضیح داده شده‌اند، فقط هنگام ساخت یا به‌روزرسانی یک 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: فایل‌های نام‌برده‌شده (یا همه فایل‌ها) را از بایگانی استخراج می‌کند.

-d یا --describe-module: توصیف‌گر ماژول یا نام ماژول خودکار را چاپ می‌کند.

تغییردهنده‌های عملیات معتبر در هر حالت (OPERATION MODIFIERS VALID IN ANY MODE)

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

-C DIR: به دایرکتوری مشخص‌شده تغییر مسیر می‌دهد و files (فایل‌های) مشخص‌شده در انتهای خط فرمان را شامل می‌شود.

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

-f=FILE یا --file=FILE: نام فایل بایگانی را مشخص می‌کند.

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

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

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

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

-e=CLASSNAME یا --main-class=CLASSNAME: نقطهٔ ورود برنامه را برای برنامه‌های مستقلی که در یک فایل JAR ماژولار یا JAR ماژولار اجرایی بسته‌بندی شده‌اند، مشخص می‌کند.

-m=FILE یا --manifest=FILE: اطلاعات مانیفست را از فایل مانیفست داده‌شده اضافه می‌کند.

-M یا --no-manifest: برای مدخل‌ها فایل مانیفست ایجاد نمی‌کند.

--module-version=VERSION: هنگام ایجاد یا به‌روزرسانی یک فایل JAR ماژولار، یا به‌روزرسانی یک فایل JAR غیرماژولار، نسخهٔ ماژول را تعیین می‌کند.

--hash-modules=PATTERN: هش‌های ماژول‌هایی را که با الگوی داده‌شده مطابقت دارند و به‌طور مستقیم یا غیرمستقیم به فایل JAR ماژولار در حال ایجاد یا فایل JAR غیرماژولار در حال به‌روزرسانی وابسته‌اند، محاسبه و ثبت می‌کند.

-p یا --module-path: مکان وابستگی ماژول را برای تولید هش مشخص می‌کند.

@file: گزینه‌ها و نام‌های فایل دستور jar را از یک فایل متنی می‌خواند، گویی مستقیماً در خط فرمان وارد شده‌اند.

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

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

-0 یا --no-compress: بدون استفاده از فشرده‌سازی ZIP ذخیره می‌کند.

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

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

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

--help-extra: راهنمای مربوط به گزینه‌های اضافی را نمایش می‌دهد.

--version: نسخهٔ برنامه را چاپ می‌کند.

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

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

jar --create --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 را فهرست کند و آن را با پیشوند علامت ات‌ساین (@) به دستور jar ارسال نمایید.

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

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