نام (NAME)

jdeprscan-openjdk21 - ابزار پویش و بررسی استفاده از عناصر منسوخ‌شده در کلاس‌های جاوا در OpenJDK 21

خلاصه دستور (SYNOPSIS)

jdeprscan [گزینه‌ها] {پوشه|فایل_jar|کلاس}

گزینه‌ها: بخش گزینه‌های دستور jdeprscan را ببینید.
پوشه|فایل_jar|کلاس: دستور jdeprscan هر آرگومان را برای یافتن موارد استفاده از APIهای منسوخ‌شده پویش می‌کند. آرگومان‌ها می‌توانند شامل موارد زیر باشند:

•: dir: دایرکتوری یا پوشه
•: jar: فایل JAR
•: class: نام کلاس یا فایل کلاس

در نام کلاس باید از نقطه (.) به عنوان جداکننده استفاده شود. برای نمونه:

java.lang.Thread

برای کلاس‌های تو‌در‌تو، باید از نویسه جداکننده علامت دلار $ استفاده شود. برای نمونه:

java.lang.Thread$State

همچنین می‌توان مسیر فایل کلاس را مشخص کرد. برای نمونه:

build/classes/java/lang/Thread$State.class

توضیحات (DESCRIPTION)

ابزار jdeprscan یک ابزار تحلیل ایستا است که توسط JDK ارائه شده و یک فایل JAR یا هر مجموعه دیگری از فایل‌های کلاس را برای یافتن موارد استفاده از عناصر منسوخ‌شده API پویش می‌کند. APIهای منسوخ‌شده‌ای که توسط ابزار jdeprscan شناسایی می‌شوند، فقط مواردی هستند که توسط Java SE تعریف شده‌اند. APIهای منسوخ‌شده متعلق به کتابخانه‌های شخص ثالث گزارش نمی‌شوند.

برای پویش یک فایل JAR یا مجموعه‌ای از فایل‌های کلاس، ابتدا باید اطمینان حاصل کنید که تمام کلاس‌هایی که کلاس‌های پویش‌شده به آن‌ها وابسته هستند در مسیر کلاس (Class path) موجود باشند. مسیر کلاس را با استفاده از گزینه --class-path که در بخش گزینه‌های دستور jdeprscan شرح داده شده تنظیم کنید. معمولاً از همان مسیر کلاسی استفاده می‌کنید که هنگام اجرای برنامه‌تان به کار می‌برید.

اگر jdeprscan نتواند تمام کلاس‌های وابسته را پیدا کند، برای هر کلاسی که مفقود است یک پیام خطا تولید خواهد کرد. این پیام‌های خطا معمولاً به این صورت هستند:

error: cannot find class ...

در صورت بروز این خطاها، باید مسیر کلاس را به گونه‌ای تنظیم کنید که شامل تمامی کلاس‌های وابسته باشد.

گزینه‌های دستور JDEPRSCAN (OPTIONS FOR THE JDEPRSCAN COMMAND)

گزینه‌های زیر در دسترس هستند:

--class-path مسیر: مسیر جستجو را برای تفکیک و بارگذاری کلاس‌های وابسته فراهم می‌کند.

مسیر می‌تواند یک مسیر جستجو متشکل از یک یا چند دایرکتوری باشد که با جداکننده مسیر مخصوص سیستم‌عامل از هم جدا شده‌اند. برای نمونه:

•: لینوکس و macOS:

--class-path /some/directory:/another/different/dir

نکته:

در ویندوز، به جای دونقطه (:) از نقطه ویرگول (;) به عنوان جداکننده استفاده کنید.

•: ویندوز:

--class-path \some\directory;\another\different\dir

--for-removal: پویش یا فهرست‌کردن را به APIهایی محدود می‌کند که برای حذف منسوخ شده‌اند (Deprecated for removal). نمی‌توان از این گزینه با مقادیر انتشار ۶، ۷ یا ۸ استفاده کرد.
--full-version: رشته نگارش کامل ابزار را چاپ می‌کند.
--help یا -h: پیام راهنمای کامل را چاپ می‌کند.
--list یا -l: مجموعه APIهای منسوخ‌شده را چاپ می‌کند. در این حالت هیچ پویشی انجام نمی‌شود، بنابراین نباید هیچ آرگومانی از نوع دایرکتوری، فایل jar یا کلاس ارائه شود.
--release 6|7|8|9: نگارش Java SE را مشخص می‌کند که مجموعه APIهای منسوخ‌شده را برای پویش فراهم می‌سازد.
--verbose یا -v: چاپ پیام‌های اضافی و با جزئیات را حین پردازش فعال می‌کند.
--version: رشته نگارش خلاصه ابزار را چاپ می‌کند.

نمونه‌ای از خروجی JDEPRSCAN (EXAMPLE OF JDEPRSCAN OUTPUT)

فایل JAR این کتابخانه نامی شبیه به commons-math3-3.6.1.jar خواهد داشت. برای پویش این فایل JAR جهت بررسی استفاده از APIهای منسوخ‌شده، دستور زیر را اجرا کنید:

jdeprscan commons-math3-3.6.1.jar

این دستور چندین خط خروجی تولید می‌کند. برای نمونه، یک خط از خروجی ممکن است به این صورت باشد:


class org/apache/commons/math3/util/MathUtils uses deprecated method java/lang/Double::<init>(D)V

نکته:

نام کلاس با استفاده از نام باینری جداشده با اسلش همان‌طور که در بخش 4.2.1 از JVMS شرح داده شده مشخص شده است. این فرمتی است که به صورت داخلی در فایل‌های کلاس استفاده می‌شود.

API منسوخ‌شده‌ای که استفاده می‌کند متدی در کلاس java.lang.Double است.

نام متد منسوخ‌شده <init> است که یک نام ویژه بوده و نشان می‌دهد که این متد در واقع یک سازنده (Constructor) است. یک نام ویژه دیگر <clinit> است که نشان‌دهنده مقداردهی اولیه ایستا کلاس (Class static initializer) است.

سایر متدها صرفاً با نام متد فهرست می‌شوند. به دنبال نام متد، لیست آرگومان‌ها و نوع بازگشتی درج می‌شود:

(D)V

این عبارت نشان می‌دهد که این متد تنها یک مقدار نوع double (یک داده اولیه) دریافت می‌کند و نوع بازگشتی آن void است. آرگومان‌ها و انواع بازگشتی می‌توانند ساختاری رمزی و مبهم به نظر برسند. برای نمونه، خط دیگری از خروجی ممکن است به این صورت باشد:


class org/apache/commons/math3/util/Precision uses deprecated method java/math/BigDecimal::setScale(II)Ljava/math/BigDecimal;

در این خط خروجی، متد منسوخ‌شده در کلاس java.math.BigDecimal قرار دارد و نام متد setScale() است. در این مورد، عبارت (II) به این معنی است که متد دو آرگومان از نوع int می‌گیرد. عبارت Ljava/math/BigDecimal; پس از پرانتزها به این معنی است که ارجاعی به java.math.BigDecimal را برمی‌گرداند.

تحلیل JDEPRSCAN می‌تواند وابسته به نگارش باشد (JDEPRSCAN ANALYSIS CAN BE VERSION-SPECIFIC)

می‌توانید از jdeprscan نسبت به سه نگارش قبلی JDK استفاده کنید. برای نمونه، اگر JDK 9 را اجرا می‌کنید، می‌توانید در برابر JDK 8، 7 و 6 بررسی را انجام دهید.

به عنوان نمونه، به این قطعه کد نگاه کنید:


public class Deprecations {
   SecurityManager sm = new RMISecurityManager();    // deprecated in 8
   Boolean b2 = new Boolean(true);          // deprecated in 9
}

این کلاس کامل در JDK 7 بدون هیچ هشداری کامپایل می‌شود.

اگر jdeprscan را روی سیستمی با JDK 9 اجرا کنید، خروجی زیر را مشاهده خواهید کرد:


$ jdeprscan --class-path classes --release 7 example.Deprecations
(no output)

دستور jdeprscan را با مقدار انتشار 8 اجرا کنید:


$ 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

دستور jdeprscan را روی JDK 9 اجرا کنید:


$ 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