pREST Quick Start

pREST - Java Web Framework for servlet container which is dedicated for effective development of Web applications and Web services.
Controller: - basic unit of pREST Web application which controls the flow of input/output data. It is represented by a Java class
Action: - basic functional unit of pREST Web controller, represented by its public method
Request parameters: - standard POST/GET HTTP input parameters
URL parameters: - sequential input parameters gained from the URI part after the controller action part (the parameter separator is "/")
Controller creation

/**
 * pREST controller extends class prest.core.Controller.
 * The controller is mapped to the part of URL in the initialize(()
 * method of prest.core.Application class:
 * 
 * package quickstart;
 *
 * public class QuickStartApplication extends prest.core.Application {
 *
 * 	@Override
 * 	public void initialize() throws ApplicationException {
 * 		mount("/controller-path", new QuickStartController());
 * 	}
 * }
 *
 * pREST application represented by an application class QuickStartApplication
 * is specified in web.xml
 *
 * <filter>
 * 	<filter-name>ServletFilter</filter-name>
 * 	<filter-class>prest.core.ServletFilter</filter-class>
 * 	<init-param>
 * 		<param-name>Application</param-name>
 * 		<param-value>quickstart.QuickStartApplication</param-value>
 * 	</init-param>
 * </filter>
 * <filter-mapping>
 * 	<filter-name>ServletFilter</filter-name>
 * 	<url-pattern>/*</url-pattern>
 * </filter-mapping>
 *
 * The controller's methods can be call by URL:
 *
 * http://<host>:<port>/<app_name>/<controller-path>/<action_name>
 *
 * <app_name> - the application context
 * <controller_path> - the path a pREST controller is mapped, in our case "/controller-path"
 * <action_name> - the name of a requested action - action is mapped into name of public method
 *			of the controller or into the name specified in @Action annotation
 */
public class QuickStartController extends prest.core.Controller {

	/**
	 * pREST engine try to call the public controller method annotated by @Action
	 * annotation with the same name as the URL action name <action_name> is.
	 * <action_name> is the first URL segment after <controller_path>.
	 * The helloWorld() method therefore can be invoke by URL with action
	 * named "hello-world":
	 * http://<host>:<port>/<app_name>/<controller_path>/hello-world
	 *
	 * The @Doc annotation is used for documenting a controller, a method (action)
	 * and a method parameter - the documentation can be displayed by calling
	 * _docs_ and _doc_ actions like this:
	 * http://<host>:<port>/<app_name>/<controller_path>/_doc_
	 *
	 * The example method below sets HTTP response parameters:
	 * content type, charset encoding and a content of a HTTP body.
	 *
	 * @return string written to output
	 */
	@Action(name="hello-world")
	@Doc("Documentation of a method")
	public String helloWorld() {
		setContentType(ContentType.TEXT_PLAIN_UTF8);
		String httpBody = "Hello World!";
		return httpBody;
	}

	/**
	 * POST/GET parameters with p1 and p2 keys are mapped on param1 and param2
	 * parameters by using @Key annotation (prest.core.annotations.Key)
	 *
	 * For example, in case of URL:
	 * http://localhost:8080/quickstart/controller-path/post-get-parameters?p1=foo&p2=77
	 * the param1 will get "foo" value and param2 will get number 77 as a value.
	 *
	 * In case of missing POST/GET parameter or unsuccessful conversion of prameter
	 * string representation to corresponding object or primnitive Java type,
	 * parameter has null value.
	 *
	 *
	 * @param param1
	 *            the value of POST/GET parameter of p1 is mapped to this parameter
	 * @param param2
	 *            the value of POST/GET parameter of p2 is mapped to this parameter
	 */
	@Action(name="post-get-parameters")
	public void postGetParameters(
	        @Key("p1") String param1,
	        @Key("p2") Integer param2)
	{
		// do_something();
	}

	/**
	 * The URL parameters are mapped into arguments (not annotated by @Key annotation)
	 * of the called method seriately.
	 * 
	 * For example, in case of URL:
	 * http://localhost:8080/quickstart/controller-path/url-parameters/foo/77
	 * the stringParam will get "foo" value and integerParam will get number 77
	 * as a value.
	 *
	 * In case of missing URL parameter or unsuccessful conversion of URL prameter
	 * string representation to corresponding object (or primnitive Java type),
	 * parameter has a null value.
	 *
	 * @param stringParam
	 *            the value of the first URL parameter is mapped into this argument
	 * @param integerParam
	 *            the value of the second URL parameter is mapped into this argument.
	 */
	@Action(name="url-parameters")
	public void urlParameters(
	        @Doc("Documentation of string parameter") String stringParam,
	        @Doc("Documentation of integer parameter") Integer integerParam)
	{
		// do_something();
	}

	/**
	 * The special types:
	 * 	- prest.core.types.UrlParameters
	 * 	- prest.core.types.RequestParameters
	 * encapsulates all URL or POST/GET parameters.
	 *
	 * @param urlParameters
	 *            all URL parameters.
	 * @param requestParameters
	 *            all POST/GET parameters.
	 */
	@Action(name="special-parameters")
	public void specialParameters(
	        UrlParameters urlParameters,
	        RequestParameters requestParameters)
	{
		// do_something_with_all_url_parameters(urlParameters);
		// do_something_with_all_request_parameters(requestParameters);
	}

	/**
	 * @Action annotation (prest.core.annotations.Action) is used for mapping
	 * the action name into an appropriate annotated controller's public
	 * method which can be called by defined HTTP methods.
	 * This Java controller method will be called only by GET HTTP method on URL
	 * with action name "product":
	 * http://host.net/app/controller-path/product
	 * If we do not specify httpMethod @Action parameter, pREST will call
	 * this method in case any HTTP method.
	 *
	 * @param id
	 *            URL parameter
	 * @return object, which will be serialized into string by calling a toString() method.
	 */
	@Action(name = "product", httpMethod = {"GET"})
	public Car getProduct(Long id) {
		Car car = Car.get(id);
		return car;
	}

	/**
	 * @View annotation (prest.web.annotations.View) is used for assigne the
	 * input/output filter with called controller method. 
	 * The goal of the @View annotation filter is to represent testView()
	 * returned data (model) by template specified as @View annotation
	 * template attribute.
	 *
	 * @return data, model that has to be visualized by @View annotation template.
	 */
	@Action(name="test-view")
	@Doc("The example of @View annotation usage")
	@View(template = "/templates/view.jsp")
	public Object testView() {
		String[] data = {"data", "for", "view"};
		return data;
	}

	/**
	 * @Json annotation (prest.json.annotations.Json) is used for assigne the 
	 * input/output filter with called controller method.
	 * The task of the @Json annotation filter is to serialize output data
	 * into JSON format.
	 *
	 * @param id
	 *            URL parameter
	 * @return data object, model (has to be serialized into JSON format)
	 */
	@Action(name="test-json")
	@Json
	public Car testJson(Long id) {
		Car car = Car.get(id);
		return car;
	}
}
pREST

Authors

pREST Quick Start

Controller creation
