.\" Copyright (c) 1997, 2018, Oracle and/or its affiliates. All rights reserved.
.\" DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
.\"
.\" This code is free software; you can redistribute it and/or modify it
.\" under the terms of the GNU General Public License version 2 only, as
.\" published by the Free Software Foundation.
.\"
.\" This code is distributed in the hope that it will be useful, but WITHOUT
.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
.\" FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
.\" version 2 for more details (a copy is included in the LICENSE file that
.\" accompanied this code).
.\"
.\" You should have received a copy of the GNU General Public License version
.\" 2 along with this work; if not, write to the Free Software Foundation,
.\" Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
.\"
.\" Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
.\" or visit www.oracle.com if you need additional information or have any
.\" questions.
.\"
.\" Automatically generated by Pandoc 2.3.1
.\"
.TH "JAR" "1" "2021" "JDK 17" "JDK Commands"
.hy
.SH "نام (NAME)"
.PP
jar \- ایجاد یک بایگانی برای کلاس‌ها و منابع، و دستکاری یا بازیابی کلاس‌ها یا منابع منفرد از یک بایگانی
.SH "خلاصه دستور (SYNOPSIS)"
.PP
\f[CB]jar\f[R] [\f[I]OPTION\f[R] ...] [ [\f[CB]\-\-release\f[R]
\f[I]VERSION\f[R]] [\f[CB]\-C\f[R] \f[I]dir\f[R]] \f[I]files\f[R]] ...
.SH "توضیحات (DESCRIPTION)"
.PP
دستور \f[CB]jar\f[R] یک ابزار چندمنظوره برای بایگانی و فشرده‌سازی بر پایه
قالب‌های فشرده‌سازی ZIP و ZLIB است.
در ابتدا، دستور \f[CB]jar\f[R] برای بسته‌بندی اپلت‌های جاوا (که از JDK 11
به بعد دیگر پشتیبانی نمی‌شوند) یا برنامه‌های کاربردی طراحی شده بود؛ با این
حال، با شروع از JDK 9، کاربران می‌توانند از دستور \f[CB]jar\f[R] برای ایجاد
JARهای ماژولار استفاده کنند.
برای انتقال و استقرار، معمولاً بسته‌بندی ماژول‌ها به صورت JARهای ماژولار
راحت‌تر است.
.PP
ساختار دستور \f[CB]jar\f[R] شبیه به ساختار دستور \f[CB]tar\f[R] است.
این دستور چندین حالت عملیاتی اصلی دارد که با یکی از آرگومان‌های عملیاتی
اجباری مشخص می‌شوند.
سایر آرگومان‌ها یا گزینه‌هایی هستند که رفتار عملیات را تغییر می‌دهند یا برای
انجام عملیات الزامی هستند.
.PP
هنگامی که ماژول‌ها یا اجزای یک برنامه (فایل‌ها، تصاویر و صداها) در یک
بایگانی واحد ترکیب می‌شوند، می‌توانند توسط یک عامل جاوا (مانند یک مرورگر)
در یک تراکنش HTTP منفرد بارگیری شوند، به جای اینکه برای هر قطعه به یک اتصال
جدید نیاز باشد.
این کار زمان بارگیری را به طور چشمگیری بهبود می‌بخشد.
همچنین دستور \f[CB]jar\f[R] فایل‌ها را فشرده می‌کند که این امر زمان بارگیری
را بیش از پیش کاهش می‌دهد.
دستور \f[CB]jar\f[R] علاوه بر این امکان امضا کردن مدخل‌های منفرد در یک فایل
را فراهم می‌کند تا اصالت مبدأ آن‌ها قابل اعتبارسنجی باشد.
یک فایل JAR می‌تواند، چه فشرده شده باشد یا نباشد، به عنوان یک مدخل class
path استفاده شود.
.PP
یک بایگانی زمانی به یک JAR ماژولار تبدیل می‌شود که توصیف‌گر ماژول، یعنی
\f[CB]module\-info.class\f[R]، را در ریشه دایرکتوری‌های داده‌شده یا در ریشه
بایگانی \f[CB]\&.jar\f[R] بگنجانید.
عملیات زیر که در بخش \f[B]تغییردهنده‌های عملیات معتبر فقط در حالت‌های ایجاد
و به‌روزرسانی (Operation Modifiers Valid Only in Create and Update Modes)\f[R]
توضیح داده شده‌اند، فقط هنگام ساخت یا به‌روزرسانی یک jar ماژولار یا به‌روزرسانی
یک jar غیرماژولار موجود معتبر هستند:
.IP \[bu] 2
\f[CB]\-\-module\-version\f[R]
.IP \[bu] 2
\f[CB]\-\-hash\-modules\f[R]
.IP \[bu] 2
\f[CB]\-\-module\-path\f[R]
.PP
\f[B]نکته:\f[R]
.PP
تمام آرگومان‌های اجباری یا اختیاری برای گزینه‌های طولانی، برای هر گزینه کوتاه
متناظر با آن‌ها نیز اجباری یا اختیاری هستند.
.SH "حالت‌های اصلی عملیات (MAIN OPERATION MODES)"
.PP
هنگام استفاده از دستور \f[CB]jar\f[R]، باید عملیاتی را که قصد انجام آن را
دارد مشخص کنید.
شما حالت عملیاتی دستور \f[CB]jar\f[R] را با درج آرگومان‌های عملیاتی مناسب که
در این بخش شرح داده شده‌اند تعیین می‌کنید.
می‌توانید یک آرگومان عملیاتی را با سایر گزینه‌های تک‌حرفی ترکیب کنید.
به طور کلی آرگومان عملیاتی نخستین آرگومانی است که در خط فرمان مشخص می‌شود.
.TP
.B \f[CB]\-c\f[R] یا \f[CB]\-\-create\f[R]
بایگانی را ایجاد می‌کند.
.RS
.RE
.TP
.B \f[CB]\-i=\f[R]\f[I]FILE\f[R] یا \f[CB]\-\-generate\-index=\f[R]\f[I]FILE\f[R]
اطلاعات نمایه (index) را برای فایل JAR مشخص‌شده تولید می‌کند.
.RS
.RE
.TP
.B \f[CB]\-t\f[R] یا \f[CB]\-\-list\f[R]
فهرست محتویات بایگانی را نمایش می‌دهد.
.RS
.RE
.TP
.B \f[CB]\-u\f[R] یا \f[CB]\-\-update\f[R]
یک فایل JAR موجود را به‌روزرسانی می‌کند.
.RS
.RE
.TP
.B \f[CB]\-x\f[R] یا \f[CB]\-\-extract\f[R]
فایل‌های نام‌برده‌شده (یا همه فایل‌ها) را از بایگانی استخراج می‌کند.
.RS
.RE
.TP
.B \f[CB]\-d\f[R] یا \f[CB]\-\-describe\-module\f[R]
توصیف‌گر ماژول یا نام ماژول خودکار را چاپ می‌کند.
.RS
.RE
.SH "تغییردهنده‌های عملیات معتبر در هر حالت (OPERATION MODIFIERS VALID IN ANY MODE)"
.PP
می‌توانید از گزینه‌های زیر برای سفارشی‌سازی عملکردهای هر حالت عملیاتی موجود
در دستور \f[CB]jar\f[R] استفاده کنید.
.TP
.B \f[CB]\-C\f[R] \f[I]DIR\f[R]
به دایرکتوری مشخص‌شده تغییر مسیر می‌دهد و \f[I]files\f[R] (فایل‌های)
مشخص‌شده در انتهای خط فرمان را شامل می‌شود.
.RS
.PP
\f[CB]jar\f[R] [\f[I]OPTION\f[R] ...] [ [\f[CB]\-\-release\f[R]
\f[I]VERSION\f[R]] [\f[CB]\-C\f[R] \f[I]dir\f[R]] \f[I]files\f[R]]
.RE
.TP
.B \f[CB]\-f=\f[R]\f[I]FILE\f[R] یا \f[CB]\-\-file=\f[R]\f[I]FILE\f[R]
نام فایل بایگانی را مشخص می‌کند.
.RS
.RE
.TP
.B \f[CB]\-\-release\f[R] \f[I]VERSION\f[R]
یک فایل JAR چندنسخه‌ای (multirelease) ایجاد می‌کند.
تمام فایل‌های مشخص‌شده پس از این گزینه را درون یک دایرکتوری نسخه‌بندی‌شده از
فایل JAR به نام
\f[CB]META\-INF/versions/\f[R]\f[I]VERSION\f[R]\f[CB]/\f[R] قرار می‌دهد،
که در آن \f[I]VERSION\f[R] باید یک عدد صحیح مثبت با مقدار ۹ یا بزرگتر باشد.
.RS
.PP
در زمان اجرا، چنانچه بیش از یک نسخه از یک کلاس در JAR وجود داشته باشد، JDK
از نخستین نسخه‌ای که پیدا کند استفاده خواهد کرد؛ به این صورت که ابتدا در درخت
دایرکتوری‌ای جستجو می‌کند که شماره \f[I]VERSION\f[R] آن با شماره نسخه اصلی
(major version) مربوط به JDK مطابقت داشته باشد.
سپس دایرکتوری‌هایی با شماره‌های \f[I]VERSION\f[R] به ترتیب کمتر را بررسی
می‌کند و در نهایت به ریشه فایل JAR نگاه خواهد انداخت.
.RE
.TP
.B \f[CB]\-v\f[R] یا \f[CB]\-\-verbose\f[R]
خروجی پرگو (verbose) را به خروجی استاندارد ارسال کرده یا چاپ می‌کند.
.RS
.RE.SH "اصلاح‌کننده‌های عملیات معتبر فقط در حالت‌های ایجاد و به‌روزرسانی (OPERATION MODIFIERS VALID ONLY IN CREATE AND UPDATE MODES)"
.PP
می‌توانید از گزینه‌های زیر برای سفارشی‌سازی عملکردهای حالت‌های عملیاتی اصلی ایجاد (create) و به‌روزرسانی (update) استفاده کنید:
.TP
.B \f[CB]\-e=\f[R]\f[I]CLASSNAME\f[R] یا \f[CB]\-\-main\-class=\f[R]\f[I]CLASSNAME\f[R]
نقطهٔ ورود برنامه را برای برنامه‌های مستقلی که در یک فایل JAR ماژولار یا JAR ماژولار اجرایی بسته‌بندی شده‌اند، مشخص می‌کند.
.RS
.RE
.TP
.B \f[CB]\-m=\f[R]\f[I]FILE\f[R] یا \f[CB]\-\-manifest=\f[R]\f[I]FILE\f[R]
اطلاعات مانیفست را از فایل مانیفست داده‌شده اضافه می‌کند.
.RS
.RE
.TP
.B \f[CB]\-M\f[R] یا \f[CB]\-\-no\-manifest\f[R]
برای مدخل‌ها فایل مانیفست ایجاد نمی‌کند.
.RS
.RE
.TP
.B \f[CB]\-\-module\-version=\f[R]\f[I]VERSION\f[R]
هنگام ایجاد یا به‌روزرسانی یک فایل JAR ماژولار، یا به‌روزرسانی یک فایل JAR غیرماژولار، نسخهٔ ماژول را تعیین می‌کند.
.RS
.RE
.TP
.B \f[CB]\-\-hash\-modules=\f[R]\f[I]PATTERN\f[R]
هش‌های ماژول‌هایی را که با الگوی داده‌شده مطابقت دارند و به‌طور مستقیم یا غیرمستقیم به فایل JAR ماژولار در حال ایجاد یا فایل JAR غیرماژولار در حال به‌روزرسانی وابسته‌اند، محاسبه و ثبت می‌کند.
.RS
.RE
.TP
.B \f[CB]\-p\f[R] یا \f[CB]\-\-module\-path\f[R]
مکان وابستگی ماژول را برای تولید هش مشخص می‌کند.
.RS
.RE
.TP
.B \f[CB]\@\f[R]\f[I]file\f[R]
گزینه‌ها و نام‌های فایل دستور \f[CB]jar\f[R] را از یک فایل متنی می‌خواند، گویی مستقیماً در خط فرمان وارد شده‌اند.
.RS
.RE
.SH "اصلاح‌کننده‌های عملیات معتبر فقط در حالت‌های ایجاد، به‌روزرسانی و تولید فهرست (OPERATION MODIFIERS VALID ONLY IN CREATE, UPDATE, AND GENERATE-INDEX MODES)"
.PP
می‌توانید از گزینه‌های زیر برای سفارشی‌سازی عملکردهای حالت‌های عملیاتی اصلی ایجاد (\f[CB]\-c\f[R] یا \f[CB]\-\-create\f[R])، به‌روزرسانی (\f[CB]\-u\f[R] یا \f[CB]\-\-update\f[R]) و تولید فهرست (\f[CB]\-i\f[R] یا \f[CB]\-\-generate\-index=\f[R]\f[I]FILE\f[R]) استفاده کنید:
.TP
.B \f[CB]\-0\f[R] یا \f[CB]\-\-no\-compress\f[R]
بدون استفاده از فشرده‌سازی ZIP ذخیره می‌کند.
.RS
.RE
.SH "سایر گزینه‌ها (OTHER OPTIONS)"
.PP
گزینه‌های زیر توسط دستور \f[CB]jar\f[R] شناخته می‌شوند و در حالت‌های عملیاتی استفاده نمی‌شوند:
.TP
.B \f[CB]\-h\f[R] یا \f[CB]\-\-help\f[R][\f[CB]:compat\f[R]]
راهنمای خط فرمان را برای دستور \f[CB]jar\f[R] یا به صورت اختیاری راهنمای سازگاری را نمایش می‌دهد.
.RS
.RE
.TP
.B \f[CB]\-\-help\-extra\f[R]
راهنمای مربوط به گزینه‌های اضافی را نمایش می‌دهد.
.RS
.RE
.TP
.B \f[CB]\-\-version\f[R]
نسخهٔ برنامه را چاپ می‌کند.
.RS
.RE
.SH "مثال‌هایی از نحو دستور JAR (EXAMPLES OF JAR COMMAND SYNTAX)"
.IP \[bu] 2
ایجاد یک بایگانی با نام \f[CB]classes.jar\f[R] که شامل دو فایل کلاس \f[CB]Foo.class\f[R] و \f[CB]Bar.class\f[R] است.
.RS 2
.RS
.PP
\f[CB]jar\ \-\-create\ \-\-file\ classes.jar\ Foo.class\ Bar.class\f[R]
.RE
.RE
.IP \[bu] 2
ایجاد یک بایگانی با نام \f[CB]classes.jar\f[R] با استفاده از یک مانیفست موجود به نام \f[CB]mymanifest\f[R] که شامل تمام فایل‌های دایرکتوری \f[CB]foo/\f[R] است.
.RS 2
.RS
.PP
\f[CB]jar\ \-\-create\ \-\-file\ classes.jar\ \-\-manifest\ mymanifest\ \-C\ foo/\f[R]
.RE
.RE
.IP \[bu] 2
ایجاد یک بایگانی JAR ماژولار به نام \f[CB]foo.jar\f[R] که در آن توصیف‌گر ماژول در \f[CB]classes/module\-info.class\f[R] قرار دارد.
.RS 2
.RS
.PP
\f[CB]jar\ \-\-create\ \-\-file\ foo.jar\ \-\-main\-class\ com.foo.Main\ \-\-module\-version\ 1.0\ \-C\ foo/classes\ resources\f[R]
.RE
.RE
.IP \[bu] 2
به‌روزرسانی یک فایل JAR غیرماژولار موجود با نام \f[CB]foo.jar\f[R] به یک فایل JAR ماژولار.
.RS 2
.RS
.PP
\f[CB]jar\ \-\-update\ \-\-file\ foo.jar\ \-\-main\-class\ com.foo.Main\ \-\-module\-version\ 1.0\ \-C\ foo/module\-info.class\f[R]
.RE
.RE
.IP \[bu] 2
ایجاد یک JAR نسخه‌دار یا چندنسخه‌ای (multi-release) با نام \f[CB]foo.jar\f[R] که فایل‌های موجود در دایرکتوری \f[CB]classes\f[R] را در ریشهٔ فایل JAR، و فایل‌های موجود در دایرکتوری \f[CB]classes\-10\f[R] را در دایرکتوری \f[CB]META\-INF/versions/10\f[R] فایل JAR قرار می‌دهد.
.RS 2
.PP
در این مثال، دایرکتوری \f[CB]classes/com/foo\f[R] شامل دو کلاس است: \f[CB]com.foo.Hello\f[R] (کلاس نقطهٔ ورود) و \f[CB]com.foo.NameProvider\f[R]، که هر دو برای JDK 8 کامپایل شده‌اند.
دایرکتوری \f[CB]classes\-10/com/foo\f[R] شامل نسخهٔ متفاوتی از کلاس \f[CB]com.foo.NameProvider\f[R] است؛ این نسخه شامل کدهای مخصوص JDK 10 بوده و برای JDK 10 کامپایل شده است.
.PP
با فرض این ساختار، با اجرای دستور زیر از دایرکتوریِ حاوی پوشه‌های \f[CB]classes\f[R] و \f[CB]classes\-10\f[R]، یک فایل JAR چندنسخه‌ای به نام \f[CB]foo.jar\f[R] ایجاد کنید.
.RS
.PP
\f[CB]jar\ \-\-create\ \-\-file\ foo.jar\ \-\-main\-class\ com.foo.Hello\ \-C\ classes\ .\ \-\-release\ 10\ \-C\ classes\-10\ .\f[R]
.RE
.PP
فایل JAR به نام \f[CB]foo.jar\f[R] اکنون حاوی موارد زیر است:
.IP
.nf
\f[CB]
%\ 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
\f[R]
.fi
.PP
علاوه بر سایر اطلاعات، فایل \f[CB]META\-INF/MANIFEST.MF\f[R] شامل خطوط زیر خواهد بود که نشان می‌دهد این فایل یک JAR چندنسخه‌ای با نقطهٔ ورود \f[CB]com.foo.Hello\f[R] است.
.IP
.nf
\f[CB]
\&...
Main\-Class:\ com.foo.Hello
Multi\-Release:\ true
\f[R]
.fi
.PP
با فرض اینکه کلاس \f[CB]com.foo.Hello\f[R] متدی از کلاس \f[CB]com.foo.NameProvider\f[R] را فراخوانی می‌کند، اجرای برنامه با استفاده از JDK 10 تضمین می‌کند که کلاس \f[CB]com.foo.NameProvider\f[R] همان نسخهٔ موجود در \f[CB]META\-INF/versions/10/com/foo/\f[R] خواهد بود.
اجرای برنامه با استفاده از JDK 8 تضمین می‌کند که کلاس \f[CB]com.foo.NameProvider\f[R] همان نسخهٔ واقع در ریشهٔ فایل JAR، در \f[CB]com/foo\f[R] خواهد بود.
.RE
.IP \[bu] 2
ایجاد یک بایگانی به نام \f[CB]my.jar\f[R] از طریق خواندن گزینه‌ها و فهرست فایل‌های کلاس از فایل \f[CB]classes.list\f[R].
.RS 2
.PP
\f[B]نکته:\f[R]
.PP
برای کوتاه یا ساده‌تر کردن دستور \f[CB]jar\f[R]، می‌توانید آرگومان‌ها را در یک فایل متنی جداگانه مشخص کرده و آن را با پیشوند علامت ات‌ساین (\f[CB]\@\f[R]) به دستور \f[CB]jar\f[R] ارسال کنید.

برای کوتاه یا ساده‌تر کردن دستور \f[CB]jar\f[R]، می‌توانید یک فایل آرگومان ارائه دهید که فایل‌های مورد نظر برای قرار گرفتن در فایل JAR را فهرست کند و آن را با پیشوند علامت ات‌ساین (\f[CB]\@\f[R]) به دستور \f[CB]jar\f[R] ارسال نمایید.
.RS
.PP
\f[CB]jar\ \-\-create\ \-\-file\ my.jar\ \@classes.list\f[R]
.RE
.PP
اگر یک یا چند مدخل در فایل آرگومان پیدا نشود، دستور \f[CB]jar\f[R] بدون ایجاد فایل JAR با خطا پایان می‌یابد.
.RE