JAR(1)                           JDK Commands                           JAR(1)

نام (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 با خطا پایان می‌یابد.

JDK 17                               2021                               JAR(1)