ایجاد Interceptor

اولین مثال عملی که اجرا خواهیم کرد، طراحی یک سیستم ساده Interception برای متدهای Service است. این سیستمی است که در Java EE، Jakarta EE و سایر Framework های کاربردی سازمانی وجود دارد. مفهوم ساده است: یک Annotation روی یک متود اضافه می‌کنید، این Annotation یک کلاس به‌عنوان ویژگی (Attribute) می‌گیرد و به‌جای متود Service شما، متود خاصی از آن کلاس فراخوانی می‌شود.

Interceptor چیست؟

مفهوم قطع (Intercept) یک فراخوانی متود بسیار ساده است. بر دو عنصر تکیه دارد: یک Service که دارای یک متود Service است و یک Interceptor که آن نیز یک متود دارد. وقتی متود Service خود را فراخوانی می‌کنید، آنچه می‌خواهید این است که به‌جای آن، متود Interceptor فراخوانی شود.

سپس این متود می‌تواند کارهای مختلفی انجام دهد:

• می‌تواند آرگومان‌های ارسال‌شده به متود Service شما را اعتبارسنجی (Validate) کند.
• می‌تواند این آرگومان‌ها را تغییر دهد.
• علاوه بر اعتبارسنجی، می‌تواند قوانین امنیتی خاصی را اعمال کند.
• می‌تواند تصمیم بگیرد متود Service شما را فراخوانی کند یا نه.
• می‌تواند نتیجه متود Service را دریافت کرده و تصمیم بگیرد آن را همان‌طور برگرداند یا تغییر دهد.
• و می‌تواند Exception های پرتاب‌شده توسط متود Service شما را دریافت کرده و بر اساس آن‌ها عمل کند.

این نوع Interceptor را می‌توان با استفاده از اشیاء Proxy پیاده‌سازی کرد، که خارج از محدوده این فصل است. پس این قابلیت را به شکل ساده‌تری پیاده‌سازی خواهیم کرد.

طراحی Interface و Annotation برای Intercept

بیایید با Annotation مورد نیاز شروع کنیم. این Annotation باید مشخص کند چه کلاس Interceptor‌ای استفاده شود. برای سادگی، فرض می‌کنیم Interceptor ها یک Interface خاص را پیاده‌سازی می‌کنند.

توجه کنید این Interface از Type های پارامتریک (Parameterized Types) برای شیء Intercept شده و Type بازگشتی متود Intercept شده استفاده می‌کند:

public interface Interceptor<T, R> {
    R intercept(T interceptedObject, Method method, Object... arguments);
}

سپس Annotation مورد نیاز را طراحی کنید:

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface Intercept {
    Class<? extends Interceptor<?, ?>> value();
}

طراحی یک Service و متود Intercept شده

بیایید یک Service با متودی که باید Intercept شود ایجاد کنیم:

public class SomeInterceptedService {
    
    @Intercept(MessageInterceptor.class)
    public String message(String input) {
        return input.toUpperCase();
    }
}

با نوشتن این کد، انتظار دارید:

1. روشی برای فراخوانی متود message() کلاس SomeInterceptedService داشته باشید.
2. وقتی آن را فراخوانی می‌کنید، پیاده‌سازی متود intercept() کلاس MessageInterceptor قبل از فراخوانی متود message() اجرا شود.
3. سپس نتیجه این فراخوانی را دریافت کنید.

کد شما می‌تواند به این شکل باشد:

void main() {
    String output = ServiceFactory.invoke(SomeInterceptedService.class, "message", "Hello");
    IO.println("output = " + output);
}

نوشتن کلاس MessageInterceptor

این کلاس پیاده‌سازی Interface Interceptor است و مسئولیت تصمیم‌گیری برای فراخوانی یا عدم فراخوانی Service Intercept شده را دارد.

سه عنصر برای فراخوانی Reflective این متود لازم است:

1. خود متود، به‌صورت یک شیء Method
2. شیئی که این متود روی آن فراخوانی می‌شود — یعنی Service شما
3. آرگومان‌هایی که باید به این متود پاس دهید

در اینجا ابتدا اعتبارسنجی آرگومان‌ها انجام می‌شود. اگر آرگومان‌ها شامل دقیقاً یک عنصر String نباشند، Exception پرتاب شده و متود Intercept شده فراخوانی نمی‌شود. سپس متود Intercept شده فراخوانی شده و نتیجه با پیام [was intercepted] ترکیب می‌شود:

public class MessageInterceptor implements Interceptor<SomeInterceptedService, String> {

    @Override
    public String intercept(
            SomeInterceptedService service, Method interceptedMethod, Object... arguments) {
        try {
            if (arguments.length == 1) {
                
                // validating the arguments
                String input = (String) arguments[0];
                Objects.requireNonNull(input, "Input is null");
                if (input.isEmpty()) {
                    throw new IllegalArgumentException("Input is empty");
                }
                
                // calling the service method
                String result = (String)interceptedMethod.invoke(service, arguments);
                return result + " [was intercepted]";
            }
        } catch (IllegalAccessException | InvocationTargetException e) {
            throw new RuntimeException(e);
        }
        throw new IllegalArgumentException(
                "Arguments should contain exactly one argument of type String");
    }
}

نوشتن کلاس ServiceFactory

این کلاس فنی‌تر است و از Reflection API بهره می‌برد.

کلاسی که متود روی آن اعلام شده، نام متود Intercept شده و آرگومان‌ها را دریافت می‌کند. مراحل کار به این صورت است:

1. ابتدا یک نمونه از Service ایجاد می‌شود. این کار از طریق دریافت Constructor بدون پارامتر انجام می‌شود.
2. سپس متود مورد نظر شناسایی می‌شود. برای این کار به دو عنصر نیاز است: نام متود و Type های پارامترها به‌صورت آرایه.
3. در ادامه بررسی می‌شود آیا Annotation روی این متود وجود دارد. اگر وجود دارد، نمونه Annotation دریافت شده و متود value() آن فراخوانی می‌شود تا کلاس Interceptor بازگردانده شود.
4. نمونه Interceptor ایجاد شده و متود intercept() آن فراخوانی می‌شود.

اگر Annotation یافت نشود، متود Service به‌صورت Reflective و بدون Interception فراخوانی می‌شود:

public class ServiceFactory {
    public static <T, R> R invoke(
            Class<? extends T> serviceClass, String methodName, Object... arguments) {
        try {
            // Getting an instance of the service
            T service = serviceClass.getConstructor().newInstance();
            
            // Locating the service method
            Class<?>[] parameterClasses =
                    Arrays.stream(arguments).map(Object::getClass).toArray(Class<?>[]::new);
            Method method = serviceClass.getDeclaredMethod(methodName, parameterClasses);
            
            // locating the Intercept annotation
            if (method.isAnnotationPresent(Intercept.class)) {
                Intercept intercept = method.getDeclaredAnnotation(Intercept.class);
                Class<? extends Interceptor<T, R>> interceptorClass =
                        (Class<? extends Interceptor<T, R>>) intercept.value();
                
                // creating an instance of the interceptor
                Interceptor<T, R> interceptor = interceptorClass.getConstructor().newInstance();
                
                // intercepting the service method
                R returnedObject = interceptor.intercept(service, method, arguments);
                return returnedObject;
            } else {
                // invoking the service method
                R returnedObject = (R) method.invoke(service, arguments);
                return returnedObject;
            }
        } catch (InstantiationException | IllegalAccessException |
                 InvocationTargetException | NoSuchMethodException e) {
            throw new RuntimeException(e);
        }
    }
}

همان‌طور که می‌بینید، این کد نسبتاً پیچیده، تا حدی مبهم و در زمان کامپایل Type-Safe نیست. این وضعیت در بیشتر مواردی که از Reflection API در موارد کاربردی واقعی استفاده می‌کنید، صادق است.

بیایید کلاس دیگری اضافه کنیم تا ثابت شود مکانیزم Interception به‌درستی کار می‌کند:

public class SomeNonInterceptedService {
    
    String message(String input) {
        return input.toUpperCase();
    }
}

حالا که تمام عناصر آماده هستند، کد زیر را اجرا کنید:

public static void main(String[] args) {
 
    String interceptedOutput = 
            ServiceFactory.invoke(SomeInterceptedService.class, "message", "Hello");
    IO.println("Intercepted output = " + interceptedOutput);
 
    String nonInterceptedOutput = 
            ServiceFactory.invoke(SomeNonInterceptedService.class, "message", "Hello");
    IO.println("Non intercepted output = " + nonInterceptedOutput);
}

خروجی:

Intercepted output = HELLO [was intercepted]
Non intercepted output = HELLO

نکته مهم: این مثال به‌درستی کار می‌کند چون Type ها به‌خوبی تعریف شده‌اند. متود invoke() به دنبال متودی به نام message() است که یک String به‌عنوان پارامتر بگیرد. اگر متود message() روی Type CharSequence به‌جای String تعریف شده بود، فراخوانی getDeclaredMethod() این متود را پیدا نمی‌کرد.