مقدمات ساخت ساده‌ترین پروژه‌ی وب-سرویس

در این مقاله ابتدا روش ساخت یک پروژه‌ی ساده JAX-RS در Eclipse شرح داده می‌شود. پیاده سازی‌های مختلفی از JAX-RS وجود دارد که ما از Jersey استفاده می‌کنیم. سپس پروژه‌ی ساده‌ای را کد‌نویسی می‌کنیم که وظیفه‌ی آن گرفتن نام کاربر و سلام دادن به اوست!

تکنولوژی‌های استفاده شده در این مقاله به شرح زیر اند:

• IDE: Eclipse Oxygen Release (4.7.0)
• Tomcat v9.0
• JDK 8
• Maven
• Jersey 2.x
• Win 10

تنظیمات در Eclipse

اجرای پروژه‌های EE به یک Server نیاز دارد. کار راه اندازی سرور را به Eclipse خواهیم سپرد اما قبل از آن باید فایل های سرور مورد نظر خود را دانلود کرده و پیش از اجرای پروژه به Eclipse معرفی کنیم. سرور Tomcat را از این سایت می توان دریافت کرد. در این مثال نسخه ی 9 از سرور جهت اجرا روی سیستم عامل ویندوز دانلود می‌شود.

فایل دریافت شده را extract کرده و در محل مناسب قرار می‌دهیم. در قدم بعدی Eclipse را باز کرده و وارد بخش Workbench می‌شویم.

سرور Tomcat که پیشتر دانلود کرده بودیم را در تب Servers معرفی خواهیم کرد. اگر این Tab فعال نیست می‌توان آن را از بخش زیر فعال کرد:

Window> Show View> Servers

سپس روی No servers are available… که در شکل بالا نشان داده شده است کلیک کرده و آدرس پوشه Unzip شده‌ی سرور را به eclipse معرفی می کنیم. در این صورت سرور به شکل زیر در تب سرور‌ها نمایش داده می‌شود.

در ادامه یک پروژه‌ی جدید Maven ای از قسمت File>New>Maven Project می‌سازیم.

تیک مربوط به (…Create a simple project (Skip  را علامت زده و روی Next کلیک می کنیم.

در ادامه مشخصات مورد نیاز مانند Group Id، Artifact Id و Version را وارد می‌‌کنیم. این سه، مشخصه‌هایی هستند که هر ماژول Maven ای با آنها شناخته می‌شود. نام فایل ماژول به شکل ArtifactId-Version.Packaging ساخته می‌شود. در انتخاب نام برای سه مشخصه ی فوق عرف هایی وجود دارد که بهتر است رعایت شوند. مثلا بخش‌های مختلف groupId با « . »  از هم جدا می‌شوند و تقریبا متشکل از URL موسسه‌ی توسعه دهنده (از اخر به اول) و بخشی از نام پروژه است. کلمات مختلف artifactId با « – »  از هم جدا می‌شوند و با حرف کوچک نوشته می‌شوند. در این مثال چون پروژه‌ای که می‌خواهیم بسازیم یک وب سرویس است packaging را به war تغییر می‌دهیم. در قسمت Name و Description بدون رعایت «عرف و روال» های فوق برای GroupId و ArtifactId پروژه را شرح دهیم.

با زدن Finish پروژه ساخته شده و در تب Package Explorer نشان داده می‌شود. شکل زیر نشان می دهد، پروژه‌ی ساخته شده فعلی نواقصی دارد. این مشکلات در تب Markers لیست شده‌اند. در ادامه تک تک این نواقص را رفع می‌کنیم.

در هیچ قسمتی از روال ساخت پروژه تا این جا مشخص نکرده‌ایم از چه نسخه ای از JDK استفاده خواهیم کرد. پیش فرض Maven این است که از نسخه‌ی 1.5 استفاده می‌شود اما قادر به پیدا کردن این نسخه نیست. چرا که 1.8 نسخه‌ی مورد استفاده‌ی ماست. برای رفع این مشکل در فایل pom.xml تکه کد زیر را وارد می کنیم.

<build>
	<plugins>
		<plugin>
			<groupId>org.apache.maven.plugins</groupId>
			<artifactId>maven-compiler-plugin</artifactId>
			<configuration>
				<source>1.8</source>
				<target>1.8</target>
			</configuration>
		</plugin>
	</plugins>
</build>

سپس فایل pom.xml را ذخیره می‌کنیم. در ادامه روی نام پروژه راست کلیک کرده و از قسمت مربوط به Maven گزینه‌ی Update Project را انتخاب می‌کنیم. (این کار باعث چک کردن دوباره ی فایل pom.xml شده و تنظیمات مربوط به نسخه‌ی JDK را اعمال می‌کند)

در نتیجه نسخه‌ی JRE در Package Explorer هم اصلاح می‌شود.

در این بخش قسمتی از dependency ها را در فایل pom.xml وارد می‌کنیم. JAX-RS نام استانداردی است که در پروژه‌های Java EE برای Rest Web Service از آن استفاده می‌شود. هنگام استفاده از آن باید یکی از پیاده سازی‌های JAX-RS مانند Jersey استفاده کنیم. برای اضافه کردن Jersey بخش زیر را به pom.xml اضافه کرده و دوباره آن را ذخیره می‌کنیم.

<dependencies>
	<dependency>
		<groupId>org.glassfish.jersey.core</groupId>
		<artifactId>jersey-server</artifactId>
		<version>2.25.1</version>
	</dependency>
	<dependency>
		<groupId>org.glassfish.jersey.containers</groupId>
		<artifactId>jersey-container-servlet</artifactId>
		<version>2.25.1</version>
	</dependency>
</dependencies>

در صورتی که یک اتصال اینترنت برقرار باشد با ذخیره کردن فایل pom.xml پکیج‌های مربوط به این وابستگی‌ها از مخازن Maven دانلود شده و در بخش Maven Dependencies داخل پروژه قرار داده می‌شود. جهت تکمیل تاثیر گذاری این بخش (و تنظیم خودکار Facet های پروژه در اثر اضافه کردن این وابستگی) دوباره روی نام پروژه راست کلیک کرده و از بخش Maven گزینه ی Update Project را انتخاب می‌کنیم.

مرحله‌ی بعدی تنظیم Facet های پروژه است. در تب Package Explorer روی پروژه راست کلیک کرده و گزینه‌ی properties را انتخاب می‌کنیم. در پنجره‌ی باز شده از سمت چپ روی Project Facets کلیک می‌کنیم.

در این حالت Facet های زیر باید تیک خورده باشند:

• Dynamic Web Module
• Java
• JavaScript
• JAX-RS (REST Web Service)

دقت داشته باشید که نسخه ی Java (که باید 1.8 باشد) به خاطر اضافه کردن maven-compiler-plugin تنظیم شده و JAX-RS Facet به خاطر اضافه کردن وابسته های Jersey تیک خورده و ورژن آن روی 2 تنظیم شده است. در صورتی که وابستگی ها به Jersey از قبل اضافه نشده بودند با تیک زدن JAX-RS و انتخاب نسخه ی آن، در پنجره‌ی زیر پیغام Further configuration available… ظاهر می‌شد و باید فایل jar مربوط به  Jersey را به پروژه معرفی می‌کردیم.

دقت کنید که ورژن Dynamic Web Module را به عدد 3 تغییر دادیم.

Web application ای که در حال ساخت آن هستیم نیازمند داشتن یک فایل web.xml و فولدر WEB-INF است. برای ساخت اتوماتیک در تب Package Explorer روی نام پروژه راست کلیک کرده و از قسمت Java EE Tools گزینه‌ی Generate Deployment Descriptor Stub را انتخاب می‌کنیم.

در نتیجه بخش های زیر به پروژه اضافه شده و اخطار مربوط به فقدان web.xml حذف می‌شود.

در انتها جهت تنظیم encoding فایل pom.xml به یک گزینه‌ی مستقل از پلتفرم و استاندارد بخش زیر را به فایل pom.xml اضافه می نماییم.

<properties>
	<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>

فایل کامل pom.xml به شکل زیر است.

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
	<modelVersion>4.0.0</modelVersion>
	<groupId>com.rhotiz.jaxrs</groupId>
	<artifactId>simple-jax-rs</artifactId>
	<version>0.0.1-SNAPSHOT</version>
	<packaging>war</packaging>
	<name>Simple JAX-RS Project</name>
	<dependencies>
		<dependency>
			<groupId>org.glassfish.jersey.core</groupId>
			<artifactId>jersey-server</artifactId>
			<version>2.25.1</version>
		</dependency>
		<dependency>
			<groupId>org.glassfish.jersey.containers</groupId>
			<artifactId>jersey-container-servlet</artifactId>
			<version>2.25.1</version>
		</dependency>
	</dependencies>

	<build>
		<plugins>
			<plugin>
				<groupId>org.apache.maven.plugins</groupId>
				<artifactId>maven-compiler-plugin</artifactId>
				<configuration>
					<source>1.8</source>
					<target>1.8</target>
				</configuration>
			</plugin>
		</plugins>
	</build>
</project>

فایل web.xml ایجاد شده نیز دارای محتویات زیر است:

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://java.sun.com/xml/ns/javaee" xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd" version="2.5">
  <display-name>simple-jax-rs</display-name>
</web-app>

در این مرحله آماده سازی پروژه ی Web Service به اتمام رسیده و می‌توانیم شروع به کد‌نویسی کنیم.

کد‌نویسی پروژه Hello userName

وب سرویس مورد نظر از دو کلاس تشکیل شده است. یک کلاس، وظیفه‌ی مدیریت و پاسخ‌دهی به متد‌های REST را مدیریت می‌کند که معمولا با نام‌هایی مثل resource یا service از آن یاد می‌کنیم. کلاس دوم وظیفه‌ی مدیریت کلاس‌های resource و شناساندن آنها به servlet container (در این مثال: Tomcat) را بر عهده دارد.

نوشتن کلاس service

یک پروژه‌ی Maven دارای resource folder های استانداردی است. یک کلاس در داخل resource folder، با نام  src/main/java می‌سازیم و نام آن را HelloUserService می‌گذاریم.  هنگام ساخت کلاس، package مناسب نیز ساخته می‌شود.

کد نوشته شده در کلاس HeloUserService به شرح زیر است:

package com.rhotiz.jaxrs;

import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;
import javax.ws.rs.core.Response;

@Path("")
public class HelloUserService {

	@Path("{userName}")
	@GET
	public Response helloUser(@PathParam("userName") String usreName) {
		return Response.ok().entity("Hello "+usreName).build();
	}
}

وظیفه‌ی این کلاس و متد نوشته شده در آن، مدیریت درخواست‌های GET و پاسخگویی به آنهاست. کاری که متد helloUser انجام می‌دهد استخراج نام کاربر از URL و تولید رشته‌ای است که به کاربر سلام می‌دهد!

نوشتن کلاس Application

کلاس دوم با نام SayHelloApplication ساخته می‌شود. وظیفه‌ی این کلاس شناساندن کلاس Service ای است که پیشتر ساختیم. به این منظور باید کلاس javax.ws.rs.core.Application را extend کنیم.

کد این کلاس به شرح زیر است:

package com.rhotiz.jaxrs;

import java.util.HashSet;
import java.util.Set;

import javax.ws.rs.ApplicationPath;
import javax.ws.rs.core.Application;
@ApplicationPath("")
public class SayHelloApplication extends Application {
	Set<Object> singletons = new HashSet<>();
	
	public SayHelloApplication() {
		singletons.add(new HelloUserService());
	}

	@Override
	public Set<Object> getSingletons() {
		return singletons;
	}
	
}

یکی از روش های معرفی کلاس‌های resource ساختن یک نمونه از آنها، تجمیع آنها در یک Set و معرفی آنها به container است تا هنگام دریافت یک درخواست از کاربر، از آنها برای پاسخگویی استفاده کند. در کد بالا هم این کار انجام شد. ApplicationPath@، معرفِ کلاسی است که این وظیفه را بر عهده دارد. جهت رعایت سادگی از شرح تنظیماتی که به کمک Path@ و ApplicationPath@ می توان اعمال کرد صرف نظر می‌کنیم.

در این حالت پروژه در ساختار زیر است:

اجرای پروژه

جهت اجرای پروژه روی نام پروژه راست کلیک کرده و از منوی Run As، گزینه ی Run On Server را انتخاب می‌کنیم.

سپس در پنجره‌ی باز شده، سروری که قبلا ساخته بودیم را انتخاب کرده و روی Finish کلیک می‌کنیم.

پس از اجرای پروژه در صورتی که تمام مراحل به صورت کامل انجام شده باشند یک مرورگر باز شده و به URL زیر هدایت می شود:

http://localhost:8080/simple-jax-rs/

به بخش (http)، شما یا scheme گفته می‌شود. بخش (localhost) نام دامین ای است که وب اپلیکیشن روی آن است. 8080 شماره ی پورتی است که سرور Tomcat روی آن اجرا شده است. simple-jax-rs نام فایل‌ای است که با پسوند war در داخل سرور، deploy کرده‌ایم. این نام از ArtifactId پروژه گرفته شده است.

وب اپلیکیشنی که نوشته‌ایم قادر به پاسخ گویی مناسب به URL هایی است که علاوه بر داشتن قسمت‌های فوق در انتها دارای یک رشته‌ی دیگر هم باشند که کلاس resource آن را به عنوان نام کاربر در نظر گرفته و از آن استفاده می‌کند. با وارد کردن URL زیر پاسخ مناسب را دریافت می‌کنیم:

http://localhost:8080/simple-jax-rs/userName