.\" Copyright (c) 2017, 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 "JDEPRSCAN" "1" "2023" "JDK 21" "دستورات JDK"
.hy
.SH "نام (NAME)"
.PP
jdeprscan-openjdk21 \- ابزار پویش و بررسی استفاده از عناصر منسوخ‌شده در کلاس‌های جاوا در OpenJDK 21
.SH "خلاصه دستور (SYNOPSIS)"
.PP
\f[V]jdeprscan\f[R] [\f[I]گزینه‌ها\f[R]]
{\f[I]پوشه\f[R]|\f[I]فایل_jar\f[R]|\f[I]کلاس\f[R]}
.TP
\f[I]گزینه‌ها\f[R]
بخش \f[B]گزینه‌های دستور jdeprscan\f[R] را ببینید.
.TP
\f[I]پوشه\f[R]|\f[I]فایل_jar\f[R]|\f[I]کلاس\f[R]
دستور \f[V]jdeprscan\f[R] هر آرگومان را برای یافتن موارد استفاده از APIهای منسوخ‌شده پویش می‌کند.
آرگومان‌ها می‌توانند شامل موارد زیر باشند:
.RS
.IP \[bu] 2
\f[I]dir\f[R]: دایرکتوری یا پوشه
.IP \[bu] 2
\f[I]jar\f[R]: فایل JAR
.IP \[bu] 2
\f[I]class\f[R]: نام کلاس یا فایل کلاس
.PP
در نام کلاس باید از نقطه (\f[V].\f[R]) به عنوان جداکننده استفاده شود.
برای نمونه:
.PP
\f[V]java.lang.Thread\f[R]
.PP
برای کلاس‌های تو‌در‌تو، باید از نویسه جداکننده علامت دلار \f[V]$\f[R] استفاده شود.
برای نمونه:
.PP
\f[V]java.lang.Thread$State\f[R]
.PP
همچنین می‌توان مسیر فایل کلاس را مشخص کرد.
برای نمونه:
.PP
\f[V]build/classes/java/lang/Thread$State.class\f[R]
.RE
.SH "توضیحات (DESCRIPTION)"
.PP
ابزار \f[V]jdeprscan\f[R] یک ابزار تحلیل ایستا است که توسط JDK ارائه شده و یک فایل JAR یا هر مجموعه دیگری از فایل‌های کلاس را برای یافتن موارد استفاده از عناصر منسوخ‌شده API پویش می‌کند.
APIهای منسوخ‌شده‌ای که توسط ابزار \f[V]jdeprscan\f[R] شناسایی می‌شوند، فقط مواردی هستند که توسط Java SE تعریف شده‌اند.
APIهای منسوخ‌شده متعلق به کتابخانه‌های شخص ثالث گزارش نمی‌شوند.
.PP
برای پویش یک فایل JAR یا مجموعه‌ای از فایل‌های کلاس، ابتدا باید اطمینان حاصل کنید که تمام کلاس‌هایی که کلاس‌های پویش‌شده به آن‌ها وابسته هستند در مسیر کلاس (Class path) موجود باشند.
مسیر کلاس را با استفاده از گزینه \f[V]--class-path\f[R] که در بخش \f[B]گزینه‌های دستور jdeprscan\f[R] شرح داده شده تنظیم کنید.
معمولاً از همان مسیر کلاسی استفاده می‌کنید که هنگام اجرای برنامه‌تان به کار می‌برید.
.PP
اگر \f[V]jdeprscan\f[R] نتواند تمام کلاس‌های وابسته را پیدا کند، برای هر کلاسی که مفقود است یک پیام خطا تولید خواهد کرد.
این پیام‌های خطا معمولاً به این صورت هستند:
.RS
.PP
\f[V]error: cannot find class ...\f[R]
.RE
.PP
در صورت بروز این خطاها، باید مسیر کلاس را به گونه‌ای تنظیم کنید که شامل تمامی کلاس‌های وابسته باشد.
.SH "گزینه‌های دستور JDEPRSCAN (OPTIONS FOR THE JDEPRSCAN COMMAND)"
.PP
گزینه‌های زیر در دسترس هستند:
.TP
\f[V]--class-path\f[R] \f[I]مسیر\f[R]
مسیر جستجو را برای تفکیک و بارگذاری کلاس‌های وابسته فراهم می‌کند.
.RS
.PP
\f[I]مسیر\f[R] می‌تواند یک مسیر جستجو متشکل از یک یا چند دایرکتوری باشد که با جداکننده مسیر مخصوص سیستم‌عامل از هم جدا شده‌اند.
برای نمونه:
.IP \[bu] 2
\f[B]لینوکس و macOS:\f[R]
.RS 2
.RS
.PP
\f[V]--class-path /some/directory:/another/different/dir\f[R]
.RE
.RE
.PP
\f[B]نکته:\f[R]
.PP
در ویندوز، به جای دونقطه (\f[V]:\f[R]) از نقطه ویرگول (\f[V];\f[R]) به عنوان جداکننده استفاده کنید.
.IP \[bu] 2
\f[B]ویندوز:\f[R]
.RS 2
.RS
.PP
\f[V]--class-path \[rs]some\[rs]directory;\[rs]another\[rs]different\[rs]dir\f[R]
.RE
.RE
.RE
.TP
\f[V]--for-removal\f[R]
پویش یا فهرست‌کردن را به APIهایی محدود می‌کند که برای حذف منسوخ شده‌اند (Deprecated for removal).
نمی‌توان از این گزینه با مقادیر انتشار ۶، ۷ یا ۸ استفاده کرد.
.TP
\f[V]--full-version\f[R]
رشته نگارش کامل ابزار را چاپ می‌کند.
.TP
\f[V]--help\f[R] یا \f[V]-h\f[R]
پیام راهنمای کامل را چاپ می‌کند.
.TP
\f[V]--list\f[R] یا \f[V]-l\f[R]
مجموعه APIهای منسوخ‌شده را چاپ می‌کند.
در این حالت هیچ پویشی انجام نمی‌شود، بنابراین نباید هیچ آرگومانی از نوع دایرکتوری، فایل jar یا کلاس ارائه شود.
.TP
\f[V]--release\f[R] \f[V]6\f[R]|\f[V]7\f[R]|\f[V]8\f[R]|\f[V]9\f[R]
نگارش Java SE را مشخص می‌کند که مجموعه APIهای منسوخ‌شده را برای پویش فراهم می‌سازد.
.TP
\f[V]--verbose\f[R] یا \f[V]-v\f[R]
چاپ پیام‌های اضافی و با جزئیات را حین پردازش فعال می‌کند.
.TP
\f[V]--version\f[R]
رشته نگارش خلاصه ابزار را چاپ می‌کند.
.SH "نمونه‌ای از خروجی JDEPRSCAN (EXAMPLE OF JDEPRSCAN OUTPUT)"
.PP
فایل JAR این کتابخانه نامی شبیه به \f[V]commons-math3-3.6.1.jar\f[R] خواهد داشت.
برای پویش این فایل JAR جهت بررسی استفاده از APIهای منسوخ‌شده، دستور زیر را اجرا کنید:
.RS
.PP
\f[V]jdeprscan commons-math3-3.6.1.jar\f[R]
.RE
.PP
این دستور چندین خط خروجی تولید می‌کند.
برای نمونه، یک خط از خروجی ممکن است به این صورت باشد:
.IP
.nf
\f[CB]
class org/apache/commons/math3/util/MathUtils uses deprecated method java/lang/Double::<init>(D)V
\f[R]
.fi
.PP
\f[B]نکته:\f[R]
.PP
نام کلاس با استفاده از نام باینری جداشده با اسلش همان‌طور که در بخش 4.2.1 از JVMS شرح داده شده مشخص شده است.
این فرمتی است که به صورت داخلی در فایل‌های کلاس استفاده می‌شود.
.PP
API منسوخ‌شده‌ای که استفاده می‌کند متدی در کلاس \f[V]java.lang.Double\f[R] است.
.PP
نام متد منسوخ‌شده \f[V]<init>\f[R] است که یک نام ویژه بوده و نشان می‌دهد که این متد در واقع یک سازنده (Constructor) است.
یک نام ویژه دیگر \f[V]<clinit>\f[R] است که نشان‌دهنده مقداردهی اولیه ایستا کلاس (Class static initializer) است.
.PP
سایر متدها صرفاً با نام متد فهرست می‌شوند.
به دنبال نام متد، لیست آرگومان‌ها و نوع بازگشتی درج می‌شود:
.RS
.PP
\f[V](D)V\f[R]
.RE
.PP
این عبارت نشان می‌دهد که این متد تنها یک مقدار نوع double (یک داده اولیه) دریافت می‌کند و نوع بازگشتی آن void است.
آرگومان‌ها و انواع بازگشتی می‌توانند ساختاری رمزی و مبهم به نظر برسند.
برای نمونه، خط دیگری از خروجی ممکن است به این صورت باشد:
.IP
.nf
\f[CB]
class org/apache/commons/math3/util/Precision uses deprecated method java/math/BigDecimal::setScale(II)Ljava/math/BigDecimal;
\f[R]
.fi
.PP
در این خط خروجی، متد منسوخ‌شده در کلاس \f[V]java.math.BigDecimal\f[R] قرار دارد و نام متد \f[V]setScale()\f[R] است.
در این مورد، عبارت \f[V](II)\f[R] به این معنی است که متد دو آرگومان از نوع \f[V]int\f[R] می‌گیرد.
عبارت \f[V]Ljava/math/BigDecimal;\f[R] پس از پرانتزها به این معنی است که ارجاعی به \f[V]java.math.BigDecimal\f[R] را برمی‌گرداند.
.SH "تحلیل JDEPRSCAN می‌تواند وابسته به نگارش باشد (JDEPRSCAN ANALYSIS CAN BE VERSION-SPECIFIC)"
.PP
می‌توانید از \f[V]jdeprscan\f[R] نسبت به سه نگارش قبلی JDK استفاده کنید.
برای نمونه، اگر JDK 9 را اجرا می‌کنید، می‌توانید در برابر JDK 8، 7 و 6 بررسی را انجام دهید.
.PP
به عنوان نمونه، به این قطعه کد نگاه کنید:
.IP
.nf
\f[CB]
public class Deprecations {
   SecurityManager sm = new RMISecurityManager();    // deprecated in 8
   Boolean b2 = new Boolean(true);          // deprecated in 9
}
\f[R]
.fi
.PP
این کلاس کامل در JDK 7 بدون هیچ هشداری کامپایل می‌شود.
.PP
اگر \f[V]jdeprscan\f[R] را روی سیستمی با JDK 9 اجرا کنید، خروجی زیر را مشاهده خواهید کرد:
.IP
.nf
\f[CB]
$ jdeprscan --class-path classes --release 7 example.Deprecations
(no output)
\f[R]
.fi
.PP
دستور \f[V]jdeprscan\f[R] را با مقدار انتشار 8 اجرا کنید:
.IP
.nf
\f[CB]
$ jdeprscan --class-path classes --release 8 example.Deprecations
class example/Deprecations uses type java/rmi/RMISecurityManager deprecated
class example/Deprecations uses method in type java/rmi/RMISecurityManager deprecated
\f[R]
.fi
.PP
دستور \f[V]jdeprscan\f[R] را روی JDK 9 اجرا کنید:
.IP
.nf
\f[CB]
$ jdeprscan --class-path classes example.Deprecations
class example/Deprecations uses type java/rmi/RMISecurityManager deprecated
class example/Deprecations uses method in type java/rmi/RMISecurityManager deprecated
class example/Deprecations uses method java/lang/Boolean <init> (Z)V deprecated
\f[R]
.fi