شروع JAX-RS

از سری مقالات آموزش Java Enterprise, مبحث JAX-RS را برمی‌گزینیم.

در مقاله قبل توضیحاتی پیرامون RESTful API داده شد و با مفاهیم اولیه آن آشنا شدیم. در راستای مقالات پیاده سازی RESTful API, مفاهیم باقی مانده را نیز در قالب کد ها بررسی می‌کنیم. در این مقاله قصد داریم تا به پیاده سازی RESTful API به وسیله جاوا بپردازیم. Java API for RESTful Web Service و یا به اختصار JAX-RS یک روش برای ایجاد RESTful API ها در جاوا است. در واقع JAX-RS, مجموعه ای از دستورات شرطی است که متناسب با درخواست ورودی, پردازش مورد نظر را انتخاب می‌کند و انجام می‌دهد. همچنین این عمل با استفاده از Annotation ها بسیار آسان تر شده است و بجای دستورات شرطی از Annotation ها استفاده می‌شود.

همانطور که در مقاله قبل اشاره شد, RESTful از Http برای جابجایی اطلاعات استفاده می‌کند. client یک Request را ارسال می‌کند و Server متناسب با درخواست Client, مقدار مورد نظر را برمی‌گرداند. ساختار Http Request به این صورت است:

verb : متد Http را مشخص می‌کند
URI : همانطور که در مقاله قبل بررسی شد, آدرس منبعی که می‌خواهیم به آن دسترسی پیدا کنیم را مشخص می‌کند
Header : یکسری اطلاعات, علاوه بر اطلاعات اصلی را به همراه دارد
Body : اطلاعات اصلی را شامل می‌شود

ساختار Response نیز مشابه ساختار Requset است با این تفاوت که بجای Verb و URI, مقدار Response Code وجود دارد.

همانطور که در ابتدای مقاله اشاره شد, در JAX-RS می‌توان از Annotation ها استفاده کرد. با استفاده از Annotation ها می‌توان کارکرد هر متد را مشخص کرد. در اینجا به یکسری از Annotation ها اشاره می‌کنیم:

Path : مسیر اصلی REST API را مشخص می‌کند. در واقع ساختار URL+path را پشتیبانی می‌کند. URL در اینجا, آدرس برنامه و همچنین Servlet مورد نظر است که کنترل API را برعهده دارد.
Post : مشخص می‌کند که این متد, به Request هایی که از متد Post استفاده می‌کنند, پاسخ می‌دهد.
Get : مانند Post Annotation است با این تفاوت که برای متد های Get در Http می‌باشد
Produce : این Annotation مشخص می‌کند که متد Get, اطلاعات را با چه نوع ساختاری برگرداند. برای مثال اگر بخواهیم اطلاعات در قالب xml برگردانده شود, باید از produce(application/json)@ استفاده شود.
Consume : مانند مشخص می‌کند که این متد, اطلاعات را در چه قالبی استفاده می‌کند.
Path Param : اطلاعات و متغیر های موجود را دریافت می‌کند

اکنون اولین پروژه را با استفاده از مفاهیم تعریف شده ایجاد می‌کنیم. در Intellij یک پروژه ایجاد می‌کنیم و از طریق Maven, مقادیر مورد نیاز برای archetype را وارد می‌کنیم:

Group ID : org.glassfish.jersey.archetypes
Artifact ID : jersey-quickstart-webapp
Version : release

اکنون یک کلاس و یک فایل JSP ایجاد شده است. وقتی پروژه را اجرا کنید و بر روی Jersey resource کلیک کنید, به اولین API ایجاد شده هدایت می‌شوید. آدرسی که این API دارد به این صورت است:

http://localhost:8080/webapi/myresource

اگر کلاس متناظر با این API را بررسی کنید :

@Path("myresource")
public class MyResource {
    @GET
    @Produces(MediaType.TEXT_PLAIN)
    public String getIt() {
        return "Got it!";
    }
}

مشاهده می‌کنید که آدرس API در path@ قرار داده شده است. سپس مشخص شده است که اگر http verb برابر با Get بود, متد getIt را فراخوانی کند. این متد مقدار خروجی را در قالب TEXT_PLAIN بر می‌گرداند. برای اینکه این ساختار را بهتر درک کنید, مقداری که متد getIt برمی‌گرداند را به این صورت تغییر می‌دهیم:

    @Produces(MediaType.TEXT_PLAIN)
    public String getIt() {
        return "<html> " +
                "<title>" + "Zero To Hero" + "</title>"
                + "<body>" + "First API" + "</body>" +
                "</html> ";
    }

اگر خروجی را بررسی کنید, مقادیر فوق را به صورت متن می‌بینید و هیچ قالب html برای آن تعریف نشده است. اما اگر MediaType را برابر TEXT_HTML قرار دهید, خروجی را در قالب HTML و بدون وجود tag ها, مشاهده می‌کنید. برای پردازش این درخواست, همانطور که در مقالات مرتبط با Servlet بررسی شد, نیاز است تا از Servlet استفاده کنید. برای این منظور فایل web.xml را بررسی می‌کنیم.

 <servlet>
        <servlet-name>Jersey Web Application</servlet-name>
        <servlet-class>org.glassfish.jersey.servlet.ServletContainer</servlet-class>
        <init-param>
            <param-name>jersey.config.server.provider.packages</param-name>
            <param-value>vhdrjb.test</param-value>
        </init-param>
        <load-on-startup>1</load-on-startup>
    </servlet>
    <servlet-mapping>
        <servlet-name>Jersey Web Application</servlet-name>
        <url-pattern>/webapi/*</url-pattern>
    </servlet-mapping>

همانطور که می‌بینید, یک Servlet در خواست های ورودی را دریافت می‌کند. می‌توانید مقالات Servlet را از اینجا مطالعه کنید. در مقاله بعد یک Resource ایجاد می‌کنیم و مفاهیم مرتبط با آن را بررسی می‌کنیم.

سری مقالات آموزش Java Enterprise ادامه دارد.

با ما همراه باشید.