Web Services

With KISS principle in mind, AbacusUtil focus on the rapid web service development for data/logic transfer among servers/clients. (It's recommended to call the service by url: endpoint url + "/" + operation name and define the error code in the response DTOs, instead of identifying call by Http Method or use Http status for application error). Here are the steps to develop web services with AbacusUtil:

• Step 1: Design the interface for your web service and DTOs(Request/Response objects): (which can be generated with (sample) xml. Refer to scheam)

public interface AccountService {
    // The default Http method is POST if the annotation is not configured here.
    // And the request url can set to operation name by setRequestByOperatioName(true) in HttpProxy.Config
    @POST("addAccount")
    AddAccountResponse addAccount(AddAccountRequest request);

    // By default, the request parameters should be wrapped with a DTO object with getter/setter methods.
    // Otherwise, Each parameter should be annotated by Field/Path with name.
    @GET("getAccount")
    GetAccountResponse getAccount(@Field("gui") String gui);

    @DELETE("removeAccount")
    RemoveAccountResponse removeAccount(RemoveAccountRequest request);
}

• Step 2: Implement the interface:

public class AccountServiceImpl implements AccountService {
    @Override
    public AddAccountResponse addAccount(AddAccountRequest request) {
        AddAccountResponse resp = new AddAccountResponse();

        // Do something...

        return resp;
    }

    @Override
    public GetAccountResponse getAccount(String gui) {
        GetAccountResponse resp = new GetAccountResponse();

        // Do something...

        return resp;
    }

    @Override
    public RemoveAccountResponse removeAccount(RemoveAccountRequest request) {
        RemoveAccountResponse resp = new RemoveAccountResponse();

        // Do something...

        return resp;
    }
}

• Step 3: Configure servlet for your web service. Here is the sample for tomcat. Both xml and json requests are supported with by same endpoint. Here is a sample for the web.xml

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

	<servlet>
		<description>Account Web Service</description>
		<display-name>Account Web Service</display-name>
		<servlet-name>Account</servlet-name>
		<servlet-class>com.landawn.abacus.http.WebServiceServlet</servlet-class>

		<init-param>
			<param-name>serviceImplClass</param-name>
			<param-value>com.landawn.abacus.http.demo.AccountServiceImpl</param-value>
		</init-param>
		
		<!-- below url mapper configuration is optional -->
		<init-param>
			<param-name>urlMapper</param-name>
			<param-value>getAccount=getAccount; addAccount=addAccount</param-value>
		</init-param>
		
		<!-- below http method mapper configuration is optional -->
		<init-param>
			<param-name>httpMethodMapper</param-name>
			<param-value>getAccount=GET, POST; addAccount=POST, PUT</param-value>
		</init-param>
	</servlet>

	<servlet-mapping>
		<servlet-name>Account</servlet-name>
		<url-pattern>/AccountService/*</url-pattern>
	</servlet-mapping>

</web-app>

• Step 4: Here is sample of sending request with xml format from the client

static final String url = "http://localhost:8080/abacus/AccountService";
static final AccountService xmlAccountService = HttpProxy.createClientProxy(AccountService.class, ContentFormat.XML, url);
// Or zipped with LZ4:
// static final AccountService xmlAccountService = HttpProxy.createClientProxy(AccountService.class, ContentFormat.XML_LZ4, url);

@Test
public void test_addAccount_xml() {
    AddAccountRequest addRequest = new AddAccountRequest();
    addRequest.setAccount(TestUtil.createEntity(Account.class));

    AddAccountResponse addResp = xmlAccountService.addAccount(addRequest);
    N.println(addResp);

    GetAccountResponse getResp = xmlAccountService.getAccount(addRequest.getAccount().getGUI());
    N.println(getResp);
}

<!-- addAccountRequest with xml -->
<addAccountRequest>
	<account>
		<account>
			<id>634209876</id>
			<gui>ffcc40c5f1fa4bff</gui>
			<emailAddress>175c2304ac224e80</emailAddress>
			<firstName>d5cbcd728923432e</firstName>
			<middleName>d75b0b5befbd46fc</middleName>
			<lastName>39d14d5f85ee4c64</lastName>
			<birthDate>1437010884475</birthDate>
			<status>735955354</status>
			<lastUpdateTime>1437010884475</lastUpdateTime>
			<createTime>1437010884475</createTime>
		</account>
	</account>
</addAccountRequest>

<!-- addAccountResponse with xml -->
<addAccountResponse>
	<responseCode>0</responseCode>
	<responseMessage>OK</responseMessage>
</addAccountResponse>

<!-- getAccountResponse with xml -->
<getAccountResponse>
	<responseCode>0</responseCode>
	<responseMessage>OK</responseMessage>
	<account>
		<account>
			<id>634209876</id>
			<gui>ffcc40c5f1fa4bff</gui>
			<emailAddress>175c2304ac224e80</emailAddress>
			<firstName>d5cbcd728923432e</firstName>
			<middleName>d75b0b5befbd46fc</middleName>
			<lastName>39d14d5f85ee4c64</lastName>
			<birthDate>1437010884475</birthDate>
			<status>735955354</status>
			<lastUpdateTime>1437010884475</lastUpdateTime>
			<createTime>1437010884475</createTime>
		</account>
	</account>
</getAccountResponse>

• Step 5: Or sending request with json format from the client

static final String url = "http://localhost:8080/abacus/AccountService";
static final AccountService jsonAccountService = HttpProxy.createClientProxy(AccountService.class, ContentFormat.JSON, url);
// Or zipped with snappy:
// static final AccountService jsonAccountService = HttpProxy.createClientProxy(AccountService.class, ContentFormat.JSON_SNAPPY, url);

@Test
public void test_addAccount_json() {
    AddAccountRequest addRequest = new AddAccountRequest();
    addRequest.setAccount(TestUtil.createEntity(Account.class));

    AddAccountResponse addResp = jsonAccountService.addAccount(addRequest);
    N.println(addResp);

    GetAccountResponse getResp = jsonAccountService.getAccount(addRequest.getAccount().getGUI());
    N.println(getResp);
}

-- addAccountRequest with json
{
	account:{
		id:1450706619,
		gui:"7c8b7956f34742d0",
		emailAddress:"bb22ff882f984eca",
		firstName:"37b2d57eb0d64a58",
		middleName:"32b0c4b308064aeb",
		lastName:"5b98779e6fed406a",
		birthDate:1437011613899,
		status:-2064330437,
		lastUpdateTime:1437011613899,
		createTime:1437011613899
	}
}

-- addAccountResponse with json
{
	responseCode:0,
	responseMessage:"OK"
}

-- getAccountResponse with json
{
	responseCode:0,
	responseMessage:"OK",
	account:{
		id:1450706619,
		gui:"7c8b7956f34742d0",
		emailAddress:"bb22ff882f984eca",
		firstName:"37b2d57eb0d64a58",
		middleName:"32b0c4b308064aeb",
		lastName:"5b98779e6fed406a",
		birthDate:1437011613899,
		status:-2064330437,
		lastUpdateTime:1437011613899,
		createTime:1437011613899
	}
}

There are a lot of additional features supported by HttpProxy, Field/Path(copied from Retrofit), and refer to SecurityDTO for Securtiy request/response.

Retrofit is an excellent framework for Restful Services in Java, recommended to all the java developers.