.\" Copyright (c) 1997, 2023, 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.19.2
.\"
.\" Define V font for inline verbatim, using C font in formats
.\" that render this, and otherwise B font.
.ie "\f[CB]x\f[R]"x" \{\
. ftr V B
. ftr VI BI
. ftr VB B
. ftr VBI BI
.\}
.el \{\
. ftr V CR
. ftr VI CI
. ftr VB CB
. ftr VBI CBI
.\}
.TH "JAR" "1" "2023" "JDK 21" "دستورات JDK"
.hy
.SH "نام (NAME)"
.PP
jar \- ابزار ایجاد، مشاهده و مدیریت بسته‌های آرشیو JAR در OpenJDK 21
.SH "خلاصه دستور (SYNOPSIS)"
.PP
\f[V]jar\f[R] [\f[I]OPTION\f[R] ...]
[ [\f[V]--release\f[R] \f[I]VERSION\f[R]] [\f[V]-C\f[R] \f[I]dir\f[R]]
\f[I]files\f[R]] ...
.SH "توضیحات (DESCRIPTION)"
.PP
دستور \f[V]jar\f[R] یک ابزار چندمنظوره برای بایگانی و فشرده‌سازی بر پایه قالب‌های فشرده‌سازی ZIP و ZLIB است.
در ابتدا، دستور \f[V]jar\f[R] برای بسته‌بندی اپلت‌های جاوا (که از JDK 11 به بعد پشتیبانی نمی‌شوند) یا برنامه‌های کاربردی طراحی شده بود؛ با این حال، از JDK 9 به بعد، کاربران می‌توانند از دستور \f[V]jar\f[R] برای ایجاد فایل‌های JAR ماژولار استفاده کنند.
برای جابه‌جایی و استقرار، معمولاً بسته‌بندی ماژول‌ها به‌صورت JARهای ماژولار راحت‌تر است.
.PP
نحو دستور \f[V]jar\f[R] شبیه به نحو دستور \f[V]tar\f[R] است.
این دستور دارای چندین حالت عملیاتی اصلی است که با یکی از آرگومان‌های اجباری عملیات مشخص می‌شوند.
سایر آرگومان‌ها یا گزینه‌هایی هستند که رفتار عملیات را تغییر می‌دهند، یا برای انجام آن عملیات مورد نیازند.
.PP
هنگامی که ماژول‌ها یا اجزای یک برنامه (فایل‌ها، تصاویر و صداها) در یک آرشیو واحد ترکیب می‌شوند، یک عامل جاوا (مانند مرورگر) می‌تواند آن‌ها را در یک تراکنش HTTP واحد بارگیری کند، به‌جای اینکه برای هر قطعه به اتصال جدیدی نیاز باشد.
این کار زمان بارگیری را به‌طور چشمگیری بهبود می‌بخشد.
دستور \f[V]jar\f[R] همچنین فایل‌ها را فشرده می‌کند که زمان بارگیری را باز هم کاهش می‌دهد.
دستور \f[V]jar\f[R] امکان امضای ورودی‌های منفرد در یک فایل را نیز فراهم می‌سازد تا اصالت منبع آن‌ها قابل تأیید باشد.
یک فایل JAR می‌تواند چه فشرده باشد و چه نباشد، به‌عنوان یک ورودی در class path استفاده شود.
.PP
هنگامی که یک توصیف‌گر ماژول، یعنی \f[V]module-info.class\f[R] را در ریشه پوشه‌های داده‌شده یا در ریشه آرشیو \f[V].jar\f[R] قرار دهید، آن آرشیو به یک JAR ماژولار تبدیل می‌شود.
عملیات‌های زیر که در \f[B]تغییردهنده‌های عملیات معتبر فقط در حالت‌های ایجاد و به‌روزرسانی\f[R] شرح داده شده‌اند، فقط هنگام ایجاد یا به‌روزرسانی یک jar ماژولار یا به‌روزرسانی یک jar غیرماژولار موجود معتبر هستند:
.IP \[bu] 2
\f[V]--module-version\f[R]
.IP \[bu] 2
\f[V]--hash-modules\f[R]
.IP \[bu] 2
\f[V]--module-path\f[R]
.PP
\f[B]نکته:\f[R]
.PP
تمام آرگومان‌های اجباری یا اختیاری برای گزینه‌های بلند، برای گزینه‌های کوتاه متناظر آن‌ها نیز اجباری یا اختیاری هستند.
.SH "حالت‌های اصلی عملیات (MAIN OPERATION MODES)"
.PP
هنگام استفاده از دستور \f[V]jar\f[R]، باید عملیاتی را که می‌خواهید اجرا شود مشخص کنید.
حالت عملیات دستور \f[V]jar\f[R] را با درج آرگومان‌های عملیاتی مناسب شرح‌داده‌شده در این بخش تعیین می‌کنید.
می‌توانید یک آرگومان عملیاتی را با سایر گزینه‌های تک‌حرفی ترکیب کنید.
معمولاً آرگومان عملیات اولین آرگومان مشخص‌شده در خط فرمان است.
.TP
\f[V]-c\f[R] یا \f[V]--create\f[R]
آرشیو را ایجاد می‌کند.
.TP
\f[V]-i\f[R] \f[I]FILE\f[R] یا \f[V]--generate-index=\f[R]\f[I]FILE\f[R]
اطلاعات ایندکس را برای فایل JAR مشخص‌شده تولید می‌کند.
این گزینه منسوخ شده است و ممکن است در نسخه‌های آینده حذف شود.
.TP
\f[V]-t\f[R] یا \f[V]--list\f[R]
فهرست محتویات آرشیو را نمایش می‌دهد.
.TP
\f[V]-u\f[R] یا \f[V]--update\f[R]
یک فایل JAR موجود را به‌روزرسانی می‌کند.
.TP
\f[V]-x\f[R] یا \f[V]--extract\f[R]
فایل‌های نام‌برده‌شده (یا تمام فایل‌ها) را از آرشیو استخراج می‌کند.
.TP
\f[V]-d\f[R] یا \f[V]--describe-module\f[R]
توصیف‌گر ماژول یا نام ماژول خودکار را چاپ می‌کند.
.SH "تغییردهنده‌های عملیات معتبر در هر حالتی (OPERATION MODIFIERS VALID IN ANY MODE)"
.PP
می‌توانید از گزینه‌های زیر برای سفارشی‌سازی رفتارهای هر یک از حالت‌های عملیاتی دستور \f[V]jar\f[R] استفاده کنید.
.TP
\f[V]-C\f[R] \f[I]DIR\f[R]
پوشه مشخص‌شده را تغییر می‌دهد و \f[I]فایل‌ها\f[R]ی مشخص‌شده در انتهای خط فرمان را شامل می‌کند.
.RS
.PP
\f[V]jar\f[R] [\f[I]OPTION\f[R] ...]
[ [\f[V]--release\f[R] \f[I]VERSION\f[R]] [\f[V]-C\f[R] \f[I]dir\f[R]]
\f[I]files\f[R]]
.RE
.TP
\f[V]-f\f[R] \f[I]FILE\f[R] یا \f[V]--file=\f[R]\f[I]FILE\f[R]
نام فایل آرشیو را مشخص می‌کند.
.TP
\f[V]--release\f[R] \f[I]VERSION\f[R]
یک فایل JAR چندنسخه‌ای (multirelease) ایجاد می‌کند.
تمام فایل‌های مشخص‌شده پس از این گزینه را در یک پوشه نسخه‌بندی‌شده از فایل JAR به نام
\f[V]META-INF/versions/\f[R]\f[I]VERSION\f[R]\f[V]/\f[R] قرار می‌دهد، که در آن \f[I]VERSION\f[R] باید یک عدد صحیح مثبت بزرگتر یا مساوی ۹ باشد.
.RS
.PP
در زمان اجرا، اگر بیش از یک نسخه از یک کلاس در JAR وجود داشته باشد، JDK اولین نسخه‌ای را که پیدا کند استفاده خواهد کرد؛ بدین صورت که ابتدا در ساختار پوشه‌ای که شماره \f[I]VERSION\f[R] آن با شماره نسخه اصلی JDK مطابقت دارد جستجو می‌کند.
سپس پوشه‌های دارای شماره‌های \f[I]VERSION\f[R] پایین‌تر را بررسی می‌کند و در نهایت ریشه فایل JAR را می‌جوید.
.RE
.TP
\f[V]-v\f[R] یا \f[V]--verbose\f[R]
خروجی مشروح را به خروجی استاندارد ارسال کرده یا چاپ می‌کند.
.SH "تغییردهنده‌های عملیات معتبر فقط در حالت‌های ایجاد و به‌روزرسانی (OPERATION MODIFIERS VALID ONLY IN CREATE AND UPDATE MODES)"
.PP
می‌توانید از گزینه‌های زیر برای سفارشی‌سازی رفتارهای حالت‌های اصلی ایجاد (create) و به‌روزرسانی (update) استفاده کنید:
.TP
\f[V]-e\f[R] \f[I]CLASSNAME\f[R] یا \f[V]--main-class=\f[R]\f[I]CLASSNAME\f[R]
نقطه ورود برنامه را برای برنامه‌های مستقلی که در یک فایل JAR ماژولار یا اجرایی بسته‌بندی شده‌اند مشخص می‌کند.
.TP
\f[V]-m\f[R] \f[I]FILE\f[R] یا \f[V]--manifest=\f[R]\f[I]FILE\f[R]
اطلاعات مانیفست را از فایل مانیفست داده‌شده در آرشیو می‌گنجاند.
.TP
\f[V]-M\f[R] یا \f[V]--no-manifest\f[R]
فایل مانیفست برای ورودی‌ها ایجاد نمی‌کند.
.TP
\f[V]--module-version=\f[R]\f[I]VERSION\f[R]
نسخه ماژول را هنگام ایجاد یا به‌روزرسانی فایل JAR ماژولار یا به‌روزرسانی فایل JAR غیرماژولار تعیین می‌کند.
.TP
\f[V]--hash-modules=\f[R]\f[I]PATTERN\f[R]
هش ماژول‌هایی را که با الگوی داده‌شده مطابقت دارند و به‌طور مستقیم یا غیرمستقیم به فایل JAR ماژولار در حال ایجاد یا فایل JAR غیرماژولار در حال به‌روزرسانی وابسته هستند، محاسبه و ثبت می‌کند.
.TP
\f[V]-p\f[R] یا \f[V]--module-path\f[R]
مسیر وابستگی‌های ماژول را برای تولید هش مشخص می‌کند.
.TP
\f[V]\[at]\f[R]\f[I]file\f[R]
گزینه‌ها و نام فایل‌های \f[V]jar\f[R] را از یک فایل متنی می‌خواند، گویی که مستقیماً در خط فرمان وارد شده‌اند.
.SH "تغییردهنده‌های عملیات معتبر در حالت‌های ایجاد، به‌روزرسانی و تولید ایندکس (OPERATION MODIFIERS VALID ONLY IN CREATE, UPDATE, AND GENERATE-INDEX MODES)"
.PP
می‌توانید از گزینه‌های زیر برای سفارشی‌سازی رفتارهای حالت‌های اصلی ایجاد (\f[V]-c\f[R] یا \f[V]--create\f[R])، به‌روزرسانی (\f[V]-u\f[R] یا \f[V]--update\f[R]) و تولید ایندکس (\f[V]-i\f[R] یا \f[V]--generate-index=\f[R]\f[I]FILE\f[R]) استفاده کنید:
.TP
\f[V]-0\f[R] یا \f[V]--no-compress\f[R]
فایل‌ها را بدون استفاده از فشرده‌سازی ZIP ذخیره می‌کند.
.TP
\f[V]--date=\f[R]\f[I]TIMESTAMP\f[R]
برچسب زمانی در قالب تاریخ-زمان گسترش‌یافته ISO-8601 همراه با منطقه زمانی اختیاری برای استفاده در تاریخ ورودی‌ها، مانند \[dq]2022-02-12T12:30:00-05:00\[dq].
.SH "سایر گزینه‌ها (OTHER OPTIONS)"
.PP
گزینه‌های زیر توسط دستور \f[V]jar\f[R] شناخته می‌شوند و همراه با حالت‌های عملیاتی به کار نمی‌روند:
.TP
\f[V]-h\f[R] یا \f[V]--help\f[R][\f[V]:compat\f[R]]
راهنمای خط فرمان برای دستور \f[V]jar\f[R] یا به‌صورت اختیاری راهنمای سازگاری را نمایش می‌دهد.
.TP
\f[V]--help-extra\f[R]
راهنما درباره گزینه‌های اضافی را نمایش می‌دهد.
.TP
\f[V]--version\f[R]
نسخه برنامه را چاپ می‌کند.
.SH "مثال‌هایی از نحو دستور JAR (EXAMPLES OF JAR COMMAND SYNTAX)"
.IP \[bu] 2
ایجاد یک آرشیو به نام \f[V]classes.jar\f[R] که شامل دو فایل کلاس \f[V]Foo.class\f[R] و \f[V]Bar.class\f[R] است:
.RS 2
.RS
.PP
\f[V]jar --create --file classes.jar Foo.class Bar.class\f[R]
.RE
.RE
.IP \[bu] 2
ایجاد یک آرشیو به نام \f[V]classes.jar\f[R] که شامل دو فایل کلاس \f[V]Foo.class\f[R] و \f[V]Bar.class\f[R] بوده و تاریخ و زمان آخرین تغییر آن روی \f[V]2021 Jan 6 12:36:00\f[R] تنظیم شده است:
.RS 2
.RS
.PP
\f[V]jar --create --date=\[dq]2021-01-06T14:36:00+02:00\[dq] --file=classes.jar Foo.class Bar.class\f[R]
.RE
.RE
.IP \[bu] 2
ایجاد یک آرشیو به نام \f[V]classes.jar\f[R] با استفاده از یک مانیفست موجود به نام \f[V]mymanifest\f[R] که شامل تمامی فایل‌های درون پوشه \f[V]foo/\f[R] است:
.RS 2
.RS
.PP
\f[V]jar --create --file classes.jar --manifest mymanifest -C foo/\f[R]
.RE
.RE
.IP \[bu] 2
ایجاد یک آرشیو JAR ماژولار به نام \f[V]foo.jar\f[R] که در آن توصیف‌گر ماژول در مسیر \f[V]classes/module-info.class\f[R] قرار دارد:
.RS 2
.RS
.PP
\f[V]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[V]foo.jar\f[R] به یک فایل JAR ماژولار:
.RS 2
.RS
.PP
\f[V]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 چندنسخه‌ای به نام \f[V]foo.jar\f[R] که فایل‌های موجود در پوشه \f[V]classes\f[R] را در ریشه JAR و فایل‌های موجود در پوشه \f[V]classes-10\f[R] را در پوشه \f[V]META-INF/versions/10\f[R] از JAR قرار می‌دهد:
.RS 2
.PP
در این مثال، پوشه \f[V]classes/com/foo\f[R] شامل دو کلاس \f[V]com.foo.Hello\f[R] (کلاس نقطه ورود) و \f[V]com.foo.NameProvider\f[R] است که هر دو برای JDK 8 کامپایل شده‌اند.
پوشه \f[V]classes-10/com/foo\f[R] شامل نسخه متفاوتی از کلاس \f[V]com.foo.NameProvider\f[R] است که شامل کدهای مخصوص JDK 10 بوده و برای JDK 10 کامپایل شده است.
.PP
با این ساختار، فایل JAR چندنسخه‌ای \f[V]foo.jar\f[R] را با اجرای دستور زیر از داخل پوشه‌ای که حاوی پوشه‌های \f[V]classes\f[R] و \f[V]classes-10\f[R] است ایجاد کنید:
.RS
.PP
\f[V]jar --create --file foo.jar --main-class com.foo.Hello -C classes . --release 10 -C classes-10 .\f[R]
.RE
.PP
اکنون فایل JAR به نام \f[V]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[V]META-INF/MANIFEST.MF\f[R] شامل خطوط زیر خواهد بود تا نشان دهد این یک فایل JAR چندنسخه‌ای با نقطه ورود \f[V]com.foo.Hello\f[R] است:
.IP
.nf
\f[CB]
\&...
Main-Class: com.foo.Hello
Multi-Release: true
\f[R]
.fi
.PP
با فرض اینکه کلاس \f[V]com.foo.Hello\f[R] متدی از کلاس \f[V]com.foo.NameProvider\f[R] را فراخوانی کند، اجرای برنامه با استفاده از JDK 10 تضمین می‌کند که کلاس \f[V]com.foo.NameProvider\f[R] همان نسخه موجود در \f[V]META-INF/versions/10/com/foo/\f[R] باشد.
اجرای برنامه با استفاده از JDK 8 نیز تضمین می‌کند که کلاس \f[V]com.foo.NameProvider\f[R] همان نسخه موجود در ریشه JAR در مسیر \f[V]com/foo\f[R] باشد.
.RE
.IP \[bu] 2
ایجاد یک آرشیو به نام \f[V]my.jar\f[R] با خواندن گزینه‌ها و فهرست فایل‌های کلاس از فایل \f[V]classes.list\f[R]:
.RS 2
.PP
\f[B]نکته:\f[R]
.PP
برای کوتاه کردن یا ساده‌سازی دستور \f[V]jar\f[R]، می‌توانید یک فایل آرگومان (arg file) شامل فهرست فایل‌های مورد نظر برای گنجاندن در JAR ایجاد کرده و آن را با علامت اتساین (\f[V]\[at]\f[R]) به‌عنوان پیشوند به دستور \f[V]jar\f[R] ارسال کنید.
.RS
.PP
\f[V]jar --create --file my.jar \[at]classes.list\f[R]
.RE
.PP
اگر یک یا چند ورودی مشخص‌شده در فایل آرگومان پیدا نشود، دستور jar بدون ایجاد فایل JAR با خطا مواجه می‌شود.
.RE