ScopedValue

القيم محدودة النطاق (Scoped Values) ScopedValue

منذ Java 25 (JEP 506)، ScopedValue حاوية غير قابلة للتغيير لمشاركة بيانات ضمن نطاق استدعاء محدد — بديل أخف وأأمن من ThreadLocal، مصمم للعمل مع الخيوط الافتراضية.

ThreadLocal أداة قديمة لمشاركة بيانات دون تمريرها كمعامل لكل دالة، لكنها تحتاج نسخة كاملة لكل خيط وتنظيفًا يدويًا عبر remove() قد يُنسى فيسرّب بيانات قديمة. مع ملايين الخيوط الافتراضية المحتملة، هذا يتضخّم.

ScopedValue حاوية غير قابلة للتغيير (immutable) مرئية فقط ضمن نطاق ديناميكي محدد: الدالة التي تربط القيمة عبر where().run()، وكل ما تستدعيه من دوال أو خيوط فرعية تنشئها، ثم تختفي القيمة تلقائيًا عند الخروج من ذلك النطاق — بلا remove() وبلا نسيان تنظيف. الخيوط الافتراضية الفرعية ترث الربط تلقائيًا بلا تكلفة نسخ إضافية.

الصياغة

static final ScopedValue<T> V = ScopedValue.newInstance();

ScopedValue.where(V, قيمة).run(() -> {
    // V.get() متاحة هنا فقط
});

📄 مثال

public class Example {
    private static final ScopedValue<String> USER_ID = ScopedValue.newInstance();

    public static void main(String[] args) {
        ScopedValue.where(USER_ID, "user-42").run(() -> {
            greet(); // داخل النطاق
        });
        // هنا USER_ID.get() ترمي IllegalStateException
    }

    private static void greet() {
        System.out.println("أهلًا، المستخدم: " + USER_ID.get());
    }
}

أهم النقاط

العنصر	الوظيفة
ScopedValue.newInstance()	ينشئ حاوية فارغة — عادة static final على مستوى الصنف
where(V, x).run(task)	يربط القيمة x بالحاوية V وينفّذ task بهذا الربط فعّالًا
V.get()	يقرأ القيمة الحالية — يعمل فقط داخل run المطابق
V.isBound()	يفحص هل القيمة مربوطة حاليًا قبل استدعاء get() لتجنّب الاستثناء

💡 نصائح عملية

استخدمها للبيانات التي تُحدَّد مرة وتُقرأ فقط ضمن سلسلة استدعاء واحدة (سياق طلب، معرّف مستخدم)
الخيوط الافتراضية الفرعية ترث الربط تلقائيًا — لا حاجة لتمريره يدويًا

⚠️ أخطاء شائعة

استدعاء get() خارج نطاق run() المطابق — يرمي IllegalStateException
محاولة تعديل القيمة بعد الربط — ScopedValue غير قابلة للتغيير، ليست بديلًا لمتغيّر عادي يحتاج تحديثًا متكررًا

🎓 تريد فهم الصورة الكاملة خطوة بخطوة؟ ابدأ من مسار JAVA الكامل بالعربي.