Paoding Rest for Java

Paoding-Rest is a java web rest framework based on spring.

HOME: http://code.google.com/p/paoding-rest/
示例应用: http://paoding.net/rest-demo

Paoding-Rest是Paoding中文分词作者的又一个开源项目。目前版本为0.2。


Paoding-Rest是什么

Paoding-Rest是使用Java编写的，基于Spring的，标准而又新颖的WEB REST框架。
作者之前多次利用了http method的特性修正传统web框架的使用，这和REST在某种程度上有所吻合。Paoding-Rest可以说是一个具有REST特点的Java Web框架。
Paoding-Rest的核心类RestSerlvet继承于Spring提供的FrameworkServlet, 使Paoding-Rest能够以相当少的代码量，提供极其丰富的功能并具有很高灵活性(thanks to Spring)。

如果您熟悉Spring，眨两眼就上手Paoding-Rest了。使用Paoding-Rest，您可以抛弃很多无聊、故弄玄虚的工作了。

Paoding-Rest不是什么

Paoding-Rest不是一个页面技术，所以您还需要结合其它页面技术来完成整个web应用。
默认的Paoding-Rest是使用jsp来展现页面的，不过您只要稍稍配置一下，就可以使用velocity,freemark之类的其它页面展现技术了。

注意

Paoding-Rest是建立在Spring FrameworkServlet之上的web框架，如果您不喜欢Spring或者因为其它原因不能使用Spring，那么Paoding-Rest并不适合您。

Paoding-Rest的显著特点

1) Rest风格的url和处理

2) POJO的Controller and Model

Controller:

public class SessionAction {
	
	private UserBo userBo;
	
	public void setUserBo(UserBo userBo) {
		this.userBo = userBo;
	}

	/**
	 * 展现会话开始页面(即登录页面)
	 */
	public String get(HttpServletRequest request, HttpSession session) {
		if (session.getAttribute("user_id") != null) {
			// 如果已经登录过了，直接到产品列表资源页面
			return "r:action:product";
		} else {
			// 如果还没有登录，则展现登录页面
			return "login";
		}
	}

	/**
	 * 执行用户登录认证
	 * 
	 * @param user
	 *            登录者信息
	 * @return
	 */
	public String post(User user, HttpSession session) {
		user = userBo.auth(user.getLogonName(), user.getPassword());
		if (user != null) {
			// 验证正确
			session.setAttribute("user_id", user.getId());
			return "@:1";
		} else {
			// 报告用户名和密码错误
			return "@:-1";
		}
	}

	/**
	 * 登出
	 * 
	 * @return
	 */
	public String delete(HttpSession session) {
		// 使会话失效
		session.invalidate();
		// 重定向到登录会话开始页面(即登录页面)
		return "r:action:session";
	}
}

Model

public class User {

	private Long id;
	private String logonName;
	private String password;
	private String name;
	private String address;
	private String postalCode;
	private double balance = Integer.MAX_VALUE;

	//getter & setting here
}

3)简单的web.xml配置:

	<servlet>
		<servlet-name>shopping</servlet-name>
		<servlet-class>net.paoding.rest.RestServlet</servlet-class>
		<init-param>
			<param-name>defaultAction</param-name>
			<param-value>home</param-value>
		</init-param>
	</servlet>

	<servlet-mapping>
		<servlet-name>shopping</servlet-name>
		<url-pattern>/shopping/*</url-pattern>
	</servlet-mapping>

4) Controller基于Spring配置(ServletName-servlet.xml=>shopping-servlet.xml)，并轻松连接到中间层：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE beans PUBLIC "-//SPRING//DTD BEAN//EN" "http://www.springframework.org/dtd/spring-beans.dtd">

<beans>
	<bean name="viewTransfer"
		class="net.paoding.rest.SimpleViewTransfer">
		<property name="prefix" value="/page/shopping/" />
		<property name="suffix" value=".vm" />
	</bean>

	<bean name="home" class="net.paoding.rest.examples.shopping.action.HomeAction"
		autowire="byName" />

	<bean name="session" class="net.paoding.rest.examples.shopping.action.SessionAction"
		autowire="byName" />
</beans>

[b]getting started[b]


现在您需要准备这些工作：

1)web容器，比如Tomcat,Resin，用以运行web app;

2)一个IDE环境，比如Eclipse,NetBean，当然这不是必须的。

我们可以开始工作了。

----------------------------------------------------

搭建并开始使用Paoding-Rest:

1、创建一个普通的Java工程，名为HelloRest.

2、把Paoding-Rest/examples目录及其子目录和文件整个copy到HelloRest/src

3、把Paoding-Rest/war目录及其子目录和文件整个copy到HelloRest/war

4、把Paoding-Rest/paoding-rest.jar copy到HelloRest/war/WEB-INF/lib下

5、HelloRest/war/WEB-INF/lib下的jar文件，架到您工程的class path中。

6、设置该工程的编译路径为war/WEB-INF/classes，并重新编译代码

OK，现在可以使用Paoding-Rest了，将HelloRest/war部署到web容器了，
并通过127.0.0.1:8080/appPath/ 访问。
如果显示了一些列的链接列表清单，则表示一切顺利。


[b] tips [b]

1、web.xml需要配置一个或多个net.paoding.rest.RestServlet

2、每个 RestServlet 需要一个serlvetName-servlet.xml的Spring配置文件，用于配置POJO控制器servletName]要替换成实际配置时该Servlet的名称。

3、每个 RestServlet 都需要一个servlet-mapping配置，并只能采用<url-pattern>/shopping/*</url-pattern>这样的配置形式


4、POJO控制器就是一个普通的Java对象，命名、方法名、方法参数的个数和类型没有任何限制，每个方法可以返回任何对象(Paoding使用toString()获取其view name)，也可以返回null。但有一个限制：不能有同名的方法。浏览器使用appPath/servlet-path/pojo_action/method_name/xxx地址时候，方法名为method_name的方法将被调用，处理请求

5、POJO控制器的方法可以含有全部或部分 HttpServletRequest,HttpServletResponse,HttpSession,HttpServlet等参数,且顺序可任意：

public String login(User user, HttpSession session, int h, HttpServletRequest req, HttpServletResponse resp,  HttpServlet servlet){
    return "home";
}

6、POJO控制器的方法可以放入多个Bean，甚至他们具有同样的类型：

//aooPath/servlet/action/hello/110/xyz?user.id=123&user1.name=wang&user2.name=antherwang
public String hello(int a, String b, User c, User d, Company e, HttpServletRequest req) {
    return "hello";
}

URI中的110,xyz按照hello方法声明的顺序分别设置给a和b

user.xxx以及user1.xxx的属性设置到第1个user对象中(也就是User c)

user2.xxx的属性设置到第2个user对象中(也就是User d)

company.xxx的属性设置到Campany对象中。

7、支持http method语义：

对只有action name，没有method name的请求，如：appPath/servlet/action_name, appPath/servlet/action_name?k=v

GET时: 如果POJO控制器有声明index(...)方法，由该方法负责处理此请求，否则由get(...)方法处理

POST时：由post(...)方法处理

PUT时：由put(...)方法处理

DELETE时：由delete(...)处理

这些请求只要没有被用到，POJO控制器都可以不声明它们。

8、pojo控制器返回串规定：

如果以"r:","redirect:","!:"开头，表示使用redirect，此时不经过view name->view page file的转化。

其它表示使用forward到对应的page file。

如果以"f:","file:"开头，表示不需要经过viewTransfer，比如可以直接返回"file:/page/anotherlocation/some.html"

以"@:"开头，表示返回随后的字符串，这一般用于ajax操作的返回值，如"@:1"，用于返回1给ajax客户端。

其它的view都经过viewTransfer转化。