• Home
• org.apache.juneau
• juneau-all
• 7.0.0
• source code
• package.html

×

Project download

Many resources are needed to download a project. Please understand that we have to compensate our server costs. Thank you in advance.
Project price only 1 $

You can buy this project and download/modify it how often you want.

org.apache.juneau.rest.package.html Maven / Gradle / Ivy

	
	
	


REST Servlet API




	Defines an API for defining REST resources as servlets.


Table of Contents

	
Introduction
	
Hello World Example
	
Class Hierarchy
	
REST Servlets
	

		
REST Java Method Signature
		

			
Path
			
Matchers
		
		
Request Content
	

			
Form Posts
			
Multipart Form Posts
		
		
Response Content
		
Lifecycle Hooks
		
OPTIONS Pages
		
Serializers
		
Parsers
		
Properties
		
Transforms
		
Guards
		
Converters
		
Child Resources
		
Localized Messages
		
Encoders
		
SVL Vars
		
Static Files
		
Listener Methods
	
		
Stylesheet
	
		
Default Headers
		
Handling Errors / Logging
		
Configuration Files
		
Annotation Inheritance
		
HTTP Status Codes
		
Overloaded HTTP Methods
		
Built-In Parameters
		
Defining your own serializers/parsers
		
Response Handlers
		
Other Notes
	
	
Using with OSGi
	
POJOs Convertible From Strings
	
Address Book Resource




1 - Introduction

	

		The juneau-rest.jar library allows you to quickly wrap POJOs and expose them as full-fledged REST 
		resources served up in a servlet container using a bare-minimum amount of code.
		The primary goal for Juneau was to make it as easy as possible to implement easy-to-read and self-documenting 
		REST resources using very little code.
	
	

		One of the biggest advantages of the Juneau REST framework over similar architectures is that it hides the 
		serialization layer from the developer.  
		The developer can work entirely with POJOs and let the Juneau framework handle all the serialization and 
		parsing work.  
		The developer need never know what the Accept or Content-Type or Accept-Encoding (etc...) 
		header values are because those details are all handled by the framework. 
	
	
 
		The API builds upon the existing JEE Servlet API.  
		The root class, {@link org.apache.juneau.rest.RestServlet} is nothing but a specialized 
		{@link javax.servlet.http.HttpServlet}, and the {@link org.apache.juneau.rest.RestRequest} and 
		{@link org.apache.juneau.rest.RestResponse} classes are nothing more than specialized 
		{@link javax.servlet.http.HttpServletRequest} and {@link javax.servlet.http.HttpServletResponse} objects.  
		This allows maximum flexibility for the developer since you can let Juneau handle operations such as 
		serialization, or you can revert to the existing servlet APIs to do low-level processing of requests yourself.	
		It also means you need nothing more than a Servlet container such as Jetty to use the REST framework.
	
	
	
Features
	

		

			Serializes POJOs to JSON, XML, HTML, URL-Encoding, UON, RDF/XML, N-Triple, Turtle, N3, SOAP, or 
			Java-serialized-object based on value of Accept header.  
			
No user code is required to handle these types.
			

				
Extensible design that provides ability to override existing content type handlers, or add the 
					ability to handle other kinds of content types.
			
		

			Parses content of POST/PUT request bodies to POJOs.
		

			Automatic built-in ability to serialize POJO metadata to JSON+SCHEMA, XML+SCHEMA, or HTML+SCHEMA based on 
			Accept header.
		

			Automatic negotiation of output Writer based on HTTP headers.
			

				
Automatic handling of Accept-Charset header for all character sets supported by the JVM.
				
Automatic handling of Accept-Encoding header with registered encoders.
			
		

			Automatic error handling.
			

				
Automatic 401 errors (Unauthorized) on failed guards.
				
Automatic 404 errors (Not Found) on unmatched path patterns.
				
Automatic 405 errors (Method Not Implemented) on unimplemented methods.
				
Automatic 406 errors (Not Acceptable) when no matching serializer was found to handle the 
					Accept header.
				
Automatic 412 errors (Precondition Failed) when all matchers failed to match.
				
Automatic 415 errors (Unsupported Media Type) when no matching parser was found was found to handle 
					the Content-Type header.
				
Automatic 500 errors on uncaught exceptions.
			
		

			Self-documenting REST interfaces.
		

			Various useful debugging features that make debugging using a browser extremely simple...
			

				
Ability to pass HTTP header values as URL GET parameters (e.g. &Accept=text/xml).
				
Ability to pass HTTP content on PUT/POST requests as a URL GET parameter 
					(e.g. &content={foo:"bar"}).
				
Ability to simulate non-GET requests using a &method GET parameter 
					(e.g. &method=POST).
				
Ability to force "text/plain" on response using GET parameter &plainText=true.
			
		

			Ability to implement overloaded HTTP methods through the use of the &method attribute 
			(e.g. &method=FOO).
		

			Ability to match URL patterns (e.g. /foo/{fooId}/bar/{barId}) against URLs 
			(e.g. /foo/123/bar/456/bing).
		

			Ability to associate guards at the resource or method levels through annotations.
			
Typically useful for security, but can be used for a variety of purposes.
		

			Ability to associate converters at the resource or method levels through annotations.
			
Typically useful for performing conversions on input and output, such as for supporting older input and 
			output formats.
	
	

		Many of the examples in this document are pulled directly from the microservice-samples-project.zip 
		project.
	

	


2 - Hello World Example

	

		A REST resource is an implementation of {@link org.apache.juneau.rest.RestServlet}, which itself is simply an 
		extension of {@link javax.servlet.http.HttpServlet}.  
	
	

		In this example, we define a resource called HelloWorldResource.  
		This example is located in the microservice-samples-project.zip project.
		It's assumed the reader is familiar with defining servlets in web applications.
	
	

		Like any servlet, we could define our resource in the web.xml file of the web application like so...
	
	

	<?xml version="1.0" encoding="UTF-8"?>
	<web-app version="2.3">
		<servlet>
			<servlet-name>HelloWorldResource</servlet-name>
			<servlet-class>com.foo.sample.HelloWorldResource</servlet-class>
		</servlet>
		<servlet-mapping>
			<servlet-name>HelloWorldResource</servlet-name>
			<url-pattern>/*</url-pattern>
		</servlet-mapping>
	</web-app>
	
	

		Our servlet code is shown below:
	
	

	/** 
	 * Sample REST resource that prints out a simple "Hello world!" message.
	 */
	@RestResource(
		messages="nls/HelloWorldResource", 
		htmldoc=@HtmlDoc(
			navlinks={
				"up: request:/..",
				"options: servlet:/?method=OPTIONS"
			}
		)
	)
	public class HelloWorldResource extends Resource {
	
		/** GET request handler */
		@RestMethod(name=GET, path="/*")
		public String sayHello() {
			return "Hello world!";
		}
	}
	
	

		The messages annotation points to a properties file on the classpath whose contents are shown below:
	
	

	#--------------------------------------------------------------------------------
	# HelloWorldResource labels
	#--------------------------------------------------------------------------------
	label = Hello World sample resource
	description = Simplest possible resource
	sayHello = Responds with "Hello world!" 
	
	
	

		It doesn't much simpler than that.  
		In this case, we're simply returning a string that will be converted to any of the supported languages (e.g. 
		JSON, XML, HTML, ...).
		However, we could have returned any POJO consisting of beans, maps, collections, etc...
	
	

		The {@link org.apache.juneau.rest.RestServletDefault} class that we're using here is a subclass of 
		{@link org.apache.juneau.rest.RestServlet} that provides default support for a variety of content types.  
		Implementers can choose to use this class, or create their own subclass of 
		{@link org.apache.juneau.rest.RestServlet} with their own specialized serializers and parsers.
	
	

		If you were to start up this servlet and view it with a browser, you would see this:
	
	
	

		The Juneau REST interface is designed to make it easy to interact with resources using nothing but a browser.  
		Therefore, several built-in features are provided for making it easy to do so.  
		Specifically, we'll be using these available URL parameters...
	
	

		

			&plainText=true - If specified, then the Content-Type on the response is always 
			"text/plain" regardless of the data format.
		

			&Accept=X - Specify the content type of the response.  
			In a browser, "text/html" is the default content type, but this parameter can be used to override 
			the content type on the response.
			
Note:  The behavior is identical to setting the Accept header on the request.  
			In fact, Juneau allows ANY HTTP request headers to be specified as URL parameters for debugging purposes.
	
	

		Using the plainText parameter, we can view the HTML as plain text...	  
	
	
	

		You'll notice that the HTML view has a simple stylesheet associated with it to improve the look of the interface.  
		It is possible to specify your own stylesheet, but the default styles will usually suffice for most purposes. 
	
	

		When accessed through a browser, the content type will default to HTML (based on the value of the Accept 
		HTTP header).  
	
	

		Let's use the &Accept URL parameter to override the Accept HTTP header to view this servlet 
		in other formats...
	
	

		In the case of JSON, we're serialize a single string, so it gets rendered as a JSON fragment....
	
	
	

		...or as XML...
	
	
	
	

		...or any of the other supported languages.
	
	

		If you click the OPTIONS link on the page, you'll see the results from an HTTP OPTIONS request:	  
	
	
	

		The OPTIONS page is a serialized Swagger DTO bean populated by introspection of the class itself combined with
			labels in the messages properties file and annotations.
		It's composed of a POJO that gets serialized just like any other POJO.  
		Therefore, the POJO can be serialized to any of the supported languages, like Swagger JSON.	  
	
	

	


3 - Class Hierarchy

	

		The class hierarchy for the REST servlet class is shown below:
	
	

		

			{@link javax.servlet.http.HttpServlet javax.servlet.http.HttpServlet} 
			

				

					{@link org.apache.juneau.rest.RestServlet org.apache.juneau.rest.RestServlet}
					
Contains all the main logic.
					

						

							{@link org.apache.juneau.rest.RestServletDefault org.apache.juneau.rest.RestServletDefault}
							
Provides a default set of serializers, parsers, options page, stylesheet, and other common settings.
							
Developers will typically subclass this when creating REST resources in JEE environments. 
							

								

									{@link org.apache.juneau.microservice.Resource org.apache.juneau.microservice.Resource}
									
Subclass intended to be used in REST microservices.
									
Developers will typically subclass this when creating microservices. 
								

									{@link org.apache.juneau.rest.RestServletGroupDefault org.apache.juneau.rest.RestServletGroupDefault}
									
A default implementation for "router" pages.
									

										

											{@link org.apache.juneau.microservice.ResourceGroup org.apache.juneau.microservice.ResourceGroup}
											
Subclass intended to be used in REST microservices.
									
								
								

									{@link org.apache.juneau.rest.remoteable.RemoteableServlet org.apache.juneau.rest.remoteable.RemoteableServlet}
									
REST servlet for implementing remoteable proxy interfaces.
							
						
					
				
			
		
	
	

		The servlets with RDF support require Jena on the classpath.  
		All other serializers and parsers do not have any external library dependencies.
		For this reason, we have separate servlets for supporting RDF so that you don't need Jena if you don't need to 
		support RDF. 
	
	

		The {@link org.apache.juneau.rest.RestRequest} and {@link org.apache.juneau.rest.RestResponse} classes 
		described later also extend from their servlet equivalents:
	
 
	

		

			{@link javax.servlet.http.HttpServletRequest javax.servlet.http.HttpServletRequest}
			

				

					{@link org.apache.juneau.rest.RestRequest org.apache.juneau.rest.RestRequest} 
					- Augmented with specialized REST methods.
			
		
 
		

			{@link javax.servlet.http.HttpServletResponse javax.servlet.http.HttpServletResponse}
			

				

					{@link org.apache.juneau.rest.RestResponse org.apache.juneau.rest.RestResponse} 
					- Augmented with specialized REST methods.
			
		
 
	




4 - REST Servlets

	

		Since REST servlets are subclasses of HttpServlet, they can be deployed in a J2EE container like any 
		other servlet, typically inside a web.xml file.
		The REST servlet framework does not depend on any classloader scanning or external setup other than 
		registering the servlet with the J2EE container.
	
	

		REST servlets can also be deployed by declaring them as children of other REST servlets (described later).
	
	

		A REST servlet consists of an instance of {@link org.apache.juneau.rest.RestServlet} annotated with 
		{@link org.apache.juneau.rest.annotation.RestResource @RestResource} containing public Java methods 
		annotated with {@link org.apache.juneau.rest.annotation.RestMethod @RestMethod}.
	
	

		Developers will typically subclass directly from {@link org.apache.juneau.rest.RestServletDefault}
		since it provides a default set of serializers and parsers for a variety of Accept and 
		Content-Type types.
	
	
	
Valid Accept headers for RestServletDefault
	

		

			
Accept
			
Content-Type
			
Serializer
		
		

			
application/json
text/json
			
application/json
			
{@link org.apache.juneau.json.JsonSerializer}
		
		

			
application/json+simple
text/json+simple
			
application/json
			
{@link org.apache.juneau.json.JsonSerializer.Simple}
		
		

			
application/json+schema
text/json+schema
			
application/json
			
{@link org.apache.juneau.json.JsonSchemaSerializer}
		
		

			
text/xml
			
text/xml
			
{@link org.apache.juneau.xml.XmlDocSerializer}
		
		

			
text/xml+schema
			
text/xml
			
{@link org.apache.juneau.xml.XmlSchemaDocSerializer}
		
		

			
text/html
	 		
text/html
			
{@link org.apache.juneau.html.HtmlDocSerializer}
		
		

			
text/html+stripped
			
text/html
			
{@link org.apache.juneau.html.HtmlStrippedDocSerializer}
		
		

			
text/uon
			
text/uon
			
{@link org.apache.juneau.uon.UonSerializer}
		
		

			
application/x-www-form-urlencoded
			
application/x-www-form-urlencoded
			
{@link org.apache.juneau.urlencoding.UrlEncodingSerializer}
		
		

			
text/xml+soap
			
text/xml
			
{@link org.apache.juneau.soap.SoapXmlSerializer}
		
		

			
text/plain
			
text/plain
			
{@link org.apache.juneau.plaintext.PlainTextSerializer}
		
		

			
application/x-java-serialized-object
			
application/x-java-serialized-object
			
{@link org.apache.juneau.jso.JsoSerializer}
		
	
	
	
Valid Content-Type headers for RestServletDefault
	

		

			
Content-Type
			
Parser
		
		

			
application/json
text/json
			
{@link org.apache.juneau.json.JsonParser}
		
		

			
text/xml
application/xml
			
{@link org.apache.juneau.xml.XmlParser}
		
		

			
text/html
text/html+stripped
			
{@link org.apache.juneau.html.HtmlParser}
		
		

			
text/uon
			
{@link org.apache.juneau.uon.UonParser}
		
		

			
application/x-www-form-urlencoded
			
{@link org.apache.juneau.urlencoding.UrlEncodingParser}
		
		

			
text/plain
			
{@link org.apache.juneau.plaintext.PlainTextParser}
		
	
	

 		{@link org.apache.juneau.rest.RestServletDefault} also provides a default OPTIONS page by implementing 
 		a {@link org.apache.juneau.rest.RestServletDefault#getOptions(RestRequest)} method that returns a POJO 
 		consisting of beans describing the class.
 		This is what produces the output for the OPTIONS page on the Hello World sample above.
	
	
	
Additional Information
	

		

			{@link org.apache.juneau.rest.RestServletDefault}
	

	
	
	
4.1 - REST Java Method Signature
	

		

			REST Java methods are identified on REST servlets using the 
			{@link org.apache.juneau.rest.annotation.RestMethod @RestMethod} annotation. 
			The annotation allows the framework to identify the available REST methods through reflection.
		
		

	/** GET request handler */
	@RestMethod(name=GET, path="/")
	public String sayHello() {
		return "Hello world!";
	}
		
		
		
Method Name
		

			There are no restrictions on the name of the Java method.  However, if you plan on making use of the 
			{@link org.apache.juneau.rest.annotation.RestResource#messages() @RestResource.messages()} annotation 
			(described later), the method names must be unique to make it possible to identify unique keys for labels 
			in the resource bundle.
			Therefore, you should not define two identically-named doFoo(...) methods that differ only by 
			parameters.
			If you're not using messages for NLS support, then name them whatever you want!
		
		
		
Method Return Type
		

			The return type can be any serializable POJO as defined in POJO Categories.
			It can also be void if the method is not sending any output (e.g. a request redirect) or is 
			setting the output using the {@link org.apache.juneau.rest.RestResponse#setOutput(Object)} method.
			Calling the {@link org.apache.juneau.rest.RestResponse#setOutput(Object)} method is functionally equivalent 
			to returning a value.
		
		

	// Equivalent method 1
	@RestMethod(name=GET)
	public void doGet(RestResponse res) {
		res.setOutput("Hello World!");
	}

 	// Equivalent method 2
	@RestMethod(name=GET)
	public String doGet() {
		return "Hello World!";
	}
		
		

			The return type can also be any of the following special object types:
		
		

			

				{@link java.io.InputStream}
				
The contents are simply piped to the output stream returned by 
				{@link org.apache.juneau.rest.RestResponse#getNegotiatedOutputStream()}.
				
Note that you should call {@link org.apache.juneau.rest.RestResponse#setContentType(String)} to set 
				the Content-Type header if you use this object type.
			

				{@link java.io.Reader}
				
The contents are simply piped to the output stream returned by 
				{@link org.apache.juneau.rest.RestResponse#getNegotiatedWriter()}.
				
Note that you should call {@link org.apache.juneau.rest.RestResponse#setContentType(String)} to set 
				the Content-Type header if you use this object type.
			

				{@link org.apache.juneau.rest.Redirect}
				
Represents an HTTP redirect response.
			

				{@link org.apache.juneau.Streamable}
				
Interface that identifies that an object can be serialized directly to an output stream.
			

				{@link org.apache.juneau.Writable}
				
Interface that identifies that an object can be serialized directly to a writer.
			

				{@link org.apache.juneau.utils.ZipFileList}
				
Special interface for sending zip files as responses.
		
		

			Additional "special types" can be defined through the {@link org.apache.juneau.rest.ResponseHandler} 
			interface (described later).
		
		
		
Method Parameters
		

			The method can contain any of the following parameters in any order:
		
		

			

				Parameters of the following class types:
				

					
Request/response objects:
						

							
{@link org.apache.juneau.rest.RestRequest} - The request object.
							
{@link javax.servlet.http.HttpServletRequest} - The superclass of RestRequest.
							
{@link org.apache.juneau.rest.RestResponse} - The response object.
							
{@link javax.servlet.http.HttpServletResponse} - The superclass of RestResponse.
						
					
Parsed request header values:
						

							
{@link org.apache.juneau.http.Accept}
							
{@link org.apache.juneau.http.AcceptCharset}
							
{@link org.apache.juneau.http.AcceptEncoding}
							
{@link org.apache.juneau.http.AcceptLanguage}
							
{@link org.apache.juneau.http.Authorization}
							
{@link org.apache.juneau.http.CacheControl}
							
{@link org.apache.juneau.http.Connection}
							
{@link org.apache.juneau.http.ContentLength}
							
{@link org.apache.juneau.http.ContentType}
							
{@link org.apache.juneau.http.Date}
							
{@link org.apache.juneau.http.Expect}
							
{@link org.apache.juneau.http.From}
							
{@link org.apache.juneau.http.Host}
							
{@link org.apache.juneau.http.IfMatch}
							
{@link org.apache.juneau.http.IfModifiedSince}
							
{@link org.apache.juneau.http.IfNoneMatch}
							
{@link org.apache.juneau.http.IfRange}
							
{@link org.apache.juneau.http.IfUnmodifiedSince}
							
{@link org.apache.juneau.http.MaxForwards}
							
{@link org.apache.juneau.http.Pragma}
							
{@link org.apache.juneau.http.ProxyAuthorization}
							
{@link org.apache.juneau.http.Range}
							
{@link org.apache.juneau.http.Referer}
							
{@link org.apache.juneau.http.TE}
							
{@link org.apache.juneau.http.UserAgent}
							
{@link org.apache.juneau.http.Upgrade}
							
{@link org.apache.juneau.http.Via}
							
{@link org.apache.juneau.http.Warning}
							
{@link java.util.TimeZone}
						
					
Direct streams on request/response:
						

							
{@link java.io.InputStream}
							
{@link javax.servlet.ServletInputStream}
							
{@link java.io.Reader}
							
{@link java.io.OutputStream}
							
{@link javax.servlet.ServletOutputStream}
							
{@link java.io.Writer}
						
					
Localization:
						

							
{@link java.util.ResourceBundle} - Client-localized resource bundle.
							
{@link org.apache.juneau.utils.MessageBundle} - A resource bundle with additional features.
							
{@link java.util.Locale} - Client locale.
						
					
Request APIs:
						

							
{@link org.apache.juneau.rest.RequestHeaders} - API for accessing request headers.
							
{@link org.apache.juneau.rest.RequestQuery} - API for accessing request query parameters.
							
{@link org.apache.juneau.rest.RequestFormData} - API for accessing request form data.
							
{@link org.apache.juneau.rest.RequestPathMatch} - API for accessing path variables.
							
{@link org.apache.juneau.rest.RequestBody} - API for accessing request body.
						
					
Other:
						

							
{@link org.apache.juneau.http.HttpMethod} - The method name matched (when using @RestMethod(name="*"))
							
{@link java.util.logging.Logger} - The logger to use for logging.
							
{@link org.apache.juneau.internal.JuneauLogger} - Logger with additional features.
							
{@link org.apache.juneau.rest.RestContext} - The resource read-only context.
							
{@link org.apache.juneau.parser.Parser} - The parser matching the request content type.
							
{@link org.apache.juneau.dto.swagger.Swagger} - The auto-generated Swagger doc.
							
{@link org.apache.juneau.ini.ConfigFile} - The external config file for the resource.
						
				
			

				Annotated parameters:
				

					
{@link org.apache.juneau.rest.annotation.Path @Path} - Variables in matched URL path patterns.
					
{@link org.apache.juneau.rest.annotation.FormData @FormData} - Multipart form post parameter values.
					
{@link org.apache.juneau.rest.annotation.HasFormData @HasFormData} - Denotes whether the form data parameter exists.
					
{@link org.apache.juneau.rest.annotation.Query @Query} - Query parameters.  Using this prevents the HTTP body from being processed as a URL-Encoded form post.
					
{@link org.apache.juneau.rest.annotation.HasQuery @HasQuery} - Denotes whether the query parameter exists.
					
{@link org.apache.juneau.rest.annotation.Header @Header} - A header value.
					
{@link org.apache.juneau.rest.annotation.Method @Method} - The HTTP method name. 
					
{@link org.apache.juneau.rest.annotation.PathRemainder @PathRemainder} - The remainder value after path pattern match.
					
{@link org.apache.juneau.rest.annotation.Body @Body} - The HTTP content parsed as a POJO.
					
{@link org.apache.juneau.rest.annotation.Messages @Messages} - The resource bundle for the servlet localized to the language on the request.
					
{@link org.apache.juneau.rest.annotation.Properties @Properties} - The serializer/parser/servlet properties so they can be read or altered on the request.
				
		
		

	// Example GET request using annotated attributes
	@RestMethod(name=GET, path="/example1/{a1}/{a2}/{a3}/*")
	public String doGetExample1(
		RestRequest req,
		RestResponse res,
		@Method String method,
		@Path String a1,
		@Path int a2,
		@Path UUID a3,
		@Query("p1") int p1,
		@Query("p2") String p2,
		@Query("p3") UUID p3,
		@HasQuery("p3") boolean hasP3,
		@PathRemainder String remainder,
		@Header("Accept-Language") String lang,
		@Header("Accept") String accept,
		@Header("DNT") int doNotTrack,
		@Properties ObjectMap properties,
		@Messages ResourceBundle nls
	) {
		// Do something with all of those
	}
		
		

			All the annotated parameters (with the exception of @Body) can be any POJO type convertible from a 
			String.
			(See POJOs Convertible From String)
		
		

			For example, headers can be accessed as Strings or UUIDs...
		
		

	// Example GET with access to HTTP headers
	@RestMethod(name=GET, path="/*")
	public String doGet(@Header("Accept-Language") String lang, @Header("ETag") UUID eTag) throws Exception {
		...
	}
		
		

			All annotations have programmatic equivalents on the {@link org.apache.juneau.rest.RestRequest} class.
		
		
		
		
		
4.1.1 - Path
		

			

				The {@link org.apache.juneau.rest.annotation.RestMethod#path() @RestMethod.path()} annotation allows 
				you to define URL path patterns to match against.
				These patterns can contain variables of the form "{xxx}" that can be passed in directly to the
				Java methods as extra parameters.
			
			

				In the following example, 3 separate GET request handlers are defined with different path patterns.
				Note how the variables are passed in as additional arguments on the method, and how those arguments are 
				automatically converted to the specified class type...
			
			

	// Default method
	@RestMethod(name=GET, path="/*")
	public void doGetDefault() {
		...
	}

	// Method with path pattern
	@RestMethod(name=GET, path="/xxx")
	public void doGetNoArgs(...) {
		...
	}

	// Method with path pattern with arguments
	@RestMethod(name=GET, path="/xxx/{foo}/{bar}/{baz}/{bing}")
	public void doGetWithArgs(@Path String foo, @Path int bar, @Path MyEnum baz, @Path UUID bing) {
		...
	}
			
			

				By default, path patterns are matched using a best-match heuristic. 
				When overlaps occur, URLs are matched from most-specific to most-general order:
			
			

	// Try first 
	@RestMethod(name=GET, path="/foo/bar")
	public void method1() {
		...
	}

	// Try second
	@RestMethod(name=GET, path="/foo/{bar}")
	public void method2(...) {
		...
	}

	// Try third
	@RestMethod(name=GET, path="/foo/*")
	public void method3(...) {
		...
	}

	// Try last
	@RestMethod(name=GET, path="/*")
	public void method4(...) {
		...
	}
			
			

				The match heuristic behavior can be overridden by the 
				{@link org.apache.juneau.rest.annotation.RestMethod#priority() @RestMethod.priority()} annotation 
				property.
				However, in practice this is almost never needed.
			
			

				Paths that end with "/*" will do a prefix match on the incoming URL.  
				Any remainder after the match can be accessed through 
				{@link org.apache.juneau.rest.RequestPathMatch#getRemainder()} or parameters with the 
				{@link org.apache.juneau.rest.annotation.PathRemainder @PathRemainder} annotation.
				On the other hand, paths that don't end with "/*" (e.g. "/" or "/foo") will 
				require an exact URL match, and if any remainder exists, a 404 (not found) error will be thrown.
			
			

				The following example shows the distinction.
			
			

	@RestMethod(name=GET, path="/*")
	public void doGet(@PathRemainder String remainder) {
		// URL path pattern can have remainder accessible through req.getRemainder().
	}

	@RestMethod(name=PUT, path="/")
	public void doPut() {
		// URL path pattern must match exactly and will cause a 404 error if a remainder exists.
	}
			
			

				Annotations are provided for easy access to URL parameters with automatic conversion to any parsable object type.
				For example, the following example can process the URL "/urlWithParams?foo=foo&bar=[1,2,3]&baz=067e6162-3b6f-4ae2-a171-2470b63dff00"...
			
			

	// Example GET request with access to query parameters
	@RestMethod(name=GET, path="/urlWithParams")
	public String doGetWithParams(@Query("foo") String foo, @Query("bar") int bar, @Query("baz") UUID baz) throws Exception {
		return "GET /urlWithParams?foo="+foo+"&bar="+bar+"&baz="+baz);
	}
			
		
		
		
		
		
4.1.2 - Matchers
		

			

				{@link org.apache.juneau.rest.RestMatcher RestMatchers} are used to allow multiple Java methods to be 
				tied to the same HTTP method and path, but differentiated by some request attribute such as a specific 
				header value.
			
			

	// GET method that gets invoked for administrators
	@RestMethod(name=GET, path="/*", matchers=IsAdminMatcher.class)
	public Object doGetForAdmin() {
		...
	}

	// GET method that gets invoked for everyone else
	@RestMethod(name=GET, path="/*")
	public Object doGetForEveryoneElse() {
		...
	}
			
			

				The interface for matchers is simple:
			
			

	public class IsAdminMatcher extends RestMatcher {
		@Override
		public boolean matches(RestRequest req) {
			return req.isUserInRole("ADMINS_GROUP");
		}
	}
			
			
			
Other Notes
			

				

					If no methods are found with a matching matcher, a 412 Precondition Failed status is returned.
				

					If multiple matchers are specified on the same method, ONLY ONE matcher needs to match for the 
					method to be invoked.
				

					Note that you CANNOT define identical paths on different methods UNLESS you use matchers.
					
That includes paths that are only different in variable names (e.g. "/foo/{bar}" and 
					"/foo/{baz}").
					
If you try to do so, a ServletException will be thrown on startup.
				

					Methods with matchers take precedence over methods without.
					
Otherwise, methods are attempted in the order they appear in the class.
			
		
	

	
	
	
4.2 - Request Content
	

		

			Annotations are provided for easy access to HTTP body content as any parsable POJO type
			(See POJO Categories).
			In the example below, we're POSTing beans.
		
		

	// Example POST of a bean
	@RestMethod(name=POST, path="/")
	public void doPost(@Body Person person) throws Exception {
		// Do something with person.
	}
		
		

			The HTTP body of a request can be retrieved as a parsed POJO using either the 
			{@link org.apache.juneau.rest.RestRequest#getBody()} method, or a parameter annotated with 
			{@link org.apache.juneau.rest.annotation.Body @Body}.
		
		

	// Equivalent method 1
	@RestMethod(name=POST, path="/example1")
	public void doPost1(@Body Person p) {
		// Do something with p.
	}

	// Equivalent method 2
	@RestMethod(name=POST, path="/example2")
	public void doPost2(RestRequest req) {
		Person p = req.getBody).asType(Person.class);
		// Do something with p.
	}
		
		

			The Juneau framework will automatically determine the appropriate Parser to use based on the 
			Content-Type HTTP header.  
			So the body content could be JSON or XML or any other supported parsing types.
		
		
		
		
		
4.2.1 - Form Posts
		
	
			

				URL-Encoded form posts require their own topic since they can be handled in multiple ways.
			
			

				The best way to handle a form post is by using an input bean.
				The samples include a UrlEncodedFormResource class that takes in URL-Encoded form post of the 
				form "aString=foo&aNumber=123&aDate=2001-07-04T15:30:45Z".
				The code is shown here:
			
			
				
	@RestResource(
		path="/urlEncodedForm"
	)
	public class UrlEncodedFormResource extends Resource {

		/** POST request handler */
		@RestMethod(name=POST, path="/")
		public Object doPost(@Body FormInputBean input) throws Exception {
			// Just mirror back the request
			return input;
		}
	
		public static class FormInputBean {
			public String aString;
			public int aNumber;
			@BeanProperty(pojoSwaps=CalendarSwap.ISO8601DT.class)
			public Calendar aDate;
		}
	}		
			
	
			

				Another possibility is to access the form parameters individually:	
			
	
			

	/** POST request handler */
	@RestMethod(name=POST, path="/")
	public Object doPost(@FormData("aString") String aString, @FormData("aNumber") int aNumber, @FormData("aDate") Calendar aDate) throws Exception {
		...
	}
			
			

				The advantage to the form input bean is that it can handle any of the parsable types (e.g. JSON, XML...) 
				in addition to URL-Encoding.  The latter approach only supports URL-Encoding.
			
			

				

					If you're using form input beans, DO NOT use the @FormData attribute or 
					{@link org.apache.juneau.rest.RestRequest#getParameter(String)} method since this will cause the 
					underlying JEE servlet to parse the HTTP body as a form post.
					
Your input bean will end up being null since there won't be any content left after the servlet 
					has parsed the body of the request.
					
This applies to WHENEVER you use @Body or {@link org.apache.juneau.rest.RestRequest#getBody()}
			
		

		
		
		
4.2.2 - Multipart Form Posts
		

			

				The Juneau framework does not natively support multipart form posts.  
				However, it can be used in conjunction with the Apache Commons File Upload library to do so.
			
	
			

				The samples include a TempDirResource class that uses the File Upload library to allow files to 
				be uploaded as multipart form posts.
			
			

	@RestResource(
		path="/tempDir"
	)
	public class TempDirResource extends DirectoryResource {
	
		/**
		 * [POST /upload] - Upload a file as a multipart form post.
		 * Shows how to use the Apache Commons ServletFileUpload class for handling multi-part form posts.
		 */
		@RestMethod(name=POST, path="/upload", matchers=TempDirResource.MultipartFormDataMatcher.class)
		public Redirect uploadFile(RestRequest req) throws Exception {
			ServletFileUpload upload = new ServletFileUpload();
			FileItemIterator iter = upload.getItemIterator(req);
			while (iter.hasNext()) {
				FileItemStream item = iter.next();
				if (item.getFieldName().equals("contents")) { 
					File f = new File(getRootDir(), item.getName());
					IOPipe.create(item.openStream(), new FileOutputStream(f)).closeOut().run();
				}
			}
			return new Redirect(); // Redirect to the servlet root.
		}
	
		/** Causes a 404 if POST isn't multipart/form-data */
		public static class MultipartFormDataMatcher extends RestMatcher {
			@Override /* RestMatcher */
			public boolean matches(RestRequest req) {
				String contentType = req.getContentType();
				return contentType != null && contentType.startsWith("multipart/form-data"); 
			}
		}
			
		
	

	
	
	
4.3 - Response Content
	

		

			REST Java methods can generate output in any of the following ways:
		
		

			

				By returning a serializable POJO, or any of the following:
				
{@link java.io.Reader}, {@link java.io.InputStream}, {@link org.apache.juneau.Streamable}, 
				{@link org.apache.juneau.Writable} 
			

				By calling {@link org.apache.juneau.rest.RestResponse#setOutput(Object)} with any of the types above.
			

				By accessing the {@link java.io.Writer} directly by calling 
				{@link org.apache.juneau.rest.RestResponse#getNegotiatedWriter()} and writing the output yourself.
		
		

	// Equivalent method 1
	@RestMethod(name=GET, path="/example1/{personId}")
	public Person doGet1(@Path UUID personId) {
		Person p = getPersonById(personId);
		return p;
	}

	// Equivalent method 2
	@RestMethod(name=GET, path="/example2/{personId}")
	public void doGet2(RestResponse res, @Path UUID personId) {
		Person p = getPersonById(personId);
		res.setOutput(p);
	}

	// (Sorta) Equivalent method 3
	// (Ignores any converters or method-level properties)
	@RestMethod(name=GET, path="/example3/{personId}")
	public void doGet3(RestRequest req, RestResponse res, @Path UUID personId) {
		Person p = getPersonById(personId);
		String accept = req.getHeader("Accept", "text/json");
		WriterSerializer s = res.getSerializerGroup().getWriterSerializer(accept);
		res.setContentType(s.getResponseContentType());
		s.serialize(p, res.getNegotiatedWriter());
	}
		
	

	
	
	
4.4 - Lifecycle Hooks
	

		

			Lifecycle hooks allow you to hook into lifecycle events of the servlet or REST call.
			Like @RestMethod methods, the list of parameters are specified by the developer.
		
		

			For example, if you want to add an initialization method to your resource:
		
		

	@RestResource(...)
	public class MyResource  {

		// Our database.
		private Map<Integer,Object> myDatabase;

		@RestHook(INIT)
		public void initMyDatabase(RestConfig config) throws Exception {
			myDatabase = new LinkedHashMap<>();
		}
	}
		
		

			Or if you want to intercept REST calls:
		
		

	@RestResource(...)
	public class MyResource {

		// Add a request attribute to all incoming requests.
		@RestHook(PRE_CALL)
		public void onPreCall(RestRequest req) {
			req.setAttribute("foo", "bar");
		}
	}
		
		

			The hook events can be broken down into two categories:
		
		

			
Resource lifecycle events:
				

					
{@link org.apache.juneau.rest.annotation.HookEvent#INIT INIT} - Right before initialization.
					
{@link org.apache.juneau.rest.annotation.HookEvent#POST_INIT POST_INIT} - Right after initialization.
					
{@link org.apache.juneau.rest.annotation.HookEvent#POST_INIT_CHILD_FIRST POST_INIT_CHILD_FIRST} - Right after initialization, but run child methods first.
					
{@link org.apache.juneau.rest.annotation.HookEvent#DESTROY DESTROY} - Right before servlet destroy.
				
			
REST call lifecycle events:
				

					
{@link org.apache.juneau.rest.annotation.HookEvent#START_CALL START_CALL} - At the beginning of a REST call.
					
{@link org.apache.juneau.rest.annotation.HookEvent#PRE_CALL PRE_CALL} - Right before the @RestMethod method is invoked.
					
{@link org.apache.juneau.rest.annotation.HookEvent#POST_CALL POST_CALL} - Right after the @RestMethod method is invoked.
					
{@link org.apache.juneau.rest.annotation.HookEvent#END_CALL END_CALL} - At the end of the REST call after the response has been flushed.
				
		
	
	
		
Additional Information
		

			

		 		{@link org.apache.juneau.rest.annotation.RestHook @RestHook}
		
	
	
	

	
	
	
4.5 - OPTIONS Pages
	

		

			One of the most useful features of Juneau is that it can produce OPTIONS pages for self-documenting designs 
			(i.e. REST interfaces that document themselves).
		
		
		
OPTIONS page for HelloWorld sample resource
	 	
		

			This page is constructed through reflection on the servlet class and it's methods, combined with 
			information provided in the following locations:
		
		

			
Annotations (i.e. {@link org.apache.juneau.rest.annotation.RestResource @RestResource} and 
				{@link org.apache.juneau.rest.annotation.RestMethod @RestMethod}).
			
Resource bundle properties.
			
Swagger JSON files.
		
		

			Swagger JSON files are specified with the same name as the servlet 
			(e.g. MyResource.java -> MyResource.json).
			Localized versions of Swagger JSON files can be specified by appending the locale to the file name 
			(e.g. MyResource_ja_JP.json).
			The existence of Swagger JSON files will override any auto-generation of the OPTIONS pages.
			This allows you to fully control the contents of the OPTIONS page with your own Swagger spec.
		
		

			The framework takes the information above and populates a {@link org.apache.juneau.dto.swagger.Swagger} bean.
			This bean is then serialized just like any other POJO to produce the page shown above.
		
		

	 		{@link org.apache.juneau.rest.RestServletDefault} provides a default OPTIONS page by implementing 
	 		a {@link org.apache.juneau.rest.RestServletDefault#getOptions(RestRequest)} method that returns a POJO 
	 		consisting of beans describing the class.
	 		It uses the {@link org.apache.juneau.rest.RestRequest#getSwagger()} method that returns a localized swagger 
	 		bean.
	 	
	 	

	/**
	 * [OPTIONS /*] - Show resource options.
	 *
	 * @param req The HTTP request.
	 * @return A bean containing the contents for the OPTIONS page.
	 */
	@RestMethod(name=OPTIONS, path="/*",
		summary="Resource options",
		htmldoc=@HtmlDoc(
			navlinks={
				"back: servlet:/,",
				"json: servlet:/?method=OPTIONS&Accept=text/json&plainText=true"
			}
		)
	)
	public Swagger getOptions(RestRequest req) {
		return req.getSwagger();
	}
	 	
	 	
	 	
Title and Description
	 	

	 		The title and description can be defined in the following ways.
	 	
	 	

	 		
Annotations:  {@link org.apache.juneau.rest.annotation.RestResource#title()}, 
	 			{@link org.apache.juneau.rest.annotation.RestResource#description()}
	 		
By overriding methods on the servlet class:  
	 			{@link org.apache.juneau.rest.RestInfoProvider#getTitle(RestRequest)}, 
	 			{@link org.apache.juneau.rest.RestInfoProvider#getDescription(RestRequest)} 
	 		
By defining properties in the resource bundle.
	 		
By specifying them in a Swagger JSON file.
	 	
		

	 		If you don't care about internationalization, then the easiest way is to use annotations on the servlet.
	 	
		

	@RestResource(
		path="/example",
		title="Example Resource",
		description="This shows how to use labels and descriptions."
	)
	public class ExampleResource extends RestServletDefault {
		
	 	
		

			The second approach which supports internationalization is to use the 
			{@link org.apache.juneau.rest.annotation.RestResource#messages() @RestResource.messages()} annotation to 
			point to a resource bundle, and then use predefined properties that identify the label and description.
		
		

	@RestResource(
		messages="nls/Messages"
	)
	public class ExampleResource extends RestServletDefault {
		
	 	
		

			The title and description are specified as special properties in the resource bundle:
		
		

	#--------------------------------------------------------------------------------
	# Contents of Messages.properties
	#--------------------------------------------------------------------------------
	title = Example Resource
	description = This shows how to use labels and descriptions.
		
	 	
		

			Message keys can optionally be prefixed by the short class name if the resource bundle is shared by 
			multiple servlets:
		
		

	#--------------------------------------------------------------------------------
	# Contents of Messages.properties
	#--------------------------------------------------------------------------------
	ExampleResource.title = Example Resource
	ExampleResource.description = This shows how to use labels and descriptions.
		
	 	
	 	

	 		When both annotations and properties are used, annotations take precedence.
	 	
	 	

	 		The localized label and description are also available through the following methods:
		
	 	

	 		

	 			{@link org.apache.juneau.rest.RestRequest#getServletTitle()}
	 		

	 			{@link org.apache.juneau.rest.RestRequest#getServletDescription()}
	 	
		

	 		They are also made available as the request string variables "$R{servletTitle}" and 
	 		"$R{servletDescription}".
	 		These variable facilitate the localized label and descriptions on the HTML pages when using 
	 		{@link org.apache.juneau.rest.RestServletDefault}:
		
		

	@RestResource(
		pageTitle="The title for this page is $R{servletTitle}",
		pageText="The description for this page is $R{servletDescription}"
	)
	public abstract class RestServletDefault extends RestServlet {
	 	
	 	

	 		The title and description annotations support string variables.
	 		So in theory, you could also provide localized messages using "$L" variables pointing to your own 
	 		resource bundle properties:
	 	
		

	@RestResource(
		path="/example",
		messages="nls/Messages"
		title="$L{my.resource.label}",
		description="$L{my.resource.description}"
	)
	public class ExampleResource extends RestServletDefault {
		
		

			Another option is to override the {@link org.apache.juneau.rest.RestInfoProvider#getTitle(RestRequest)} 
			and {@link org.apache.juneau.rest.RestInfoProvider#getDescription(RestRequest)} methods.
		
	
		 	
	 	
Method Description, Input, and Responses
	 	

	 		The methods field in the OPTIONS page is mostly populated through reflection.
	 		However, the description, input, and responses field can be specified through either annotations or 
	 		resource properties. 
	 	
	 	

	 		For example, the AddressBookResource has a getPerson() method
	 			that gets rendered in the OPTIONS page like so...
	 	
		
		

			This method is described through the 
			{@link org.apache.juneau.rest.annotation.RestMethod#description() @RestMethod.description()}, 
			{@link org.apache.juneau.rest.annotation.RestMethod#swagger() @RestMethod.swagger()},
			and {@link org.apache.juneau.rest.annotation.MethodSwagger @MethodSwagger} annotations.
		
		

	@RestMethod(
		name=GET, 
		path="/people/{id}/*", 
		converters={Traversable.class,Queryable.class,Introspectable.class}, 
		description="Get a person by id in the address book",
		parameters={
			@Parameter(in="path", name="id", description="Person UUID")
		},
		responses={
			@Response(value=200, description="Person bean"),
			@Response(value=404, description="Person with specified id not found")
		}
	)
	public Person getPerson(@Path int id) throws Exception {
		return findPerson(id);
	}
		
 	
		

			These labels can also be localized by instead specifying them in the servlet properties file:		
		
		
		

	@RestMethod(
		name=GET, 
		path="/people/{id}/*", 
		converters={Traversable.class,Queryable.class,Introspectable.class}
		// Don't specify annotations for labels...they'll be detected in resource bundle. 
	)
	public Person getPerson(@Path int id) throws Exception {
		return findPerson(id);
	}
		
 	
		

	#--------------------------------------------------------------------------------
	# Contents of AddressBookResource.properties
	#--------------------------------------------------------------------------------
	getPerson.summary = Get a person by id in the address book
	getPerson.req.path.id.description = Person UUID
	getPerson.res.200.description = Person found
	getPerson.res.404.description = Person with specified id not found
		
		
		

			The following table shows the predefined resource bundle message property names:
		
		

			

				
Property
				
Description
				
Equivalent Annotation
				
Equivalent Method
			
			

				
label
				
Servlet label
				
{@link org.apache.juneau.rest.annotation.RestResource#title() @RestResource.title()}
				
{@link org.apache.juneau.rest.RestInfoProvider#getTitle(RestRequest)}
			
			

				
description
				
Servlet description
				
{@link org.apache.juneau.rest.annotation.RestResource#description() @RestResource.description()}
				
{@link org.apache.juneau.rest.RestInfoProvider#getDescription(RestRequest)}
			
			

				
[javaMethodName].summary
				
Java method summary
				
{@link org.apache.juneau.rest.annotation.RestMethod#summary() @RestMethod.summary()}
			
			

				
[javaMethodName].description
				
Java method description
				
{@link org.apache.juneau.rest.annotation.RestMethod#description() @RestMethod.description()}
			
			

				
[javaMethodName].req.body.description
				

					A description of the HTTP request body.
				
				
{@link org.apache.juneau.rest.annotation.MethodSwagger#parameters() @MethodSwagger.parameters()}
			
			

				
[javaMethodName].req.[category].[name].description
				

					A request input variable.
					
Categories: path, query, formData, header
				
				
{@link org.apache.juneau.rest.annotation.MethodSwagger#parameters() @MethodSwagger.parameters()}
			
			

				
[javaMethodName].res.[code].description
				

					A possible HTTP response code and description.
				
				
{@link org.apache.juneau.rest.annotation.MethodSwagger#responses() @MethodSwagger.responses()}
			
			

				
[javaMethodName].res.[code].body.description
				

					A description of response content for the specified HTTP response.
				
				
{@link org.apache.juneau.rest.annotation.MethodSwagger#responses() @MethodSwagger.responses()}
			
			

				
[javaMethodName].res.[code].header.[name].description
				

					A response header.
				
				
{@link org.apache.juneau.rest.annotation.MethodSwagger#responses() @MethodSwagger.responses()}
			
		
		
		
Additional Information
		

			

				{@link org.apache.juneau.rest.annotation.RestMethod#description() @RestMethod.description()}
			

				{@link org.apache.juneau.rest.annotation.MethodSwagger#parameters() @MethodSwagger.parameters()}
			

				{@link org.apache.juneau.rest.annotation.MethodSwagger#responses() @MethodSwagger.responses()}
		
	

	
	
	
4.6 - Serializers
	

		

			REST servlets use the {@link org.apache.juneau.serializer.Serializer} API for defining serializers for 
			serializing response POJOs.
		
		

			The servlet will pick which serializer to use by matching the request Accept header with the
			media types defined through the {@link org.apache.juneau.serializer.Serializer#getMediaTypes()} method.
		
		

			Serializers can be associated with REST servlets in the following ways:
		
		

			

				{@link org.apache.juneau.rest.annotation.RestResource#serializers() @RestResource.serializers()} 
				- Annotation on servlet class.
			

				{@link org.apache.juneau.rest.annotation.RestMethod#serializers() @RestMethod.serializers()} 
				- Annotation on individual servlet methods.
			

				{@link org.apache.juneau.rest.RestConfig#addSerializers(Class[])} 
				- Override method to set the serializers programmatically.
		
		

			The following are equivalent ways of defining serializers used by a servlet...
		
 		
		

	// Example #1 - Serializers defined on servlet through annotation
	@RestResource(
		serializers={JsonSerializer.class, XmlSerializer.class}
	)
	public MyRestServlet extends RestServlet {
		...
	}

 	// Example #2 - Serializers defined on method through annotation
 	@RestMethod(name=GET, path="/*"
 		serializers={JsonSerializer.class, XmlSerializer.class}
 	)
	public Object doGet() {
 		...
	}

	// Example #3 - Serializers defined on servlet by overriding the createSerializers(ObjectMap,Class[],Class[]) method
	@Override
	public SerializerGroupBuilder createSerializers(ObjectMap,Class[],Class[]) {

 		return new SerializerGroupBuilder()
 			.append(JsonSerializer.class, XmlSerializer.class);
	}
		
		

			

				When debugging the output from REST servlets, it's almost always easier to bypass the REST servlet and 
				try to serialize the POJOs using the serializers directly using the 
				{@link org.apache.juneau.serializer.WriterSerializer#toString(Object)} method.
		
		
		
Additional Information
		

			

				{@link org.apache.juneau.rest.annotation.RestMethod#serializersInherit() @RestMethod.serializersInherit()}
				
Controls how serializers are inherited from the servlet class.
		
	
	
	
	
	
4.7 - Parsers
	

		

			REST servlets use the {@link org.apache.juneau.parser.Parser} API for defining parsers for parsing request
			body content and converting them into POJOs.
		
		

			The servlet will pick which parser to use by matching the request Content-Type header with the
			media types defined through the {@link org.apache.juneau.parser.Parser#getMediaTypes()} method.
		
		

			Parsers can be associated with REST servlets in the following ways:
		
		

			

				{@link org.apache.juneau.rest.annotation.RestResource#parsers() @RestResource.parsers()} 
				- Annotation on servlet class.
			

				{@link org.apache.juneau.rest.annotation.RestMethod#parsers() @RestMethod.parsers()} 
				- Annotation on individual servlet methods.
			

				{@link org.apache.juneau.rest.RestConfig#addParsers(Class[])} 
				- Override method to set the parsers programmatically.
		
		

			The following are equivalent ways of defining parsers used by a servlet...
		
		

		// Example #1 - Parsers defined on servlet through annotation
		@RestResource(
			parsers={JsonParser.class, XmlParser.class}
		)
		public MyRestServlet extends RestServlet {
			...
		}
	
	 	// Example #2 - Parsers defined on method through annotation
	 	@RestMethod(name=GET, path="/*"
			parsers={JsonParser.class, XmlParser.class}
		)
		public void doPut(@Body Foo input) {
			...
		}
	
		// Example #3 - Parsers defined on servlet by overriding the getParserGroup method
		@Override
		public ParserGroupBuilder getParserGroup() {
	
	 		return new ParserGroupBuilder()
				.append(JsonParser.class, XmlParser.class);
	 	}
		
		
		
Additional Information
		

			

				{@link org.apache.juneau.rest.annotation.RestMethod#parsersInherit() @RestMethod.parsersInherit()} 
				
Controls how parsers are inherited from the servlet class.
		
	

	
	
	
4.8 - Properties
	

		

			The Juneau serializers and parsers are highly-configurable through properties.
			(See Configurable Properties)
		
		

			There are several ways of defining properties in the REST API.
			The most common way is going to be through the 
			{@link org.apache.juneau.rest.annotation.RestResource#properties() @RestResource.properties()}
			and {@link org.apache.juneau.rest.annotation.RestMethod#properties() @RestMethod.properties()} annotations.
		
		

			The {@link org.apache.juneau.rest.annotation.RestResource#properties() @RestResource.properties()} 
			annotation can be used as a convenient way to set various serializer and parser properties to all 
			serializers and parsers registered with the servlet.
		
		

	import static org.apache.juneau.SerializerContext.*;
	import static org.apache.juneau.xml.XmlSerializerContext.*;
	import static org.apache.juneau.rest.serializers.HtmlSerializerContext.*;

	// Servlet with properties applied
	@RestResource(
		properties={
			// Nulls should not be serialized
			@Property(name=TRIM_NULLS, value="true"),

			// Empty lists should not be serialized
			@Property(name=SERIALIZER_trimEmptyLists, value="true"),

			// Specify the default namespaces for the XML serializer
			@Property(name=XML_defaultNamespaceUriS,
				value="{jp06:'http://jazz.net/xmlns/prod/jazz/process/0.6/',jp:'http://jazz.net/xmlns/prod/jazz/process/1.0/'}"),

			// Specify a default title for the HtmlSerializer serializer
			// This is equivalent to @RestResource(title/pageTitle)
			@Property(name=HTMLDOC_title, value="My resource")
		}
	)
	public MyRestServlet extends RestServlet {
		...
	}
		
		

			The {@link org.apache.juneau.rest.annotation.RestMethod#properties() @RestMethod.properties()} annotation 
			can be used to define method-level properties that can alter the behavior of serializers and parsers at the 
			method level only.
		
		

	// GET method with method-level properties
	@RestMethod(
		name=GET, path="/*",
		properties={
			// Nulls should not be serialized
			@Property(name=TRIM_NULLS, value="true"),

			// Empty lists should not be serialized
			@Property(name=SERIALIZER_trimEmptyLists, value="true"),

			// Specify the default namespaces for the XML serializer
			@Property(name=XML_defaultNamespaceUriS,
				value="{jp06:'http://jazz.net/xmlns/prod/jazz/process/0.6/',jp:'http://jazz.net/xmlns/prod/jazz/process/1.0/'}"),

			// Specify a default title for the HtmlSerializer serializer
			// This is equivalent to @RestMethod(pageTitle)
			@Property(name=HTMLDOC_title, value="My resource")
		}
	public Object doGet() {
		...
	}
		
		

			In particular, the {@link org.apache.juneau.rest.RestContext} class has a variety of properties for 
			controlling the behavior of the {@link org.apache.juneau.rest.RestServlet} class itself.
		
		

			There are also ways to provide properties programmatically.
		
		

			

				By overriding the {@link org.apache.juneau.rest.RestConfig#setProperties(Map)} method.
			

				By overriding the {@link org.apache.juneau.rest.RestConfig#addSerializers(Class[])} and 
				{@link org.apache.juneau.rest.RestConfig#addParsers(Class[])} methods and setting properties on the 
				serializers and parsers directly.
			
		
		
		
Additional Information
		

			

				{@link org.apache.juneau.rest.RestContext}
				
Properties associated with the {@link org.apache.juneau.rest.RestServlet} class.
			

				{@link org.apache.juneau.rest.annotation.RestMethod#serializersInherit @RestMethod.serializersInherit()} 
				
Controls how serializers inherit properties from the servlet class.
			

				{@link org.apache.juneau.rest.annotation.RestMethod#parsersInherit @RestMethod.parsersInheritInherit()} 
				
Controls how parsers inherit properties from the servlet class.
		
	
	
	
	
	
4.9 - Transforms
	

		

			The Juneau serializers and parsers can be configured on how to handle POJOs through the use of Transforms.
			(See Transforms)
		
		

			The {@link org.apache.juneau.rest.annotation.RestResource#beanFilters() @RestResource.beanFilters()} 
			and {@link org.apache.juneau.rest.annotation.RestResource#pojoSwaps() @RestResource.pojoSwaps()} annotations 
			can be used as a convenient way to add bean filters and POJO swaps to the serializers and parsers
			registered with the servlet.
		
		

	// Servlet with transforms applied
	@RestResource(
		pojoSwaps={
			// Calendars should be serialized/parsed as ISO8601 date-time strings
			CalendarSwap.DEFAULT_ISO8601DT.class,

			// Byte arrays should be serialized/parsed as BASE64-encoded strings
			ByteArrayBase64Swap.class,
		},
		beanFilters={
			// Subclasses of MyInterface will be treated as MyInterface objects.
			// Bean properties not defined on that interface will be ignored.
			MyInterface.class
		}
	)
	public MyRestServlet extends RestServlet {
		...
	}
		
		

			{@link org.apache.juneau.rest.annotation.RestMethod#beanFilters() @RestMethod.beanFilters()} and 
			{@link org.apache.juneau.rest.annotation.RestMethod#pojoSwaps() @RestMethod.pojoSwaps()}
			are the equivalent annotations for individual Java methods.
		
		

			Transforms can also be defined programmatically through the following:
		
		

			

				By overriding the {@link org.apache.juneau.rest.RestConfig#addBeanFilters(Class[])} and 
				{@link org.apache.juneau.rest.RestConfig#addPojoSwaps(Class[])} methods.
			

				By overriding the {@link org.apache.juneau.rest.RestConfig#addSerializers(Class[])} and 
				{@link org.apache.juneau.rest.RestConfig#addParsers(Class[])} methods and setting transforms on the 
				serializers and parsers directly.
			
		
		
		
Additional Information
		

			

				{@link org.apache.juneau.rest.annotation.RestMethod#serializersInherit @RestMethod.serializersInherit()} 
				
Controls how serializers inherit transforms (bean filters and POJO swaps) from the servlet class.
			

				{@link org.apache.juneau.rest.annotation.RestMethod#parsersInherit @RestMethod.parsersInherit()} 
				
Controls how parsers inherit transforms from the servlet class.
		
	
	
	
	
	
	
4.10 - Guards
	

		

			Guards are classes that control access to REST servlets and methods.
		
		

			The {@link org.apache.juneau.rest.annotation.RestResource#guards @RestResource.guards()} annotation 
			can be used to associate one or more class-level {@link org.apache.juneau.rest.RestGuard RestGuards} with a 
			servlet.
		
		

	// Servlet with class-level guard applied
	@RestResource(guards=BillyGuard.class)
	public MyRestServlet extends RestServlet {

 		// Delete method that only Billy is allowed to call.
		public doDelete(RestRequest req, RestResponse res) throws Exception {...}
 	}

	// Define a guard that only lets Billy make a request
	public BillyGuard extends RestGuard {

	@Override
		public boolean isRequestAllowed(RestRequest req) {
			return req.getUserPrincipal().getName().equals("Billy");
		}
	}
		
		

			A common use for guards is to only allow admin access to certain Java methods...
		
		

	// DELETE method
	@RestMethod(name=DELETE, guards={AdminGuard.class})
	public void doDelete(RestRequest req, RestResponse res) throws Exception {
		...
		
		

	public class AdminGuard extends RestGuard {
		@Override
		public boolean isRequestAllowed(RestRequest req) {
			return req.getUserPrincipal().isUserInRole("ADMIN");
		}
	}
		
		

			A guard failure results in an HTTP 401 Unauthorized response.
			However, this can be configured by overriding the 
			{@link org.apache.juneau.rest.RestGuard#guard(RestRequest,RestResponse)} and processing the response 
			yourself.
		
		

			When guards are associated at the class-level, it's equivalent to associating guards on all Java methods on 
			the servlet.
		
		

			Class-level guards can also be created programmatically by overriding the 
			{@link org.apache.juneau.rest.RestConfig#addGuards(Class[])} method.
		
		
		
Additional Information
		

			

				{@link org.apache.juneau.rest.RestGuard} 
		
	
	
	
	
	
4.11 - Converters
	

		

			Converters can be thought of as a "post-processor" for POJOs before they get passed to the serializers.
		
		

			The {@link org.apache.juneau.rest.annotation.RestResource#converters @RestResource.converters()} annotation 
			can be used as a convenient way to add {@link org.apache.juneau.rest.RestConverter RestConverters} to
			all Java REST methods on a servlet.
		
		

	// Associate the Traversable converter to all Java REST methods in this servlet
	@RestResource(converters=Traversable.class)
	public MyRestServlet extends RestServlet {
		...
	}
		
		

			The {@link org.apache.juneau.rest.annotation.RestMethod#converters() @RestMethod.converters()} annotation 
			can be used to associate converters on individual methods.
		
		

	// GET person request handler.
	// Traversable conversion enabled to allow nodes in returned POJO tree to be addressed.
	// Queryable conversion enabled to allow returned POJO to be searched/viewed/sorted.
	@RestMethod(
			name=GET, path="/people/{id}/*",
			converters={Traversable.class,Queryable.class}
	)
	public Person getPerson(@Path int id) {
		return findPerson(id);
	}
		
	
		

			The following converter is used to provide support for addressing child nodes in a POJO tree with URL path 
			remainders.  
			
In this code, the 3rd parameter is the object that was returned by the Java method (or set through 
			request.setObject(o);).
			
The converter uses the {@link org.apache.juneau.utils.PojoRest} wrapper class to address nodes in the 
			tree.
		
		

	/**
	 * Converter for enablement of PojoRest support on response objects returned by a @RestMethod method.
	 * When enabled, objects in a POJO tree returned by the REST method can be addressed through additional URL path information.
	 */
	public class Traversable implements RestConverter {
	
		@Override
		public Object convert(RestServlet resource, RestRequest req, Object o) {
			if (o == null)
				return null;
	
			BeanContext beanContext = resource.getBeanContext();
			
			if (req.getRemainder() != null) {
				PojoRest p = new PojoRest(o, beanContext);
				try {
					o = p.get(req.getRemainder());
				} catch (PojoRestException e) {
					throw new RestException(e.getStatus(), e.getMessage(), e);
				}
			}
			
			return o;
		}
	}
		
	
		

			Juneau defines the following converters out-of-the-box:
		
		

			

			{@link org.apache.juneau.rest.RestConverter}
			

				

					{@link org.apache.juneau.rest.converters.Queryable}
					
Provides query parameters that can be used to transform the response (i.e. search/view/sort the 
					POJO response before being serialized).
				

					{@link org.apache.juneau.rest.converters.Traversable}
					
Allows nodes in the POJO response tree to be individually accessed through additional path info on 
					the request.
				

					{@link org.apache.juneau.rest.converters.Introspectable}
					
Allows method calls to be made on the response POJO, and for the result of that method call to be 
					serialized as the response.
			
		
		

			Class-level converters can be created programmatically by overriding the 
			{@link org.apache.juneau.rest.RestConfig#addConverters(Class[])} method.
		
		

			Note that from the example above, you can specify more than one converter.
			When multiple converters are used, they're executed in the order they're specified in the annotation
			(e.g. first the results will be traversed, then the resulting node will be searched/sorted).
			
		
		
		
Additional Information
		

			

				{@link org.apache.juneau.rest.RestConverter} 
		
	

	
	
	
4.12 - Child Resources
	
		
		

			Child Resources are REST servlets that are linked to parent servlets through the 
			{@link org.apache.juneau.rest.annotation.RestResource#children() @RestResource.children()} annotation.
		
		

	/** Parent Resource */
	@RestResource(
		path="/parent",
		children={Foo.class}
	)
	public MyResource extends RestServlet {
		...
		
		

	/** Child Resource */
 	@RestResource(
		path="/foo"  // Path relative to parent resource.
	)
	public FooResource extends RestServlet {
		...
		
		

			A HUGE advantage of using child resources is that they do not need to be declared in the JEE web.xml 
			file.
			Initialization of and access to the child resources occurs through the parent resource.
			Children can be nested arbitrary deep to create complex REST interfaces with a single top-level REST servlet.
		
		

			The path of the child resource gets appended to the path of the parent resource. 
			So in the example above, the child resource is accessed through the URL /parent/foo.
		
		

			The {@link org.apache.juneau.rest.RestServletGroupDefault} class provides a default "router" page for 
			child resources when a parent resource is nothing more than a grouping of child resources.
		
		
		

			The RootResources class in the Samples project is an example of a router page:
		
		
		
	/**
	 * Sample REST resource showing how to implement a "router" resource page.
	 */
	@RestResource(
		path="/",
		children={
			HelloWorldResource.class,
			MethodExampleResource.class,
			RequestEchoResource.class,
			TempDirResource.class,
			AddressBookResource.class,
			SampleRemoteableServlet.class,
			PhotosResource.class,
			AtomFeedResource.class,
			JsonSchemaResource.class,
			SqlQueryResource.class,
			TumblrParserResource.class,
			CodeFormatterResource.class,
			UrlEncodedFormResource.class,
			SourceResource.class,
			ConfigResource.class,
			LogsResource.class,
			DockerRegistryResource.class,
			ShutdownResource.class
		}
	)
	public class RootResources extends ResourceGroup {
		private static final long serialVersionUID = 1L;
	}
		
		

			When you bring up this resource in a browser, you see the following:
		
		
		
 
			The RestServletGroupDefault class is nothing more than a subclass of 
			{@link org.apache.juneau.rest.RestServletDefault} with a getChildren() method mapped to the servlet 
			root path.
			The method returns a POJO with is just a linked-list of beans with name/description properties.
		
	
		

	public class RestServletGroupDefault extends RestServletDefault {
	
		/**
		 * [GET /] - Get child resources.
		 *
		 * @param req The HTTP request.
		 * @return The bean containing links to the child resources.
		 */
		@RestMethod(name=GET, path="/", description="Child resources")
		public ChildResourceDescriptions getChildren(RestRequest req) {
			return new ChildResourceDescriptions(this, req);
		}
	}		
		
		

			Children can also be defined programmatically by overriding any of the following methods:
		
		

			

			{@link org.apache.juneau.rest.RestConfig}
			

				

					{@link org.apache.juneau.rest.RestConfig#addChildResource(String,Object)}
				

					{@link org.apache.juneau.rest.RestConfig#addChildResources(Class[])}
				

					{@link org.apache.juneau.rest.RestConfig#addChildResources(Object[])}
			
 
		
	
	
	
	
	
4.13 - Localized Messages
	

		

			The {@link org.apache.juneau.rest.annotation.RestResource#messages @RestResource.messages()} annotation can 
			be used to associate a resource bundle with a servlet class.
		
		

	// Servlet with associated resource bundle
	@RestResource(messages="nls/MyMessages")
	public MyRestServlet extends RestServlet {

		// Returns the localized greeting from the "greeting" key in MyMessages.properties
		@RestMethod(name=GET, path="/")
		public String printLocalizedGreeting(RestRequest req) {
			return req.getMessage("greeting");
		}
		
		
	
			The resource bundle can also be passed into the method by using the 
			{@link org.apache.juneau.rest.annotation.Messages @Messages} annotation:
		
		

	@RestMethod(name=GET)
	public String printLocalizedGreeting(@Messages ResourceBundle messages) {
		return messages.getString("greeting");
	}
		
		

			If a resource bundle is shared by multiple servlets, the label and description can be prefixed by the class 
			name:
		
		

	#--------------------------------------------------------------------------------
	# Contents of MyMessages.properties
	#--------------------------------------------------------------------------------
	greeting = Hello!
		
	 	
		

	#--------------------------------------------------------------------------------
	# Contents of shared MyMessages.properties
	#--------------------------------------------------------------------------------
	MyRestServlet.greeting = Hello!
		
	
	
	
	
	
4.14- Encoders
	

		

			The {@link org.apache.juneau.rest.annotation.RestResource#encoders @RestResource.encoders()} annotation can 
			be used to associate character encoders with a servlet class.
			Encoders can be used to enable various kinds of compression (e.g. "gzip") on requests and responses 
			based on the request Accept-Encoding and Content-Encoding headers.
		
		
		
Example:
		

	// Servlet with automated support for GZIP compression
	@RestResource(encoders={GzipEncoder.class})
	public MyRestServlet extends RestServlet {
		...
	}
		
		

			Juneau defines the following encoders out-of-the-box:
		
		

			

			{@link org.apache.juneau.encoders.Encoder}
			

				

					{@link org.apache.juneau.encoders.GzipEncoder}
				

					{@link org.apache.juneau.encoders.IdentityEncoder}
			
		
	
	
	
	
	
4.15 - SVL Vars
	

		
	
			In the previous examples, there were several cases where embedded variables were contained within
			annotation values:
		
		

	@RestResource(
		title="$L{my.label}"
    )
		
		

			Variables are of the form $X{key}, where X can consist of zero or more ASCII characters.
			This is called Simple Variable Language, or SVL.
		
		

			Features include:
		
		

			

				Variables can be nested arbitrarily deep (e.g. "$X{$Y{foo}}").
			

				Variables can contain arguments (e.g. "$L{my.label,arg1,arg2}").
			

				Variables are recursively resolved. 
				
i.e., if a variable results to a value with another variable in it, that variable will also be 
				resolved.
		
		
	
			String variables are implemented through the {@link org.apache.juneau.svl.VarResolver} class and one or more
			{@link org.apache.juneau.svl.Var Vars}. 
		
		
		
Example:
		

	// Create a variable that resolves system properties (e.g. "$S{java.home}")
	public class SystemPropertiesVar extends SimpleVar {
	
		public SystemPropertiesVar() {
			super("S");
		}
		
		@Override
		public String resolve(VarResolverSession session ,String varVal) {
			return System.getProperty(varVal);
		}
	}
	
	// Create a resolver that used that variable
	VarResolver r = new VarResolver().addVars(SystemPropertiesVar.class);

	// Use that resolver to resolve a variable in a string
 	System.out.println(r.resolve("java.home is set to $S{java.home}"));
		
		

			The methods that define the var resolver on a servlet are:
		
		

			

				{@link org.apache.juneau.rest.RestServlet}
				

					

						{@link org.apache.juneau.rest.RestContext#getVarResolver()}
						
Returns the VarResolver associated with a servlet.
					

						{@link org.apache.juneau.rest.RestConfig#addVars(Class[])}
						
The method used to create the servlet VarResolver.
						
Subclasses can override this method to provide their own resolver.
					

						{@link org.apache.juneau.rest.RestCallHandler#getSessionObjects(RestRequest)}
						
Defines the session objects for the var resolver.
						
Subclasses can override this method to provide additional session objects.
				
			
		
		

			The default {@link org.apache.juneau.rest.RestContext#getVarResolver()} method provides support the 
			following string variable types:
		
		

			

				
Variable
				
Description
			
			

				
$S{key}
$S{key,default}
				
System properties.
			
			

				
$E{key}
$E{key,default}
				
Environment variables.
			
			

				
$I{key}
$I{key,default}
				
Servlet initialization parameters.
			
			

				
$C{key}
$C{key,default}
				
Values from the config file returned by {@link org.apache.juneau.rest.RestContext#getConfigFile()}.
			
		
		

			The default values are used when a property doesn't resolve to a value.
			
(e.g. "$S{myBooleanProperty,true}").
		
		

			Like all other variables, keys and default values can themselves be arbitrarily nested.
			
(e.g. "$S{$E{BOOLEAN_PROPERTY_NAME},$E{BOOLEAN_DEFAULT}}")
		
		
	
			Subclasses can augment this list by adding their own variables.
		
		
		
Example:
		

	@Override /* RestServlet */
	protected VarResolver createVarResolver() {

		// Augment the default variable resolver.
		return super.createVarResolver().addVars(BracketVar.class);

		r.addVar("BRACKET", new StringVar() {
		});

		return s;
	}

	public static class BracketVar extends SimpleVar {
		
		public BracketVar() {
			super("BRACKET");
		}
			
		// Wrap all strings inside [] brackets.
		// e.g. "$BRACKET{foobar}" -> "[foobar]"
		@Override
		public String resolve(VarResolverSession session, String varVal) {
			return '[' + varVal + ']';
		}
	}
		
		

			The default {@link org.apache.juneau.rest.RestRequest#getVarResolverSession()} method provides 
				support for all the servlet-level variables, and augments it with the following request-specific
				variable types:
		
		

			

				
Variable
				
Description
			
			

				
$L{key}
$L{key,args...}
				

					Localized strings pulled from resource bundle.
					
Resolves to the value returned by {@link org.apache.juneau.rest.RestRequest#getMessage(String, Object...)}.
					
Can include message arguments (e.g. "$L{my.localized.string, foo, bar}")
				
			
			

				
$R{key}
				

					Request-specific variables.
					
Possible values:
					

						
$R{attribute.X} - Value returned by {@link org.apache.juneau.rest.RestRequest#getAttribute(String)} converted to a string.
						
$R{contextPath} - Value returned by {@link org.apache.juneau.rest.RestRequest#getContextPath()}.
						
$R{formData.X} - Value returned by {@link org.apache.juneau.rest.RequestFormData#getString(String)}.
						
$R{header.X} - Value returned by {@link org.apache.juneau.rest.RequestHeaders#getString(String)}.
						
$R{method} - Value returned by {@link org.apache.juneau.rest.RestRequest#getMethod()}.
						
$R{methodSummary} - Value returned by {@link org.apache.juneau.rest.RestRequest#getMethodSummary()}.
						
$R{methodDescription} - Value returned by {@link org.apache.juneau.rest.RestRequest#getMethodDescription()}.
						
$R{path.X} - Value returned by {@link org.apache.juneau.rest.RequestPathMatch#get(Object)}.
						
$R{pathInfo} - Value returned by {@link org.apache.juneau.rest.RestRequest#getPathInfo()}.
						
$R{query.X} - Value returned by {@link org.apache.juneau.rest.RequestQuery#getString(String)}.
						
$R{requestParentURI} - Value returned by {@link org.apache.juneau.UriContext#getRootRelativePathInfoParent()}.
						
$R{requestURI} - Value returned by {@link org.apache.juneau.rest.RestRequest#getRequestURI()}.
						
$R{servletDescription} - Value returned by {@link org.apache.juneau.rest.RestRequest#getServletDescription()}.
						
$R{servletTitle} - Value returned by {@link org.apache.juneau.rest.RestRequest#getServletTitle()}.
						
$R{servletParentURI} - Value returned by {@link org.apache.juneau.UriContext#getRootRelativeServletPathParent()}.
						
$R{servletPath} - Value returned by {@link org.apache.juneau.rest.RestRequest#getServletPath()}.
						
$R{servletURI} - Value returned by {@link org.apache.juneau.UriContext#getRootRelativeServletPath()}.
					
				
			
			

				
$UE{...}
				

					URL-Encode the specified value.
					
Takes the contents inside the variable and replaces it with a URL-encoded string.
				
			
		
		

			In addition to being used in annotation values, string variables can also be embedded in resource files 
			retrieved through the {@link org.apache.juneau.rest.RestRequest#getReaderResource(String,boolean)} method.
			This can often be useful for embedding localized strings inside HTML form pages.  
		
		

			The UrlEncodedFormResource class in the Samples shows an example of using an HTML form page with
			localized variables.  
			When you bring it up in a browser, you see the following:
		
		
		

			This HTML page is a static file located in the org.apache.juneau.rest.samples package.
		
	
		
		
Contents of org/apache/juneau/server/samples/UrlEncodedForm.html
		TODO - Needs update
		

	<html> 
		<head> 
			<style type='text/css'> 
				@import '$R{servletURI}/style.css'; 
			</style> 
		</head> 
		<body> 
			<h1>$R{servletTitle}</h1> 
			<h2>$R{servletDescription}</h2> 
			<div class='data'> 
				<form id='form' action='$R{servletURI}' method='POST'> 
					<table> 
						<tr> 
							<th>$L{aString}</th> 
							<td><input name="aString" type="text"></td> 
						</tr> 
						<tr> 
							<th>$L{aNumber}</th> 
							<td><input name="aNumber" type="number"></td> 
						</tr> 
						<tr> 
							<th>$L{aDate}</th> 
							<td><input name="aDate" type="datetime"> (ISO8601, e.g. "<code>2001-07-04T15:30:45Z</code>")</td> 
						</tr> 
						<tr> 
							<td colspan='2' align='right'><button type="submit">$L{submit}</button></td> 
						</tr> 
					</table> 
				</form> 
			</div> 
		</body> 
	</html>		
		
		
		
Contents of UrlEncodedFormResource.java
		

	/** 
	* Sample REST resource for loading URL-Encoded form posts into POJOs. 
	 */
	@RestResource(
		path="/urlEncodedForm", 
		messages="nls/UrlEncodedFormResource", 
		title="URL-encoded Form Post Resource", 
		description="Shows how form posts are converted into beans.", 
		htmldoc=@HtmlDoc(
			navlinks={
				"up: request:/..",
				"options: servlet:/?method=OPTIONS"
			} 
		)
	) 
	public class UrlEncodedFormResource extends Resource { 
		private static final long serialVersionUID = 1L; 
		
		/** GET request handler */ 
		@RestMethod(name=GET, path="/") 
		public ReaderResource doGet(RestRequest req) throws IOException { 
			return req.getReaderResource("UrlEncodedForm.html", true); 
		} 
		
		/** POST request handler */ 
		@RestMethod(name=POST, path="/") 
		public Object doPost(@Body FormInputBean input) throws Exception { 
			// Just mirror back the request 
			return input; 
		} 
		
		public static class FormInputBean { 
			public String aString; 
			public int aNumber; 
			@BeanProperty(pojoSwaps=CalendarSwap.ISO8601DT.class) 
			public Calendar aDate; 
		} 
	}
		
		
		
Contents of UrlEncodedFormResource.properties
		

	#--------------------------------------------------------------------------------
	# UrlEncodedFormResource labels
	#--------------------------------------------------------------------------------
	label = URL-Encoded Form Post Example
	description = Shows how URL-Encoded form input can be loaded into POJOs.  POJO is simply echoed back.
	aString = A String:
	aNumber = A Number:
	aDate = A Date:
	submit = submit
		
		
		
Additional Information
		

			

				{@link org.apache.juneau.rest.ReaderResource}
			

				{@link org.apache.juneau.rest.RestRequest#getReaderResource(String,boolean)}
			

				org.apache.juneau.svl
		
	
	
	
	
	
4.16 - Static Files
	

		

			The {@link org.apache.juneau.rest.annotation.RestResource#staticFiles @RestResource.staticFiles()} 
			annotation is used to define paths and locations of statically-served files such as images or HTML 
			documents.
		
		

			The value is a JSON map of paths to packages/directories located on either the classpath or working 
			directory.
		
		
		
Example:
		

	package com.foo.mypackage;

	@RestResource(
		path="/myresource",
		staticFiles="{htdocs:'docs'}"
	)
	public class MyResource extends RestServletDefault {
	}
		
		
	
			Static files are found by calling {@link java.lang.Class#getResource(String)} up the class hierarchy.  
			If not found, then an attempt is made to find the class in the Java working directory.
		
		

			In the example above, given a GET request to /myresource/htdocs/foobar.html, the servlet will 
			attempt to find the foobar.html file in the following ordered locations:
		
		

			
com.foo.mypackage.docs package.
			
org.apache.juneau.rest.docs package (since RestServletDefault is in 
				org.apache.juneau.rest).
			
[working-dir]/docs directory.
		
		
		
Notes:
		

			

				Mappings are cumulative from parent to child.  Child resources can override mappings made on parent 
				resources.
			

				The media type on the response is determined by the 
				{@link org.apache.juneau.rest.RestContext#getMediaTypeForName(String)} method.
		
	

	
	
	
4.17 - Listener Methods
	
	

		

			Various convenience listener methods can be implemented by using the {@link org.apache.juneau.rest.annotation.RestHook @RestHook}
			annotation on methods in your resource class.
		
	

	
	
	
4.18 - Stylesheet
	
	

		TODO
	

	
	
	
4.19 - Default Headers
	

		

			The following annotations are provided for specifying default header values for requests and responses:
		
		

			

				{@link org.apache.juneau.rest.annotation.RestResource#defaultRequestHeaders() @RestResource.defaultRequestHeaders()} 
				
Defines default headers on request when the client doesn't specify them.
			

				{@link org.apache.juneau.rest.annotation.RestResource#defaultResponseHeaders() @RestResource.defaultResponseHeaders()}
				
Appends the specified headers if they weren't already set programmatically.	
		
		
		
		
Example:
		

	// Servlet with default headers
	@RestResource(

		// Assume "text/json" Accept value when Accept not specified
		defaultRequestHeaders={"Accept: text/json"},

		// Add a version header attribute to all responses
		defaultResponseHeaders={"X-Version: 1.0"}
	)
	public MyRestServlet extends RestServlet {
		...
	}			
		
		

			Default headers can also be specified programmatically by overriding the following methods:
		
		

			

				{@link org.apache.juneau.rest.RestConfig}
				

					

						{@link org.apache.juneau.rest.RestConfig#addDefaultRequestHeaders(String[])}
					

						{@link org.apache.juneau.rest.RestConfig#addDefaultResponseHeaders(String[])}
				
			
		
	

	
	
	
4.20 - Handling Errors / Logging
	

		

			The following overridable methods are provided for handling errors on requests:
		
		

			

				{@link org.apache.juneau.rest.RestCallHandler}
				

					

						{@link org.apache.juneau.rest.RestCallHandler#renderError(HttpServletRequest,HttpServletResponse,RestException) renderError(HttpServletRequest,HttpServletResponse,RestException)}
						
Method that produces the error message on the HTTP response.
					

						{@link org.apache.juneau.rest.RestCallHandler#handleNotFound(int,RestRequest,RestResponse) handleNotFound(int,RestRequest,RestResponse)}
						
Method that gets called when no method/path pattern match the incoming request.
				
			
		
		

			The following convenience methods are provided for logging:
		
		

			

				{@link org.apache.juneau.rest.RestLogger}
				

					

						{@link org.apache.juneau.rest.RestLogger#getLogger() getLogger()}
					

						{@link org.apache.juneau.rest.RestLogger#onError(HttpServletRequest,HttpServletResponse,RestException) onError(HttpServletRequest,HttpServletResponse,RestException)}
						
Gets called when an error occurs on a request call.
						
Default implementation logs the error.
					

						{@link org.apache.juneau.rest.RestLogger#log(Level,String,Object[]) log(Level,String,Object[])}
					

						{@link org.apache.juneau.rest.RestLogger#log(Level,Throwable,String,Object[]) log(Level,Throwable,String,Object[])}
					

						{@link org.apache.juneau.rest.RestLogger#logObjects(Level,String,Object[]) logObject(Level,String,Object[])}
				
			
		
		

			The logObjects() method is particularly useful because it allows you to pass in POJOs as arguments
			that serialized using {@link org.apache.juneau.json.JsonSerializer#DEFAULT_LAX_READABLE}, but only
			if the message is actually logged.
		
		
		
Example:
		

	logObjects(DEBUG, "Pojo contents:\n{0}", myPojo);
		
		

			The Juneau framework uses the built-in Java Logging API for logging.
		
		

			If your application makes use of Apache Commons Logging or some other logging API, you can override the 
			{@link org.apache.juneau.rest.RestServlet#log(Level,String,Object[])} method to provide a bridge between 
			the two frameworks.
		
		

	@Override /* RestServlet */
	protected void log(Level level, Throwable cause, String msg, Object...args) {
		Log log = getApacheCommonsLog();
		if (level == Level.SEVERE)
			log.error(msg, cause, args);
		else if (level == Level.WARNING)
        	log.warn(msg, cause, args);
		else if (level == Level.INFO)
        	log.info(msg, cause, args);
		else 
        	log.debug(msg, cause, args);
	}
		
	

	
	
	
4.21 - Configuration Files
	

		

			The Juneau Configuration API is an entirely separate topic from the REST support.
			But the Server API provides methods for associating configuration files with REST servlets so that 
			configuration properties can be defined in external files.
		
		

			The Configuration API provides support for INI-style configuration files with embedded string variables:
		
		
		
Example:
		

	#--------------------------
	# Examples 
	#--------------------------
	[MyProperties]
	path = $E{PATH}
	javaHome = $S{java.home}
	customMessage = Java home is $C{MyProperties/javaHome} and the environment path is $C{MyProperties/path}.
		
		

			These properties are then accessible through the {@link org.apache.juneau.ini.ConfigFile} class.
		
		

	ConfigFile cf = new ConfigFileBuilder().build("myconfig.cfg");
	String path = cf.getString("MyProperties/path");
	File javaHome = cf.getObject(File.class, "MyProperties/javaHome");
	String customMessage = cf.getString("MyProperties/customMessage");
		
		

			Configuration files are associated with REST servlets through the 
			{@link org.apache.juneau.rest.annotation.RestResource#config() @RestResource.config()} annotation.
		
		
		
Example:
		

	@RestResource(
		// Config file is located at ./config_dir/myconfig.cfg
		config="config_dir/myconfig.cfg",
		...
	)
	public MyRestServlet extends RestServlet {
		
		

			The annotation itself can contain string variables.  
			For example, the Microservice API {@link org.apache.juneau.microservice.Resource} class defines the 
			location of the config file as a system property "juneau.configFile":
		
		

	@RestResource(
		// Config file location is defined as a system property
		config="$S{juneau.configFile}",
		...
	)
	public abstract class Resource extends RestServletDefault {
		
		

			In that particular case, the system property can either be passed in, or be determined programmatically
			based on the jar file name in the {@link org.apache.juneau.microservice.Microservice} class.
			It should be noted that the Configuration API is used extensively in the Microservice API in order to 
			externally configure microservices.
		
		

			Once a config file has been associated with a REST servlet, it can be accessed through the 
			{@link org.apache.juneau.rest.RestContext#getConfigFile()} method.
		
		

			A common usage is to use this method to initialize fields in your servlet.
		
		

	@RestResource(
		// Config file is located at ./config_dir/myconfig.cfg
		config="config_dir/myconfig.cfg",
		...
	)
	public MyRestServlet extends RestServlet {
		private String path = getConfig().getString("MyProperties/path");
		private File javaHome = getConfig().getObject(File.class, "MyProperties/javaHome");
		
		

			Another common usage is to refer to config properties through $C variables in your annotations:
		
		

	@RestResource(
		// Get stylesheet from myconfig.cfg, but default to devops.css if it's not specified
		htmldoc=@HtmlDoc(
			stylesheet="$C{MyServlet/stylesheet,servlet:/styles/devops.css}",
		)
		...
	)
	public MyRestServlet extends RestServlet {
		
		

			It's even possible to reference request-level variables in your config file if you use 
			{@link org.apache.juneau.rest.RestRequest#getConfigFile()} to access the config file:
		
		

	#-------------------------------------
	# Contents of config_dir/myconfig.cfg 
	#-------------------------------------
	[HelloWorldResource]
	defaultPerson = you
	message = Hello $R{query.person,$C{HelloWorldResource/defaultPerson}}!
		
		

	/** 
	 * Sample REST resource that prints out a simple "Hello world!" message.
	 */
	 @RestResource(
	 	config="config_dir/myconfig.cfg",
	 	...
	 )
 	public class HelloWorldResource extends RestServletDefault {
		
		/** 
		 * GET request handler.
		 * Specify the GET parameter "?person=X" for a specialized message! 
		 */
		@RestMethod(name=GET, path="/")
		public String sayHello(RestRequest req) {
			return req.getConfig().getString("HelloWorldResource/message");
		}
	}
		
		

			You can even add resource bundles into the mix:
		
		

	#-------------------------------------
	# Contents of config_dir/myconfig.cfg 
	#-------------------------------------
	[HelloWorldResource]
	defaultPerson = you
	message = $L{localizedMessage,$R{query.person,$C{HelloWorldResource/defaultPerson}}}
		
		

	#-------------------------------------------
	# Contents of HelloWorldResource.properties 
	#-------------------------------------------
	localizedMessage = Hello {0}!
		
		

	/** 
	 * Sample REST resource that prints out a simple "Hello world!" message.
	 */
	 @RestResource(
	 	messages="HelloWorldResources",
	 	config="config_dir/myconfig.cfg",
	 	...
	 )
 	public class HelloWorldResource extends RestServletDefault {
		
		/** 
		 * GET request handler.
		 * Specify the GET parameter "?person=X" for a specialized message! 
		 */
		@RestMethod(name=GET, path="/")
		public String sayHello(RestRequest req) {
			return req.getConfig().getString("HelloWorldResource/message");
		}
	}
		
		
		
Additional Information
		

			

				org.apache.juneau.ini
				
Juneau Configuration API Javadocs.
			

				org.apache.juneau.microservice
				
Juneau Microservice API Javadocs.
			

				{@link org.apache.juneau.rest.RestContext#getConfigFile()}
		
	

	
	
	
4.22 - Annotation Inheritance
	

		

			The @RestResource annotation can be used on parent classes and interfaces.
			When multiple annotations are defined at different levels, the annotation values are combined.
			Child annotation values always take precedence over parent annotation values.
		
		

			

				
Annotation
				
Inheritence Rules
			
			

				
{@link org.apache.juneau.rest.annotation.RestResource#guards() guards()}
				

					Guards on child are combined with those on parent class.
					
Guards are executed child-to-parent in the order they appear in the annotation.
					
Guards on methods are executed before those on classes.
				
			
			

				
{@link org.apache.juneau.rest.annotation.RestResource#converters() converters()}
				

					Converters on child are combined with those on parent class.
					
Converters are executed child-to-parent in the order they appear in the annotation.
					
Converters on methods are executed before those on classes.
				
			
			

				
{@link org.apache.juneau.rest.annotation.RestResource#beanFilters() beanFilters()}
				

					Bean filters on child are combined with those on parent class.
				
			
			

				
{@link org.apache.juneau.rest.annotation.RestResource#pojoSwaps() pojoSwaps()}
				

					POJO swaps on child are combined with those on parent class.
				
			
			

				
{@link org.apache.juneau.rest.annotation.RestResource#properties() properties()}
				

					Properties on child are combined with those on parent class.
					
Properties are applied parent-to-child in the order they appear in the annotation.
					
Properties on methods take precedence over those on classes.				
				
			
			

				
{@link org.apache.juneau.rest.annotation.RestResource#serializers() serializers()}
				

					Serializers on child are combined with those on parent class.
					
Serializers on methods take precedence over those on classes.
				
			
			

				
{@link org.apache.juneau.rest.annotation.RestResource#parsers() parsers()}
				

					Parsers on child are combined with those on parent class.
					
Parsers on methods take precedence over those on classes.
				
			
			

				
{@link org.apache.juneau.rest.annotation.RestResource#responseHandlers() responseHandlers()}
				

					Response handlers on child are combined with those on parent class.
				
			
			

				
{@link org.apache.juneau.rest.annotation.RestResource#encoders() encoders()}
				

					Encoders on child are combined with those on parent class.
				
			
			

				
{@link org.apache.juneau.rest.annotation.RestResource#defaultRequestHeaders() defaultRequestHeaders()}
				

					Headers on child are combined with those on parent class.
					
Headers are applied parent-to-child in the order they appear in the annotation.
					
Headers on methods take precedence over those on classes.
				
			
			

				
{@link org.apache.juneau.rest.annotation.RestResource#defaultResponseHeaders() defaultResponseHeaders()}
				

					Headers on child are combined with those on parent class.
					
Headers are applied parent-to-child in the order they appear in the annotation.
				
			
			

				
{@link org.apache.juneau.rest.annotation.RestResource#children() children()}
				

					Children on child are combined with those on parent class.
					
Children are list parent-to-child in the order they appear in the annotation.
				
			
			

				
{@link org.apache.juneau.rest.annotation.RestResource#path() path()}
				

					Path is searched for in child-to-parent order.
				
			
			

				
{@link org.apache.juneau.rest.annotation.RestResource#title() title()}
				

					Label is searched for in child-to-parent order.
				
			
			

				
{@link org.apache.juneau.rest.annotation.RestResource#description() description()}
				

					Description is searched for in child-to-parent order.
				
			
			

				
{@link org.apache.juneau.rest.annotation.RestResource#config() config()}
				

					Config file is searched for in child-to-parent order.
				
			
			

				
{@link org.apache.juneau.rest.annotation.RestResource#staticFiles() staticFiles()}
				

					Static files on child are combined with those on parent class.
					
Static files are are executed child-to-parent in the order they appear in the annotation.
				
			
		
	
	
	
	
	
4.23 - HTTP Status Codes
	

		

			By default, a 200 (OK) status is automatically set as the HTTP status when a Java method executes 
			successfully.
		
		

			Other status codes can be generated by throwing a {@link org.apache.juneau.rest.RestException} with a 
			specific HTTP status code, or calling {@link javax.servlet.http.HttpServletResponse#setStatus(int)}.
		
		

			Non-OK (200) status codes are automatically triggered by the following...
		
		

			

				
Code
				
Description
				
When triggered
			
			

				
401
				
Unauthorized
				
A {@link org.apache.juneau.rest.RestGuard guard} prevented the method from being executed
			
			

				
404
				
Not Found
				
No matching path patterns were found on any method
			
			

				
405
				
Method Not Implemented
				
A path pattern matched, but no Java methods were found for the HTTP method
			
			

				
406
				
Not Acceptable
				

					A path pattern matched, but no Java methods were found with a matching serializer for the 
					Accept on the request
				
			
			

				
412
				
Precondition Failed
				

					A path pattern matched, but no Java methods were found that were not rejected by 
					{@link org.apache.juneau.rest.RestMatcher matchers}
				
			
			

				
415
				
Unsupported Media Type
				

					A path pattern matched, but no Java methods were found with a matching parser for the 
					Content-Type on the request
				
			
			

				
500
				
Internal Server Error
				
The Java method threw an exception other than {@link org.apache.juneau.rest.RestException}
			
		
	

	
	
	
4.24 - Overloaded HTTP Methods
	

		

			Through the use of the built-in "method" GET parameter, you can implement requests beyond the basic 
			REST http method types.
		
		

			For example, the URL "/sample/foo?method=BAR" will cause the following method to be invoked...
		
		

	@RestMethod(name="BAR")
	public void doBar(RestRequest req, RestResponse res) {
		// Handle BAR requests
	}
		
		

			To support overloaded methods, the {@link org.apache.juneau.rest.annotation.RestResource#allowMethodParam()} 
			setting must be enabled on your servlet.
		
		

	@RestResource(
		// Allow &method parameter on BAR requests
		allowMethodParam="BAR"
	)
		
	
	
	
	
	
4.25 - Built-In Parameters
	

		

			The following URL parameters have special meaning and can be passed in through the URL of the request:
		
		

			

				
GET Parameter
				
Description
			
			

				
&plainText=true
				

					Response will always be Content-Type: text/plain and the returned text will be human-readable
					({@link org.apache.juneau.serializer.Serializer#SERIALIZER_useWhitespace} enabled).
					
Useful for debugging.
				
			
			

				
&debug=true
				

					Request body content will be dumped to log file.
				
			
			

				
&noTrace=true
				

					If an error occurs, don't log the stack trace to the log file.
					
Useful for automated JUnit testcases testing error states to prevent the log file from filling 
					up with useless stack traces.
				
			
			

				
&method=X
				

					Overload the HTTP method as a GET parameter (e.g "POST").
					
Must be enabled via {@link org.apache.juneau.rest.annotation.RestResource#allowMethodParam()} setting.
				
			
			

				
&X=headerValue
				

					Specify a header value as a GET parameter.
					
Must be enabled via {@link org.apache.juneau.rest.annotation.RestResource#allowHeaderParams()} setting.
				
			
			

				
&content=X
				

					Pass in the HTTP body content on PUT and POST methods as a UON-encoded GET parameter.
					
Must be enabled via {@link org.apache.juneau.rest.annotation.RestResource#allowBodyParam()} setting.
				
			
		
	
	
	
	
	
4.26 - Defining your own serializers/parsers
	

		

			A very easy-to-use API is provided for defining your own serializers and parsers at both the servlet and 
			method levels.
		
		

			The following examples show a custom serializer and parser defined at the method level.
			It's the PhotosResource class pulled from the Samples project.
			It shows an example of defining a serializer and parser to handle images.
		
		

	/**
	 * Sample resource that allows images to be uploaded and retrieved.
	 */
	@RestResource(
		path="/photos",
		messages="nls/PhotosResource",
		title="Photo REST service",
		description="Use a tool like Poster to upload and retrieve jpeg and png images.",
		htmldoc=@HtmlDoc(
			navlinks={
				"options: ?method=OPTIONS"
			}
		)
	)
	public class PhotosResource extends RestServletDefault {
	
		// Our cache of photos
		private Map<Integer,Photo> photos = new TreeMap<Integer,Photo>();
		
		/** Bean class for storing photos */
		public static class Photo {
			private int id;
			BufferedImage image;
			
			Photo(int id, BufferedImage image) {
				this.id = id;
				this.image = image;
			}
			
			public URI getURI() throws URISyntaxException {
				return new URI("photos/"+id);
			}
			
			public int getID() {
				return id;
			}
		}
		
		/** GET request handler for list of all photos */
		@RestMethod(name=GET, path="/")
		public Collection<Photo> getAllPhotos(RestRequest req, RestResponse res) throws Exception {
			res.setPageTitle("Photo REST service");
			res.setPageText("Use a tool like Poster to upload and retrieve jpeg and png images.");
			return photos.values();
		}
		
		/** GET request handler for single photo */
		@RestMethod(name=GET, path="/{id}", serializers=ImageSerializer.class)
		public BufferedImage getPhoto(RestRequest req, @Path int id) throws Exception {
			Photo p = photos.get(id);
			if (p == null)
				throw new RestException(SC_NOT_FOUND, "Photo not found");
			return p.image;
		}
		
		/** PUT request handler */
		@RestMethod(name=PUT, path="/{id}", parsers=ImageParser.class)
		public String addPhoto(RestRequest req, @Path int id, @Body BufferedImage image) throws Exception {
			photos.put(id, new Photo(id, image));
			return "OK";
		}
		
		/** POST request handler */
		@RestMethod(name=POST, path="/", parsers=ImageParser.class)
		public Photo setPhoto(RestRequest req, @Body BufferedImage image) throws Exception {
			int id = photos.size();
			Photo p = new Photo(id, image);
			photos.put(id, p);
			return p;
		}
		
		/** DELETE request handler */
		@RestMethod(name=DELETE, path="/{id}")
		public String deletePhoto(RestRequest req, @Path int id) throws Exception {
			Photo p = photos.remove(id);
			if (p == null)
				throw new RestException(SC_NOT_FOUND, "Photo not found");
			return "OK";
		}
	
		/** OPTIONS request handler */
		@RestMethod(name=OPTIONS, path="/*")
		public Swagger getOptions(RestRequest req) {
			return req.getSwagger();
		}

		/** Serializer for converting images to byte streams */
		@Produces("image/png,image/jpeg")
		public static class ImageSerializer extends OutputStreamSerializer {
			@Override
			public void serialize(Object o, OutputStream out, SerializerSession session) throws IOException, SerializeException {
				RenderedImage image = (RenderedImage)o;
				String mediaType = ctx.getMediaType();
				ImageIO.write(image, mediaType.substring(mediaType.indexOf('/')+1), out);
			}	
		}
		
		/** Parser for converting byte streams to images */
		@Consumes("image/png,image/jpeg")
		public static class ImageParser extends InputStreamParser {
			@Override
			public <T> T parse(InputStream in, ClassMeta<T> type, ParserSession session) throws ParseException, IOException {
				BufferedImage image = ImageIO.read(in);
				return (T)image;
			}
		}
	}
		
	

	
	
	
4.27 - Response Handlers
	

		

			Juneau uses {@link org.apache.juneau.rest.ResponseHandler ResponseHandlers} to convert POJOS returned by 
			REST methods to proper HTTP responses.
		
		

			Juneau comes with the following response handlers out-of-the-box:
		
		

			

				{@link org.apache.juneau.rest.ResponseHandler}
				

					

						{@link org.apache.juneau.rest.response.DefaultHandler}
						
The default handler for POJOs that convert them to output using the Juneau serializers.
					

						{@link org.apache.juneau.rest.response.ReaderHandler}
						
Pipes {@link java.io.Reader Readers} directly to the response stream.  
					

						{@link org.apache.juneau.rest.response.InputStreamHandler}
						
Pipes {@link java.io.InputStream InputStream} directly to the response stream.  
					

						{@link org.apache.juneau.rest.response.RedirectHandler}
						
Handles {@link org.apache.juneau.rest.Redirect} objects that perform HTTP redirection 
						(HTTP 302).
					

						{@link org.apache.juneau.rest.response.WritableHandler}
						
Handles {@link org.apache.juneau.Writable} objects.
					

						{@link org.apache.juneau.rest.response.StreamableHandler}
						
Handles {@link org.apache.juneau.Streamable} objects.
					

						{@link org.apache.juneau.rest.response.ZipFileListResponseHandler}
						
Handles {@link org.apache.juneau.utils.ZipFileList} objects.
				
			
		
		

			The list of response handlers can be modified or augmented in one of the following ways:
		
		

			

				Specifying additional handlers through the 
				{@link org.apache.juneau.rest.annotation.RestResource#responseHandlers() @RestResource.responseHandlers()} 
				annotation.
			

				Overriding and extending the {@link org.apache.juneau.rest.RestConfig#addResponseHandlers(Class[])} 
				method.
		
		

			The {@link org.apache.juneau.rest.RestCallHandler#handleResponse(RestRequest,RestResponse,Object)} method 
			can also be overridden to bypass the response handler API and process the POJO yourself.
		
	

	
	
	
4.28 - Other Notes
	

		

			

				Subclasses can use either {@link javax.servlet.http.HttpServlet#init(ServletConfig)} 
				or {@link javax.servlet.http.HttpServlet#init()} for initialization just like any other servlet.
			

				The X-Response-Headers header can be used to pass through header values into the response.
				The value should be a URL-encoded map of key-value pairs.
				For example, to add a "Refresh: 1" header to the response to auto-refresh a page, the following 
				parameter can be specified:  "/sample?X-Response-Headers={Refresh=1}"
		
	




5 - Using with OSGi

	

		Since REST servlets are basically just HttpServlets, incorporating them into an OSGi environment
		is pretty straightforward.
	
	

		The following code shows how to register your REST servlets in an OSGi Activator:
	
	

	package org.apache.juneau.examples.rest;
	
	import org.osgi.framework.*;
	import org.osgi.service.http.*;
	import org.osgi.util.tracker.*;
	
	import org.apache.juneau.rest.samples.*;
	
	/**
	 * Activator class used when running samples as a bundle in an OSGi environment.
	 */
	public class Activator implements BundleActivator, ServiceTrackerCustomizer {
	
		private ServiceTracker httpServiceTracker;
		private BundleContext context;
	
		@Override
		public void start(BundleContext context) throws Exception {
			this.context = context;
			httpServiceTracker = new ServiceTracker(context, HttpService.class.getName(), this);
			httpServiceTracker.open();
		}
	
		@Override
		public void stop(BundleContext context) throws Exception {
			httpServiceTracker.close();
		}
	
		@Override
		public Object addingService(ServiceReference reference) {
			Object service = context.getService(reference);
	
			if (service instanceof HttpService) {
				HttpService s = (HttpService)service;
				try {
					s.registerServlet("/sample", new MyRestServlet(), null, null);
				} catch (Exception e) {
					throw new RuntimeException(e);
				}
			}
	
			return service;
		}
	
		@Override
		public void modifiedService(ServiceReference reference, Object service) {
		}
	
		@Override
		public void removedService(ServiceReference reference, Object service) {
		}
	}
	




6 - POJOs Convertible From Strings

	

		Certain methods in the REST server API allow you to specify class types that can be convertible from 
		Strings (e.g. {@link org.apache.juneau.rest.RequestPathMatch#get(Object)}).
	
	

		POJOs convertible from Strings have one of the following:
	
	

		

			One of the following static methods (first match wins):
			

				
public static T fromString(String in); (e.g. enums, UUID)
				
public static T valueOf(String in); (e.g. Number)
				
public static T parse(String in); (e.g. Java logging Level)
				
public static T parseString(String in); (e.g. DatatypeConverter)
				
public static T forName(String in); (e.g. Class and Charset)
			
		
		

			A constructor that takes in a single String:
			

				
public T(String in);
			
		
		

			Has a {@link org.apache.juneau.transform.PojoSwap} associated with the servlet
			with a swapped type of String.
	




7 - Address Book Resource

	

		The AddressBookResource class that's found in the microservice-samples-project.zip file provides
		a good overall example of how to use the Juneau server API with beans.
	
	

		When you start the microservice and point your browser to the address book, you should see the following:
	
	
	

		Use the built-in Accept GET parameter to simulate different language requests, such as JSON:
	
	
	

		The source for this class is shown below:
	
	
	
AddressBookResource.java
	

	/** 
	* Proof-of-concept resource that shows off the capabilities of working with POJO resources. 
	* Consists of an in-memory address book repository. 
	*/ 
	@RestResource( 
		path="/addressBook", 
		messages="nls/AddressBookResource", 

		// Links on the HTML rendition page.
		// "request:/..." URIs are relative to the request URI.
		// "servlet:/..." URIs are relative to the servlet URI.
		// "$C{...}" variables are pulled from the config file.
		htmldoc=@HtmlDoc(
			navlinks={
				"up: request:/..",
				"options: servlet:/?method=OPTIONS",
				"source: $C{Source/gitHub}/org/apache/juneau/examples/rest/addressbook/AddressBookResource.java"
			},
			
			// Our stylesheet for the HTML rendition.
			stylesheet="servlet:/styles/devops.css",
		),

		// Allow INIT as a method parameter.
		allowMethodParam="*",
	
		// Properties that get applied to all serializers and parsers.
		properties={
			
			// Use single quotes.
			@Property(name=SERIALIZER_quoteChar, value="'"),
			
			// Make RDF/XML readable.
			@Property(name=RDF_rdfxml_tab, value="5"),
			
			// Make RDF parsable by adding a root node.
			@Property(name=RDF_addRootProperty, value="true"),
			
			// Make URIs absolute so that we can easily reference them on the client side.
			@Property(name=SERIALIZER_uriResolution, value="ABSOLUTE")
		
			// Make the anchor text on URLs be just the path relative to the servlet.
			@Property(name=HTML_uriAnchorText, value="SERVLET_RELATIVE")
		},
		
		// Support GZIP encoding on Accept-Encoding header.
		encoders=GzipEncoder.class,
		
		// Swagger info.
		swagger=@ResourceSwagger(
			contact="{name:'John Smith',email:'[email protected]'}",
			license="{name:'Apache 2.0',url:'http://www.apache.org/licenses/LICENSE-2.0.html'}",
			version="2.0",
			termsOfService="You're on your own.",
			tags="[{name:'Java',description:'Java utility',externalDocs:{description:'Home page',url:'http://juneau.apache.org'}}]",
			externalDocs="{description:'Home page',url:'http://juneau.apache.org'}"
		)
	) 
	public class AddressBookResource extends ResourceJena { 
		private static final long serialVersionUID = 1L; 
		
		// The in-memory address book 
		private AddressBook addressBook; 
		
		@Override /* Servlet */ 
		public void init() { 
		
			try { 
				// Create the address book 
				addressBook = new AddressBook(java.net.URI.create("servlet:/")); 
				
				// Add some people to our address book by default 
				addressBook.createPerson( 
					new CreatePerson( 
						"Barack Obama", 
						toCalendar("Aug 4, 1961"),
						new CreateAddress("1600 Pennsylvania Ave", "Washington", "DC", 20500, true),
						new CreateAddress("5046 S Greenwood Ave", "Chicago", "IL", 60615, false)
					) 
				); 
				addressBook.createPerson( 
					new CreatePerson( 
						"George Walker Bush", 
						toCalendar("Jul 6, 1946"), 
						new CreateAddress("43 Prairie Chapel Rd", "Crawford", "TX", 76638, true), 
						new CreateAddress("1600 Pennsylvania Ave", "Washington", "DC", 20500, false) 
					) 
				);
			
			} catch (Exception e) { 
				throw new RuntimeException(e); 
			} 
		} 
		
		/** 
		* [GET /] 
		* Get root page. 
		*/ 
		@RestMethod(name=GET, path="/", 
			converters=Queryable.class 
		) 
		public Link[] getRoot() throws Exception { 
			return new Link[] { 
				new Link("people", "people"), 
				new Link("addresses", "addresses") 
			}; 
		} 
		
		/** 
		* [GET /people/*] 
		* Get all people in the address book. 
		* Traversable transforming enabled to allow nodes in returned POJO tree to be addressed. 
		* Introspectable transforming enabled to allow public methods on the returned object to be invoked. 
		*/ 
		@RestMethod(name=GET, path="/people/*", 
			converters={Traversable.class,Queryable.class,Introspectable.class} 
		) 
		public List<Person> getAllPeople() throws Exception { 
			return addressBook.getPeople(); 
		} 
		
		/** 
		* [GET /people/{id}/*] 
		* Get a single person by ID. 
		* Traversable transforming enabled to allow nodes in returned POJO tree to be addressed. 
		* Introspectable transforming enabled to allow public methods on the returned object to be invoked. 
		*/ 
		@RestMethod(name=GET, path="/people/{id}/*", 
			converters={Traversable.class,Queryable.class,Introspectable.class} 
		) 
		public Person getPerson(@Path int id) throws Exception { 
			return findPerson(id); 
		} 
		
		/** 
		* [GET /addresses/*] 
		* Get all addresses in the address book. 
		*/ 
		@RestMethod(name=GET, path="/addresses/*", 
			converters={Traversable.class,Queryable.class} 
		) 
		public List<Address> getAllAddresses() throws Exception { 
			return addressBook.getAddresses(); 
		} 
		
		/** 
		* [GET /addresses/{id}/*] 
		* Get a single address by ID. 
		*/ 
		@RestMethod(name=GET, path="/addresses/{id}/*", 
			converters={Traversable.class,Queryable.class} 
		) 
		public Address getAddress(@Path int id) throws Exception { 
			return findAddress(id); 
		} 
		
		/** 
		* [POST /people] 
		* Create a new Person bean. 
		*/ 
		@RestMethod(name=POST, path="/people", 
			guards=AdminGuard.class 
		) 
		public Redirect createPerson(@Body CreatePerson cp) throws Exception { 
		Person p = addressBook.createPerson(cp); 
			return new Redirect("people/{0}", p.id); 
		} 
		
		/** 
		* [POST /people/{id}/addresses] 
		* Create a new Address bean. 
		*/ 
		@RestMethod(name=POST, path="/people/{id}/addresses", 
			guards=AdminGuard.class 
		) 
		public Redirect createAddress(@Path int id, @Body CreateAddress ca) throws Exception { 
			Person p = findPerson(id); 
			Address a = p.createAddress(ca); 
			return new Redirect("addresses/{0}", a.id); 
		} 
		
		/** 
		* [DELETE /people/{id}] 
		* Delete a Person bean. 
		*/ 
		@RestMethod(name=DELETE, path="/people/{id}", 
			guards=AdminGuard.class, 
		) 
		public String deletePerson(@Path int id) throws Exception { 
			addressBook.removePerson(id); 
			return "DELETE successful"; 
		} 
		
		/** 
		* [DELETE /addresses/{id}] 
		* Delete an Address bean. 
		*/ 
		@RestMethod(name=DELETE, path="/addresses/{id}", 
			guards=AdminGuard.class 
		) 
		public String deleteAddress(@Path int addressId) throws Exception { 
			Person p = addressBook.findPersonWithAddress(addressId); 
			if (p == null) 
				throw new RestException(SC_NOT_FOUND, "Person not found"); 
			Address a = findAddress(addressId); 
			p.addresses.remove(a); 
			return "DELETE successful"; 
		} 
		
		/** 
		* [PUT /people/{id}/*] 
		* Change property on Person bean. 
		*/ 
		@RestMethod(name=PUT, path="/people/{id}/*", 
			guards=AdminGuard.class 
		) 
		public String updatePerson(RestRequest req, @Path int id, @PathRemainder String pathRemainder) throws Exception { 
			try { 
				Person p = findPerson(id); 
				PojoRest r = new PojoRest(p); 
				ClassMeta<?> cm = r.getClassMeta(pathRemainder); 
				Object in = req.getBody().asType(cm); 
				r.put(pathRemainder, in); 
				return "PUT successful"; 
			} catch (Exception e) { 
				throw new RestException(SC_BAD_REQUEST, "PUT unsuccessful").initCause(e); 
			} 
		} 
		
		/** 
		* [PUT /addresses/{id}/*] 
		* Change property on Address bean. 
		*/ 
		@RestMethod(name=PUT, path="/addresses/{id}/*", 
			guards=AdminGuard.class 
		) 
		public String updateAddress(RestRequest req, @Path int id, @PathRemainder String pathRemainder) throws Exception { 
			try { 
				Address a = findAddress(id); 
				PojoRest r = new PojoRest(a); 
				ClassMeta<?> cm = r.getClassMeta(pathRemainder); 
				Object in = req.getBody().asType(pathRemainder); 
				r.put(pathInfo, in); 
				return "PUT successful"; 
			} catch (Exception e) { 
				throw new RestException(SC_BAD_REQUEST, "PUT unsuccessful").initCause(e); 
			} 
		} 
		
		/** 
		* [INIT /] 
		* Reinitialize this resource. 
		*/ 
		@RestMethod(name="INIT", path="/", 
			guards=AdminGuard.class 
		) 
		public String doInit() throws Exception { 
			init(); 
			return "OK"; 
		} 
		
		/** 
		* [GET /cognos] 
		* Get data in Cognos/XML format 
		*/ 
		@RestMethod(name=GET, path="/cognos") 
		public DataSet getCognosData() throws Exception { 
		
			// The Cognos metadata 
			Column[] items = { 
				new Column("name", "xs:String", 255), 
				new Column("age", "xs:int"), 
				new Column("numAddresses", "xs:int") 
				.addTransform( 
					new PojoSwap<Person,Integer>() { 
						@Override /* PojoSwap */ 
						public Integer swap(Person p) { 
							return p.addresses.size(); 
						} 
					} 
				) 
			}; 
			
			return new DataSet(items, addressBook, this.getBeanContext()); 
		} 
		
		/** 
		* [OPTIONS /*] 
		* View resource options 
		*/ 
		@Override /* RestServletDefault */ 
		@RestMethod(name=OPTIONS, path="/*") 
		public Swagger getOptions(RestRequest req) { 
			return req.getSwagger(); 
		} 
		
		/** Convenience method - Find a person by ID */ 
		private Person findPerson(int id) throws RestException { 
			Person p = addressBook.findPerson(id); 
			if (p == null) 
				throw new RestException(SC_NOT_FOUND, "Person not found"); 
			return p; 
		} 
		
		/** Convenience method - Find an address by ID */ 
		private Address findAddress(int id) throws RestException { 
			Address a = addressBook.findAddress(id); 
			if (a == null) 
				throw new RestException(SC_NOT_FOUND, "Address not found"); 
			return a; 
		} 
	} 	
	
	

		The generated OPTIONS page is shown below:
	
	
	

		The OPTIONS page uses the servlet resource bundle to specify the labels so that they're globalizable.
	
	
	
AddressBookResource.properties
	

	label = AddressBook sample resource
	description = Proof-of-concept resource that shows off the capabilities of working with POJO resources
	
	getRoot = Get root page
	
	getAllPeople = Get all people in the address book
	getAllPeople.res.200.content = List<Person>
	
	getPerson = Get a single person by ID
	getPerson.req.attr.id = Person UUID
	getPerson.res.200.content = Person bean
	getPerson.res.404 = Person ID not found
	
	getAllAddresses = Get all addresses in the address book
	getAllAddresses.res.200.content = List<Address>
	
	getAddress = Get a single address by ID
	getAddress.req.attr.id = Address UUID
	getAddress.res.200.content = Address bean
	getAddress.res.404 = Address ID not found
	
	createPerson = Create a new Person bean 
	createPerson.res.307.header.Location = URL of new person
	
	createAddress = Create a new Address bean
	createAddress.req.attr.id = Person UUID
	createAddress.res.307.header.Location = URL of new address
	
	deletePerson = Delete a Person bean
	deletePerson.req.attr.id = Person UUID
	deletePerson.res.200.content = "DELETE successful"
	deletePerson.res.404 = Person ID not found
	
	deleteAddress = Delete an Address bean
	deleteAddress.req.attr.id = Address UUID
	deleteAddress.res.200.content = "DELETE successful"
	deleteAddress.res.404 = Address ID not found
	
	updatePerson = Change property on Person bean
	updatePerson.req.attr.id = Person UUID
	updatePerson.req.content = Anything
	updatePerson.res.200.content = "PUT successful"
	updatePerson.res.400 = Invalid object type used
	updatePerson.res.404 = Person ID not found
	
	updateAddress = Change property on Address bean
	updateAddress.req.attr.id = Address UUID
	updateAddress.req.content = Anything
	updateAddress.res.200.content = "PUT successful"
	updateAddress.res.400 = Invalid object type used
	updateAddress.res.404 = Address ID not found
	
	doInit = Reinitialize this resource
	doInit.res.200.content = "OK"
	
	getOptions = View resource options
	
	getCognosData = Get data in Cognos/XML format
	getCognosData.res.200.content = DataSet
	
	otherNotes = GZip support enabled.  Public methods can be invoked by using the &Method URL parameter.  'text/cognos+xml' support available under root resource only