You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@juneau.apache.org by ja...@apache.org on 2017/08/14 14:58:09 UTC
[4/6] incubator-juneau-website git commit: Update Javadocs on
@RestHook support.
http://git-wip-us.apache.org/repos/asf/incubator-juneau-website/blob/07548003/content/site/apidocs/org/apache/juneau/rest/package-summary.html
----------------------------------------------------------------------
diff --git a/content/site/apidocs/org/apache/juneau/rest/package-summary.html b/content/site/apidocs/org/apache/juneau/rest/package-summary.html
index 8a3e5ff..808e5af 100644
--- a/content/site/apidocs/org/apache/juneau/rest/package-summary.html
+++ b/content/site/apidocs/org/apache/juneau/rest/package-summary.html
@@ -372,43 +372,44 @@
<li><p><a class='doclink' href='#Intro'>Introduction</a></p>
<li><p><a class='doclink' href='#HelloWorldResource'>Hello World Example</a></p>
<li><p><a class='doclink' href='#ClassHierarchy'>Class Hierarchy</a></p>
- <li><p><a class='doclink' href='#RestServlets'>REST Servlets</a></p>
+ <li><p><a class='doclink' href='#RestResources'>REST Servlets</a></p>
<ol>
- <li><p><a class='doclink' href='#RestServlets.MethodSignature'>REST Java Method Signature</a></p>
+ <li><p><a class='doclink' href='#RestResources.MethodSignature'>REST Java Method Signature</a></p>
<ol>
- <li><p><a class='doclink' href='#RestServlets.MethodSignature.Path'>Path</a></p>
- <li><p><a class='doclink' href='#RestServlets.MethodSignature.Matchers'>Matchers</a></p>
+ <li><p><a class='doclink' href='#RestResources.MethodSignature.Path'>Path</a></p>
+ <li><p><a class='doclink' href='#RestResources.MethodSignature.Matchers'>Matchers</a></p>
</ol>
- <li><p><a class='doclink' href='#RestServlets.RequestContent'>Request Content</a></p>
+ <li><p><a class='doclink' href='#RestResources.RequestContent'>Request Content</a></p>
<ol>
- <li><p><a class='doclink' href='#RestServlets.RequestContent.FormPosts'>Form Posts</a></p>
- <li><p><a class='doclink' href='#RestServlets.RequestContent'>Multipart Form Posts</a></p>
+ <li><p><a class='doclink' href='#RestResources.RequestContent.FormPosts'>Form Posts</a></p>
+ <li><p><a class='doclink' href='#RestResources.RequestContent'>Multipart Form Posts</a></p>
</ol>
- <li><p><a class='doclink' href='#RestServlets.ResponseContent'>Response Content</a></p>
- <li><p><a class='doclink' href='#RestServlets.OptionsPages'>OPTIONS Pages</a></p>
- <li><p><a class='doclink' href='#RestServlets.Serializers'>Serializers</a></p>
- <li><p><a class='doclink' href='#RestServlets.Parsers'>Parsers</a></p>
- <li><p><a class='doclink' href='#RestServlets.Properties'>Properties</a></p>
- <li><p><a class='doclink' href='#RestServlets.Transforms'>Transforms</a></p>
- <li><p><a class='doclink' href='#RestServlets.Guards'>Guards</a></p>
- <li><p><a class='doclink' href='#RestServlets.Converters'>Converters</a></p>
- <li><p><a class='doclink' href='#RestServlets.Children'>Child Resources</a></p>
- <li><p><a class='doclink' href='#RestServlets.Labels'>Localized Messages</a></p>
- <li><p><a class='doclink' href='#RestServlets.Encoders'>Encoders</a></p>
- <li><p><a class='doclink' href='#RestServlets.SvlVars'>SVL Vars</a></p>
- <li><p><a class='doclink' href='#RestServlets.StaticFiles'>Static Files</a></p>
- <li><p><a class='doclink' href='#RestServlets.Listeners'>Listener Methods</a></p>
- <li><p><a class='doclink' href='#RestServlets.Stylesheet'>Stylesheet</a></p>
- <li><p><a class='doclink' href='#RestServlets.Headers'>Default Headers</a></p>
- <li><p><a class='doclink' href='#RestServlets.Errors'>Handling Errors / Logging</a></p>
- <li><p><a class='doclink' href='#RestServlets.ConfigFile'>Configuration Files</a></p>
- <li><p><a class='doclink' href='#RestServlets.Inheritence'>Annotation Inheritance</a></p>
- <li><p><a class='doclink' href='#RestServlets.HttpStatusCodes'>HTTP Status Codes</a></p>
- <li><p><a class='doclink' href='#RestServlets.OverloadedHttpMethods'>Overloaded HTTP Methods</a></p>
- <li><p><a class='doclink' href='#RestServlets.BuildInParams'>Built-In Parameters</a></p>
- <li><p><a class='doclink' href='#RestServlets.CustomSerializersParsers'>Defining your own serializers/parsers</a></p>
- <li><p><a class='doclink' href='#RestServlets.ResponseHandlers'>Response Handlers</a></p>
- <li><p><a class='doclink' href='#RestServlets.OtherNotes'>Other Notes</a></p>
+ <li><p><a class='doclink' href='#RestResources.ResponseContent'>Response Content</a></p>
+ <li><p><a class='doclink' href='#RestResources.RestHook'>Lifecycle Hooks</a></p>
+ <li><p><a class='doclink' href='#RestResources.OptionsPages'>OPTIONS Pages</a></p>
+ <li><p><a class='doclink' href='#RestResources.Serializers'>Serializers</a></p>
+ <li><p><a class='doclink' href='#RestResources.Parsers'>Parsers</a></p>
+ <li><p><a class='doclink' href='#RestResources.Properties'>Properties</a></p>
+ <li><p><a class='doclink' href='#RestResources.Transforms'>Transforms</a></p>
+ <li><p><a class='doclink' href='#RestResources.Guards'>Guards</a></p>
+ <li><p><a class='doclink' href='#RestResources.Converters'>Converters</a></p>
+ <li><p><a class='doclink' href='#RestResources.Children'>Child Resources</a></p>
+ <li><p><a class='doclink' href='#RestResources.Labels'>Localized Messages</a></p>
+ <li><p><a class='doclink' href='#RestResources.Encoders'>Encoders</a></p>
+ <li><p><a class='doclink' href='#RestResources.SvlVars'>SVL Vars</a></p>
+ <li><p><a class='doclink' href='#RestResources.StaticFiles'>Static Files</a></p>
+ <li><p><a class='doclink' href='#RestResources.Listeners'>Listener Methods</a></p>
+ <li><p><a class='doclink' href='#RestResources.Stylesheet'>Stylesheet</a></p>
+ <li><p><a class='doclink' href='#RestResources.Headers'>Default Headers</a></p>
+ <li><p><a class='doclink' href='#RestResources.Errors'>Handling Errors / Logging</a></p>
+ <li><p><a class='doclink' href='#RestResources.ConfigFile'>Configuration Files</a></p>
+ <li><p><a class='doclink' href='#RestResources.Inheritence'>Annotation Inheritance</a></p>
+ <li><p><a class='doclink' href='#RestResources.HttpStatusCodes'>HTTP Status Codes</a></p>
+ <li><p><a class='doclink' href='#RestResources.OverloadedHttpMethods'>Overloaded HTTP Methods</a></p>
+ <li><p><a class='doclink' href='#RestResources.BuildInParams'>Built-In Parameters</a></p>
+ <li><p><a class='doclink' href='#RestResources.CustomSerializersParsers'>Defining your own serializers/parsers</a></p>
+ <li><p><a class='doclink' href='#RestResources.ResponseHandlers'>Response Handlers</a></p>
+ <li><p><a class='doclink' href='#RestResources.OtherNotes'>Other Notes</a></p>
</ol>
<li><p><a class='doclink' href='#Osgi'>Using with OSGi</a></p>
<li><p><a class='doclink' href='#PojosConvertableFromString'>POJOs Convertible From Strings</a></p>
@@ -1447,8 +1448,75 @@
</div>
<!-- ======================================================================================================== -->
+ <a id="RestResources.RestHooks"></a>
+ <h3 class='topic' onclick='toggle(this)'>4.4 - Lifecycle Hooks</h3>
+ <div class='topic'>
+ <p>
+ Lifecycle hooks allow you to hook into lifecycle events of the servlet or REST call.
+ Like <ja>@RestMethod</ja> methods, the list of parameters are specified by the developer.
+ </p>
+ <p>
+ For example, if you want to add an initialization method to your resource:
+ </p>
+ <p class='bcode'>
+ <ja>@RestResource</ja>(...)
+ <jk>public class</jk> MyResource {
+
+ <jc>// Our database.</jc>
+ <jk>private</jk> Map<Integer,Object> <jf>myDatabase</jf>;
+
+ <ja>@RestHook</ja>(<jsf>INIT</jsf>)
+ <jk>public void</jk> initMyDatabase(RestConfig config) <jk>throws</jk> Exception {
+ <jf>myDatabase</jf> = <jk>new</jk> LinkedHashMap<>();
+ }
+ }
+ </p>
+ <p>
+ Or if you want to intercept REST calls:
+ </p>
+ <p class='bcode'>
+ <ja>@RestResource</ja>(...)
+ <jk>public class</jk> MyResource {
+
+ <jc>// Add a request attribute to all incoming requests.</jc>
+ <ja>@RestHook</ja>(<jsf>PRE_CALL</jsf>)
+ <jk>public void</jk> onPreCall(RestRequest req) {
+ req.setAttribute(<js>"foo"</js>, <js>"bar"</js>);
+ }
+ }
+ </p>
+ <p>
+ The hook events can be broken down into two categories:
+ </p>
+ <ul class='spaced-list'>
+ <li>Resource lifecycle events:
+ <ul>
+ <li><a href="../../../../org/apache/juneau/rest/annotation/HookEvent.html#INIT"><code>INIT</code></a> - Right before initialization.
+ <li><a href="../../../../org/apache/juneau/rest/annotation/HookEvent.html#POST_INIT"><code>POST_INIT</code></a> - Right after initialization.
+ <li><a href="../../../../org/apache/juneau/rest/annotation/HookEvent.html#POST_INIT_CHILD_FIRST"><code>POST_INIT_CHILD_FIRST</code></a> - Right after initialization, but run child methods first.
+ <li><a href="../../../../org/apache/juneau/rest/annotation/HookEvent.html#DESTROY"><code>DESTROY</code></a> - Right before servlet destroy.
+ </ul>
+ <li>REST call lifecycle events:
+ <ul>
+ <li><a href="../../../../org/apache/juneau/rest/annotation/HookEvent.html#START_CALL"><code>START_CALL</code></a> - At the beginning of a REST call.
+ <li><a href="../../../../org/apache/juneau/rest/annotation/HookEvent.html#PRE_CALL"><code>PRE_CALL</code></a> - Right before the <ja>@RestMethod</ja> method is invoked.
+ <li><a href="../../../../org/apache/juneau/rest/annotation/HookEvent.html#POST_CALL"><code>POST_CALL</code></a> - Right after the <ja>@RestMethod</ja> method is invoked.
+ <li><a href="../../../../org/apache/juneau/rest/annotation/HookEvent.html#END_CALL"><code>END_CALL</code></a> - At the end of the REST call after the response has been flushed.
+ </ul>
+ </ul>
+
+
+ <h6 class='topic'>Additional Information</h6>
+ <ul class='doctree'>
+ <li class='jp'>
+ <a href="../../../../org/apache/juneau/rest/annotation/RestHook.html" title="annotation in org.apache.juneau.rest.annotation"><code>@RestHook</code></a>
+ </ul>
+ </div>
+
+
+ <!-- ======================================================================================================== -->
<a id="RestResources.OptionsPages"></a>
- <h3 class='topic' onclick='toggle(this)'>4.4 - OPTIONS Pages</h3>
+ <h3 class='topic' onclick='toggle(this)'>4.5 - OPTIONS Pages</h3>
<div class='topic'>
<p>
One of the most useful features of Juneau is that it can produce OPTIONS pages for self-documenting designs
@@ -1748,7 +1816,7 @@
<!-- ======================================================================================================== -->
<a id="RestResources.Serializers"></a>
- <h3 class='topic' onclick='toggle(this)'>4.5 - Serializers</h3>
+ <h3 class='topic' onclick='toggle(this)'>4.6 - Serializers</h3>
<div class='topic'>
<p>
REST servlets use the <a href="../../../../org/apache/juneau/serializer/Serializer.html" title="class in org.apache.juneau.serializer"><code>Serializer</code></a> API for defining serializers for
@@ -1818,7 +1886,7 @@
<!-- ======================================================================================================== -->
<a id="RestResources.Parsers"></a>
- <h3 class='topic' onclick='toggle(this)'>4.6 - Parsers</h3>
+ <h3 class='topic' onclick='toggle(this)'>4.7 - Parsers</h3>
<div class='topic'>
<p>
REST servlets use the <a href="../../../../org/apache/juneau/parser/Parser.html" title="class in org.apache.juneau.parser"><code>Parser</code></a> API for defining parsers for parsing request
@@ -1882,7 +1950,7 @@
<!-- ======================================================================================================== -->
<a id="RestResources.Properties"></a>
- <h3 class='topic' onclick='toggle(this)'>4.7 - Properties</h3>
+ <h3 class='topic' onclick='toggle(this)'>4.8 - Properties</h3>
<div class='topic'>
<p>
The Juneau serializers and parsers are highly-configurable through properties.
@@ -1987,7 +2055,7 @@
<!-- ======================================================================================================== -->
<a id="RestResources.Transforms"></a>
- <h3 class='topic' onclick='toggle(this)'>4.8 - Transforms</h3>
+ <h3 class='topic' onclick='toggle(this)'>4.9 - Transforms</h3>
<div class='topic'>
<p>
The Juneau serializers and parsers can be configured on how to handle POJOs through the use of Transforms.
@@ -2051,7 +2119,7 @@
<!-- ======================================================================================================== -->
<a id="RestResources.Guards"></a>
- <h3 class='topic' onclick='toggle(this)'>4.9 - Guards</h3>
+ <h3 class='topic' onclick='toggle(this)'>4.10 - Guards</h3>
<div class='topic'>
<p>
Guards are classes that control access to REST servlets and methods.
@@ -2120,7 +2188,7 @@
<!-- ======================================================================================================== -->
<a id="RestResources.Converters"></a>
- <h3 class='topic' onclick='toggle(this)'>4.10 - Converters</h3>
+ <h3 class='topic' onclick='toggle(this)'>4.11 - Converters</h3>
<div class='topic'>
<p>
Converters can be thought of as a "post-processor" for POJOs before they get passed to the serializers.
@@ -2229,7 +2297,7 @@
<!-- ======================================================================================================== -->
<a id="RestResources.Children"></a>
- <h3 class='topic' onclick='toggle(this)'>4.11 - Child Resources</h3>
+ <h3 class='topic' onclick='toggle(this)'>4.12 - Child Resources</h3>
<div class='topic'>
<p>
Child Resources are REST servlets that are linked to parent servlets through the
@@ -2344,7 +2412,7 @@
<!-- ======================================================================================================== -->
<a id="RestResources.Labels"></a>
- <h3 class='topic' onclick='toggle(this)'>4.12 - Localized Messages</h3>
+ <h3 class='topic' onclick='toggle(this)'>4.13 - Localized Messages</h3>
<div class='topic'>
<p>
The <a href="../../../../org/apache/juneau/rest/annotation/RestResource.html#messages--"><code>@RestResource.messages()</code></a> annotation can
@@ -2391,7 +2459,7 @@
<!-- ======================================================================================================== -->
<a id="RestResources.Encoders"></a>
- <h3 class='topic' onclick='toggle(this)'>4.13- Encoders</h3>
+ <h3 class='topic' onclick='toggle(this)'>4.14- Encoders</h3>
<div class='topic'>
<p>
The <a href="../../../../org/apache/juneau/rest/annotation/RestResource.html#encoders--"><code>@RestResource.encoders()</code></a> annotation can
@@ -2425,7 +2493,7 @@
<!-- ======================================================================================================== -->
<a id="RestResources.SvlVars"></a>
- <h3 class='topic' onclick='toggle(this)'>4.14 - SVL Vars</h3>
+ <h3 class='topic' onclick='toggle(this)'>4.15 - SVL Vars</h3>
<div class='topic'>
<p>
In the previous examples, there were several cases where embedded variables were contained within
@@ -2738,7 +2806,7 @@
<!-- ======================================================================================================== -->
<a id="RestResources.StaticFiles"></a>
- <h3 class='topic' onclick='toggle(this)'>4.15 - Static Files</h3>
+ <h3 class='topic' onclick='toggle(this)'>4.16 - Static Files</h3>
<div class='topic'>
<p>
The <a href="../../../../org/apache/juneau/rest/annotation/RestResource.html#staticFiles--"><code>@RestResource.staticFiles()</code></a>
@@ -2789,7 +2857,7 @@
<!-- ======================================================================================================== -->
<a id="RestResources.Listeners"></a>
- <h3 class='topic' onclick='toggle(this)'>4.16 - Listener Methods</h3>
+ <h3 class='topic' onclick='toggle(this)'>4.17 - Listener Methods</h3>
<div class='topic'>
<p>
Various convenience listener methods can be implemented by using the <a href="../../../../org/apache/juneau/rest/annotation/RestHook.html" title="annotation in org.apache.juneau.rest.annotation"><code>@RestHook</code></a>
@@ -2799,14 +2867,14 @@
<!-- ======================================================================================================== -->
<a id="RestResources.Stylesheet"></a>
- <h3 class='topic' onclick='toggle(this)'>4.17 - Stylesheet</h3>
+ <h3 class='topic' onclick='toggle(this)'>4.18 - Stylesheet</h3>
<div class='topic'>
TODO
</div>
<!-- ======================================================================================================== -->
<a id="RestResources.Headers"></a>
- <h3 class='topic' onclick='toggle(this)'>4.18 - Default Headers</h3>
+ <h3 class='topic' onclick='toggle(this)'>4.19 - Default Headers</h3>
<div class='topic'>
<p>
The following annotations are provided for specifying default header values for requests and responses:
@@ -2853,7 +2921,7 @@
<!-- ======================================================================================================== -->
<a id="RestResources.Errors"></a>
- <h3 class='topic' onclick='toggle(this)'>4.19 - Handling Errors / Logging</h3>
+ <h3 class='topic' onclick='toggle(this)'>4.20 - Handling Errors / Logging</h3>
<div class='topic'>
<p>
The following overridable methods are provided for handling errors on requests:
@@ -2929,7 +2997,7 @@
<!-- ======================================================================================================== -->
<a id="RestResources.ConfigFile"></a>
- <h3 class='topic' onclick='toggle(this)'>4.20 - Configuration Files</h3>
+ <h3 class='topic' onclick='toggle(this)'>4.21 - Configuration Files</h3>
<div class='topic'>
<p>
The Juneau Configuration API is an entirely separate topic from the REST support.
@@ -3108,7 +3176,7 @@
<!-- ======================================================================================================== -->
<a id="RestResources.Inheritence"></a>
- <h3 class='topic' onclick='toggle(this)'>4.21 - Annotation Inheritance</h3>
+ <h3 class='topic' onclick='toggle(this)'>4.22 - Annotation Inheritance</h3>
<div class='topic'>
<p>
The <ja>@RestResource</ja> annotation can be used on parent classes and interfaces.
@@ -3246,7 +3314,7 @@
<!-- ======================================================================================================== -->
<a id="RestResources.HttpStatusCodes"></a>
- <h3 class='topic' onclick='toggle(this)'>4.22 - HTTP Status Codes</h3>
+ <h3 class='topic' onclick='toggle(this)'>4.23 - HTTP Status Codes</h3>
<div class='topic'>
<p>
By default, a 200 (OK) status is automatically set as the HTTP status when a Java method executes
@@ -3314,7 +3382,7 @@
<!-- ======================================================================================================== -->
<a id="RestResources.OverloadedHttpMethods"></a>
- <h3 class='topic' onclick='toggle(this)'>4.23 - Overloaded HTTP Methods</h3>
+ <h3 class='topic' onclick='toggle(this)'>4.24 - Overloaded HTTP Methods</h3>
<div class='topic'>
<p>
Through the use of the built-in <l>"method"</l> GET parameter, you can implement requests beyond the basic
@@ -3345,7 +3413,7 @@
<!-- ======================================================================================================== -->
<a id="RestResources.BuildInParams"></a>
- <h3 class='topic' onclick='toggle(this)'>4.24 - Built-In Parameters</h3>
+ <h3 class='topic' onclick='toggle(this)'>4.25 - Built-In Parameters</h3>
<div class='topic'>
<p>
The following URL parameters have special meaning and can be passed in through the URL of the request:
@@ -3403,7 +3471,7 @@
<!-- ======================================================================================================== -->
<a id="RestResources.CustomSerializersParsers"></a>
- <h3 class='topic' onclick='toggle(this)'>4.25 - Defining your own serializers/parsers</h3>
+ <h3 class='topic' onclick='toggle(this)'>4.26 - Defining your own serializers/parsers</h3>
<div class='topic'>
<p>
A very easy-to-use API is provided for defining your own serializers and parsers at both the servlet and
@@ -3527,7 +3595,7 @@
<!-- ======================================================================================================== -->
<a id="RestResources.ResponseHandlers"></a>
- <h3 class='topic' onclick='toggle(this)'>4.26 - Response Handlers</h3>
+ <h3 class='topic' onclick='toggle(this)'>4.27 - Response Handlers</h3>
<div class='topic'>
<p>
Juneau uses <a href="../../../../org/apache/juneau/rest/ResponseHandler.html" title="interface in org.apache.juneau.rest"><code>ResponseHandlers</code></a> to convert POJOS returned by
@@ -3585,7 +3653,7 @@
<!-- ======================================================================================================== -->
<a id="RestResources.OtherNotes"></a>
- <h3 class='topic' onclick='toggle(this)'>4.27 - Other Notes</h3>
+ <h3 class='topic' onclick='toggle(this)'>4.28 - Other Notes</h3>
<div class='topic'>
<ul class='spaced-list'>
<li>
http://git-wip-us.apache.org/repos/asf/incubator-juneau-website/blob/07548003/content/site/apidocs/overview-summary.html
----------------------------------------------------------------------
diff --git a/content/site/apidocs/overview-summary.html b/content/site/apidocs/overview-summary.html
index ede4aba..dbdba87 100644
--- a/content/site/apidocs/overview-summary.html
+++ b/content/site/apidocs/overview-summary.html
@@ -7334,6 +7334,8 @@
<br><img src='doc-files/ReleaseNotes_632_DarkStyle.png'>
<li>
Stylesheet selection now stored in HTTP session when passed in via <code>?stylesheet</code> query parameter.
+ <li>
+ New doc: <a class='doclink' href='/org/apache/juneau/rest/package-summary.html#RestResources.RestHooks'>Lifecycle Hooks</a>
</ul>
<h6 class='topic'>org.apache.juneau.rest.microservice</h6>