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 2016/10/10 00:28:25 UTC
[4/8] incubator-juneau git commit: Doc updates.
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/cc399df5/juneau-core/src/main/java/org/apache/juneau/xml/annotation/Xml.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/xml/annotation/Xml.java b/juneau-core/src/main/java/org/apache/juneau/xml/annotation/Xml.java
index a2e2008..6f1b536 100644
--- a/juneau-core/src/main/java/org/apache/juneau/xml/annotation/Xml.java
+++ b/juneau-core/src/main/java/org/apache/juneau/xml/annotation/Xml.java
@@ -44,39 +44,36 @@ public @interface Xml {
* <p>
* Applies only to collection and array bean properties.
*
- * <dl>
- * <dt>Example:</dt>
- * <dd>
- * <p class='bcode'>
+ *
+ * <h6 class='topic'>Example:</h6>
+ * <p class='bcode'>
* <jk>public class</jk> MyBean {
* <ja>@Xml</ja>(childName=<js>"child"</js>}
* <jk>public</jk> String[] <jf>children</jf> = {<js>"foo"</js>,<js>"bar"</js>};
* }
- * </p>
- * <p>
- * Without the <ja>@Xml</ja> annotation, serializing this bean as XML would have produced the following...
- * </p>
- * <p class='bcode'>
+ * </p>
+ * <p>
+ * Without the <ja>@Xml</ja> annotation, serializing this bean as XML would have produced the following...
+ * </p>
+ * <p class='bcode'>
* <xt><object></xt>
* <xt><children></xt>
* <xt><string></xt>foo<xt></string></xt>
* <xt><string></xt>bar<xt></string></xt>
* <xt></children></xt>
* <xt></object></xt>
- * </p>
- * <p>
- * With the annotations, serializing this bean as XML produces the following...
- * </p>
- * <p class='bcode'>
+ * </p>
+ * <p>
+ * With the annotations, serializing this bean as XML produces the following...
+ * </p>
+ * <p class='bcode'>
* <xt><object></xt>
* <xt><children></xt>
* <xt><child></xt>foo<xt></child></xt>
* <xt><child></xt>bar<xt></child></xt>
* <xt></children></xt>
* <xt></object></xt>
- * </p>
- * </dd>
- * </dl>
+ * </p>
*/
String childName() default "";
@@ -106,10 +103,8 @@ public @interface Xml {
/**
* The {@link XmlFormat} to use for serializing this object type.
*
- * <dl>
- * <dt>Example:</dt>
- * <dd>
- * <p class='bcode'>
+ * <h6 class='topic'>Example:</h6>
+ * <p class='bcode'>
* <jk>public class</jk> MyBean {
*
* <jc>// Normally, bean properties would be rendered as child elements of the bean element.</jc>
@@ -128,11 +123,11 @@ public @interface Xml {
* <ja>@Xml</ja>(format=XmlFormat.<jsf>COLLAPSED</jsf>, childName=<js>"child"</js>}
* <jk>public</jk> String[] <jf>children</jf> = <js>"foo"</js>,<js>"bar"</js>};
* }
- * </p>
- * <p>
- * Without the <ja>@Xml</ja> annotations, serializing this bean as XML would have produced the following...
- * </p>
- * <p class='bcode'>
+ * </p>
+ * <p>
+ * Without the <ja>@Xml</ja> annotations, serializing this bean as XML would have produced the following...
+ * </p>
+ * <p class='bcode'>
* <xt><object</xt> <xa>href</xa>=<js>'http://foo'</js><xt>></xt>
* <xt><f1></xt>123<xt></f1></xt>
* <xt><children></xt>
@@ -140,19 +135,17 @@ public @interface Xml {
* <xt><string></xt>bar<xt></string></xt>
* <xt></children></xt>
* <xt></object></xt>
- * </p>
- * <p>
- * With the annotations, serializing this bean as XML produces the following...
- * </p>
- * <p class='bcode'>
+ * </p>
+ * <p>
+ * With the annotations, serializing this bean as XML produces the following...
+ * </p>
+ * <p class='bcode'>
* <xt><object</xt> <xa>f1</xa>=<js>'123'</js><xt>></xt>
* <xt><href></xt>http://foo<xt></href></xt>
* <xt><child></xt>foo<xt></child></xt>
* <xt><child></xt>bar<xt></child></xt>
* <xt></object></xt>
- * </p>
- * </dd>
- * </dl>
+ * </p>
*/
XmlFormat format() default XmlFormat.NORMAL;
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/cc399df5/juneau-core/src/main/java/org/apache/juneau/xml/annotation/XmlSchema.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/xml/annotation/XmlSchema.java b/juneau-core/src/main/java/org/apache/juneau/xml/annotation/XmlSchema.java
index 43859fc..21b1717 100644
--- a/juneau-core/src/main/java/org/apache/juneau/xml/annotation/XmlSchema.java
+++ b/juneau-core/src/main/java/org/apache/juneau/xml/annotation/XmlSchema.java
@@ -54,13 +54,11 @@ public @interface XmlSchema {
* <p>
* Inherited by child packages.
*
- * <dl>
- * <dt>Example:</dt>
- * <dd>
- * <p>
- * Contents of <code>package-info.java</code>...
- * </p>
- * <p class='bcode'>
+ * <h6 class='topic'>Example:</h6>
+ * <p>
+ * Contents of <code>package-info.java</code>...
+ * </p>
+ * <p class='bcode'>
* <jc>// XML namespaces used within this package.</jc>
* <ja>@XmlSchema</ja>(prefix=<js>"ab"</js>,
* namespaces={
@@ -72,11 +70,11 @@ public @interface XmlSchema {
* )
* <jk>package</jk> com.ibm.sample.addressbook;
* <jk>import</jk> org.apache.juneau.xml.annotation.*;
- * </p>
- * <p>
- * Class in package using defined namespaces...
- * </p>
- * <p class='bcode'>
+ * </p>
+ * <p>
+ * Class in package using defined namespaces...
+ * </p>
+ * <p class='bcode'>
* <jk>package</jk> com.ibm.sample.addressbook;
*
* <jc>// Bean class, override "ab" namespace on package.</jc>
@@ -90,9 +88,7 @@ public @interface XmlSchema {
* <ja>@Xml</ja>(prefix=<js>"mail"</js>)
* <jk>public</jk> String <jf>street</jf>, <jf>city</jf>, <jf>state</jf>;
* }
- * </p>
- * </dd>
- * </dl>
+ * </p>
*/
public XmlNs[] xmlNs() default {};
}
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/cc399df5/juneau-core/src/main/javadoc/doc-files/Samples.AddressBookResource.2.png
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/javadoc/doc-files/Samples.AddressBookResource.2.png b/juneau-core/src/main/javadoc/doc-files/Samples.AddressBookResource.2.png
deleted file mode 100644
index 36c3e42..0000000
Binary files a/juneau-core/src/main/javadoc/doc-files/Samples.AddressBookResource.2.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/cc399df5/juneau-core/src/main/javadoc/doc-files/Samples.AddressBookResource.Options.png
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/javadoc/doc-files/Samples.AddressBookResource.Options.png b/juneau-core/src/main/javadoc/doc-files/Samples.AddressBookResource.Options.png
new file mode 100644
index 0000000..8b87cb3
Binary files /dev/null and b/juneau-core/src/main/javadoc/doc-files/Samples.AddressBookResource.Options.png differ
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/cc399df5/juneau-core/src/main/javadoc/doc-files/Samples.ConfigResource.2.png
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/javadoc/doc-files/Samples.ConfigResource.2.png b/juneau-core/src/main/javadoc/doc-files/Samples.ConfigResource.2.png
deleted file mode 100644
index ec748e4..0000000
Binary files a/juneau-core/src/main/javadoc/doc-files/Samples.ConfigResource.2.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/cc399df5/juneau-core/src/main/javadoc/doc-files/Samples.HelloWorldResource.3.png
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/javadoc/doc-files/Samples.HelloWorldResource.3.png b/juneau-core/src/main/javadoc/doc-files/Samples.HelloWorldResource.3.png
deleted file mode 100644
index c493099..0000000
Binary files a/juneau-core/src/main/javadoc/doc-files/Samples.HelloWorldResource.3.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/cc399df5/juneau-core/src/main/javadoc/doc-files/Samples.MethodExampleResource.2.png
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/javadoc/doc-files/Samples.MethodExampleResource.2.png b/juneau-core/src/main/javadoc/doc-files/Samples.MethodExampleResource.2.png
index a621767..89c1360 100644
Binary files a/juneau-core/src/main/javadoc/doc-files/Samples.MethodExampleResource.2.png and b/juneau-core/src/main/javadoc/doc-files/Samples.MethodExampleResource.2.png differ
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/cc399df5/juneau-core/src/main/javadoc/doc-files/Server.Html.png
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/javadoc/doc-files/Server.Html.png b/juneau-core/src/main/javadoc/doc-files/Server.Html.png
index 87565c5..b8881d8 100644
Binary files a/juneau-core/src/main/javadoc/doc-files/Server.Html.png and b/juneau-core/src/main/javadoc/doc-files/Server.Html.png differ
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/cc399df5/juneau-core/src/main/javadoc/doc-files/Server.Options.png
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/javadoc/doc-files/Server.Options.png b/juneau-core/src/main/javadoc/doc-files/Server.Options.png
index f89fea0..fee32de 100644
Binary files a/juneau-core/src/main/javadoc/doc-files/Server.Options.png and b/juneau-core/src/main/javadoc/doc-files/Server.Options.png differ
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/cc399df5/juneau-core/src/main/javadoc/doc-files/Server.SystemPropertiesResource.png
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/javadoc/doc-files/Server.SystemPropertiesResource.png b/juneau-core/src/main/javadoc/doc-files/Server.SystemPropertiesResource.png
new file mode 100644
index 0000000..5cce399
Binary files /dev/null and b/juneau-core/src/main/javadoc/doc-files/Server.SystemPropertiesResource.png differ
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/cc399df5/juneau-core/src/main/javadoc/overview.html
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/javadoc/overview.html b/juneau-core/src/main/javadoc/overview.html
index 7c52547..2ee2c64 100644
--- a/juneau-core/src/main/javadoc/overview.html
+++ b/juneau-core/src/main/javadoc/overview.html
@@ -1261,7 +1261,7 @@
<li>APIs for updating, modifying, and saving configuration files without losing comments or formatting.
<li>Extensive listener APIs.
</ul>
- <h6 class='topic'>Examples</h6>
+ <h6 class='topic'>Example:</h6>
<p class='bcode'>
<cc>#--------------------------</cc>
<cc># My section</cc>
@@ -1361,8 +1361,7 @@
<h2 class='topic' onclick='toggle(this)'>3 - Juneau Server (org.apache.juneau.server)</h2>
<div class='topic'>
<p>
- The Juneau REST Server API provides a variety of servlet-based REST resource classes that provides REST interfaces on top of existing POJOs,
- allowing manipulation of those models using familiar GET, PUT, POST, and DELETE operations.
+ The Juneau REST Server API provides servlet-based REST resources on top of existing POJOs.
</p>
<p>
The API automatically detects <l>Accept</l> header of requests and converts POJOs to any of the supported languages.
@@ -1376,47 +1375,132 @@
</p>
<p class='bcode'>
<ja>@RestResource</ja>(
- messages=<js>"nls/messages"</js>,
+ path=<js>"/systemProperties"</js>,
+ title=<js>"System properties resource"</js>,
+ description=<js>"REST interface for performing CRUD operations on system properties."</js>,
properties={
- <ja>@Property</ja>(name=HtmlDocSerializerContext.<jsf>HTMLDOC_title</jsf>, value=<js>"$L{label}"</js>),
- <ja>@Property</ja>(name=HtmlDocSerializerContext.<jsf>HTMLDOC_description</jsf>, value=<js>"$L{description}"</js>),
- <ja>@Property</ja>(name=HtmlDocSerializerContext.<jsf>HTMLDOC_links</jsf>, value=<js>"{up:'$R{requestParentURI}',options:'?method=OPTIONS'}"</js>),
- <ja>@Property</ja>(name=HtmlSerializerContext.<jsf>HTML_uriAnchorText</jsf>, value=<jsf>PROPERTY_NAME</jsf>)
- }
+ <ja>@Property</ja>(name=<jsf>SERIALIZER_quoteChar</jsf>, value=<js>"'"</js>),
+ <ja>@Property</ja>(name=<jsf>HTMLDOC_links</jsf>, value=<js>"{up:'$R{requestParentURI}',options:'$R{servletURI}?method=OPTIONS'}"</js>),
+ },
+ stylesheet=<js>"styles/devops.css"</js>,
+ encoders=GzipEncoder.<jk>class</jk>,
+ contact=<js>"{name:'John Smith',email:'john@smith.com'}"</js>,
+ license=<js>"{name:'Apache 2.0',url:'http://www.apache.org/licenses/LICENSE-2.0.html'}"</js>,
+ version=<js>"2.0"</js>,
+ termsOfService=<js>"You're on your own."</js>,
+ tags=<js>"[{name:'Java',description:'Java utility',externalDocs:{description:'Home page',url:'http://juneau.apache.org'}}]"</js>,
+ externalDocs=<js>"{description:'Home page',url:'http://juneau.apache.org'}"</js>
)
- <jk>public class</jk> SystemPropertiesService <jk>extends</jk> RestServletJenaDefault {
+ <jk>public class</jk> SystemPropertiesResource <jk>extends</jk> RestServletDefault {
- <jd>/** [OPTIONS /*] - Show resource options. */</jd>
- <ja>@RestMethod</ja>(name=<js>"OPTIONS"</js>, path=<js>"/*"</js>)
- <jk>public</jk> Swagger getOptions(RestRequest req) {
- <jk>return</jk> req.getSwagger();
- }
-
- <jd>/** [GET /] - Get all system properties. */</jd>
- <ja>@RestMethod</ja>(name=<js>"GET"</js>, path=<js>"/"</js>)
- <jk>public</jk> TreeMap<String,String> getSystemProperties() <jk>throws</jk> Throwable {
- <jk>return new</jk> TreeMap(System.<jsm>getProperties()</jsm>);
+ <ja>@RestMethod</ja>(
+ name=<js>"GET"</js>, path=<js>"/"</js>,
+ summary=<js>"Show all system properties"</js>,
+ description=<js>"Returns all system properties defined in the JVM."</js>,
+ parameters={
+ <ja>@Parameter</ja>(in=<js>"query"</js>, name=<js>"sort"</js>, description=<js>"Sort results alphabetically."</js>, _default=<js>"false"</js>)
+ },
+ responses={
+ <ja>@Response</ja>(value=200, description=<js>"Returns a map of key/value pairs."</js>)
+ }
+ )
+ <jk>public</jk> Map getSystemProperties(<ja>@Query</ja>(<js>"sort"</js>) <jk>boolean</jk> sort) <jk>throws</jk> Throwable {
+ <jk>if</jk> (sort)
+ <jk>return new</jk> TreeMap(System.<jsm>getProperties</jsm>());
+ <jk>return</jk> System.<jsm>getProperties</jsm>();
}
- <jd>/** [GET /{propertyName}] - Get system property with specified name. */</jd>
- <ja>@RestMethod</ja>(name=<js>"GET"</js>, path=<js>"/{propertyName}"</js>)
+ <ja>@RestMethod</ja>(
+ name=<js>"GET"</js>, path=<js>"/{propertyName}"</js>,
+ summary=<js>"Get system property"</js>,
+ description=<js>"Returns the value of the specified system property."</js>,
+ parameters={
+ <ja>@Parameter</ja>(in=<js>"path"</js>, name=<js>"propertyName"</js>, description=<js>"The system property name."</js>)
+ },
+ responses={
+ <ja>@Response</ja>(value=200, description=<js>"The system property value, or null if not found."</js>)
+ }
+ )
<jk>public</jk> String getSystemProperty(<ja>@Path</ja> String propertyName) <jk>throws</jk> Throwable {
<jk>return</jk> System.<jsm>getProperty</jsm>(propertyName);
}
-
- <jd>/** [PUT /{propertyName}] - Set system property with specified name. */</jd>
- <ja>@RestMethod</ja>(name=<js>"PUT"</js>, path=<js>"/{propertyName}"</js>, guards=AdminGuard.<jk>class</jk>)
+
+ <ja>@RestMethod</ja>(
+ name=<js>"PUT"</js>, path=<js>"/{propertyName}"</js>,
+ summary=<js>"Replace system property"</js>,
+ description=<js>"Sets a new value for the specified system property."</js>,
+ guards=AdminGuard.<jk>class</jk>,
+ parameters={
+ <ja>@Parameter</ja>(in=<js>"path"</js>, name=<js>"propertyName"</js>, description=<js>"The system property name."</js>),
+ <ja>@Parameter</ja>(in=<js>"body"</js>, description=<js>"The new system property value."</js>),
+ },
+ responses={
+ <ja>@Response</ja>(value=302,
+ headers={
+ <ja>@Parameter</ja>(name=<js>"Location"</js>, description=<js>"The root URL of this resource."</js>)
+ }
+ ),
+ <ja>@Response</ja>(value=403, description=<js>"User is not an admin."</js>)
+ }
+ )
<jk>public</jk> Redirect setSystemProperty(<ja>@Path</ja> String propertyName, <ja>@Body</ja> String value) {
System.<jsm>setProperty</jsm>(propertyName, value);
<jk>return new</jk> Redirect();
}
- <jd>/** [DELETE /{propertyName}] - Delete system property with specified name. */</jd>
- <ja>@RestMethod</ja>(name=<js>"DELETE"</js>, path=<js>"/{propertyName}"</js>, guards=AdminGuard.<jk>class</jk>)
+ <ja>@RestMethod</ja>(
+ name=<js>"POST"</js>, path=<js>"/"</js>,
+ summary=<js>"Add an entire set of system properties"</js>,
+ description=<js>"Takes in a map of key/value pairs and creates a set of new system properties."</js>,
+ guards=AdminGuard.<jk>class</jk>,
+ parameters={
+ <ja>@Parameter</ja>(in=<js>"path"</js>, name=<js>"propertyName"</js>, description=<js>"The system property key."</js>),
+ <ja>@Parameter</ja>(in=<js>"body"</js>, description=<js>"The new system property values.", schema="{example:{key1:'val1',key2:123}}"</js>),
+ },
+ responses={
+ <ja>@Response</ja>(value=302,
+ headers={
+ <ja>@Parameter</ja>(name=<js>"Location"</js>, description=<js>"The root URL of this resource."</js>)
+ }
+ ),
+ <ja>@Response</ja>(value=403, description=<js>"Unauthorized: User is not an admin."</js>)
+ }
+ )
+ <jk>public</jk> Redirect setSystemProperties(<ja>@Body</ja> java.util.Properties newProperties) {
+ System.<jsm>setProperties</jsm>(newProperties);
+ <jk>return new</jk> Redirect();
+ }
+
+ <ja>@RestMethod</ja>(
+ name=<js>"DELETE"</js>, path=<js>"/{propertyName}"</js>,
+ summary=<js>"Delete system property"</js>,
+ description=<js>"Deletes the specified system property."</js>,
+ guards=AdminGuard.<jk>class</jk>,
+ parameters={
+ <ja>@Parameter</ja>(in=<js>"path"</js>, name=<js>"propertyName"</js>, description=<js>"The system property name."</js>),
+ },
+ responses={
+ <ja>@Response</ja>(value=302,
+ headers={
+ <ja>@Parameter</ja>(name=<js>"Location"</js>, description=<js>"The root URL of this resource."</js>)
+ }
+ ),
+ <ja>@Response</ja>(value=403, description=<js>"Unauthorized: User is not an admin"</js>)
+ }
+ )
<jk>public</jk> Redirect deleteSystemProperty(<ja>@Path</ja> String propertyName) {
System.<jsm>clearProperty</jsm>(propertyName);
<jk>return new</jk> Redirect();
}
+
+ <ja>@RestMethod</ja>(
+ name=<js>"OPTIONS"</js>, path=<js>"/*"</js>,
+ summary=<js>"Show resource options"</js>,
+ description=<js>"Show resource options as a Swagger doc"</js>
+ )
+ <jk>public</jk> Swagger getOptions(RestRequest req) {
+ <jk>return</jk> req.getSwagger();
+ }
}
</p>
<p>
@@ -1436,7 +1520,12 @@
<xt></web-app></xt>
</p>
<p>
- One of the most useful aspects of using this API is the self-discovering, self-documenting OPTIONS pages that describe how to use the resource using labels pulled from the associated resource bundle:
+ Pointing your browser to the resource renders the POJOs as HTML (since that's what the browser specifies in the <code>Accept</code> header).
+ </p>
+ <img class='bordered' src="doc-files/Server.SystemPropertiesResource.png">
+ <p>
+ One of the most useful aspects of using this API is the self-discovering, self-documenting OPTIONS pages.
+ These are constructed automatically using reflection, augmented with information pulled from annotations (as shown above), resource bundles, or Swagger JSON files:
</p>
<img class='bordered' src="doc-files/Server.Options.png">
@@ -2024,9 +2113,9 @@
<cc>#--------------------------------------------------------------------------------
# HelloWorldResource labels
#--------------------------------------------------------------------------------</cc>
- <ck>label</ck> = <cv>Hello World sample resource</cv>
+ <ck>title</ck> = <cv>Hello World sample resource</cv>
<ck>description</ck> = <cv>Simplest possible resource</cv>
- <ck>sayHello</ck> = <cv>Responds with "Hello world!"</cv>
+ <ck>sayHello.summary</ck> = <cv>Responds with "Hello world!"</cv>
</p>
<p>
The class hierarchy for this class is:
@@ -2055,11 +2144,6 @@
allows us to see this page rendered as JSON:
</p>
<img class='bordered' src='doc-files/Samples.HelloWorldResource.2.png'>
- <p>
- Clicking the OPTIONS link on the page shows the OPTIONS for this resource.
- Note how the <l>sayHello</l> Java method description is pulled from the resource bundle.
- </p>
- <img class='bordered' src='doc-files/Samples.HelloWorldResource.3.png'>
</div>
<!-- ======================================================================================================== -->
@@ -2127,14 +2211,14 @@
String method = req.getMethod();
<jc>// Attributes (from URL pattern variables)</jc>
- String a1 = req.getAttribute(<js>"a1"</js>, String.<jk>class</jk>);
- <jk>int</jk> a2 = req.getAttribute(<js>"a2"</js>, <jk>int</jk>.<jk>class</jk>);
- UUID a3 = req.getAttribute(<js>"a3"</js>, UUID.<jk>class</jk>);
+ String a1 = req.getPathParameter(<js>"a1"</js>, String.<jk>class</jk>);
+ <jk>int</jk> a2 = req.getPathParameter(<js>"a2"</js>, <jk>int</jk>.<jk>class</jk>);
+ UUID a3 = req.getPathParameter(<js>"a3"</js>, UUID.<jk>class</jk>);
<jc>// Optional GET parameters</jc>
- <jk>int</jk> p1 = req.getParameter(<js>"p1"</js>, <jk>int</jk>.<jk>class</jk>, 0);
- String p2 = req.getParameter(<js>"p2"</js>, String.<jk>class</jk>);
- UUID p3 = req.getParameter(<js>"p3"</js>, UUID.<jk>class</jk>);
+ <jk>int</jk> p1 = req.getQueryParameter(<js>"p1"</js>, <jk>int</jk>.<jk>class</jk>, 0);
+ String p2 = req.getQueryParameter(<js>"p2"</js>, String.<jk>class</jk>);
+ UUID p3 = req.getQueryParameter(<js>"p3"</js>, UUID.<jk>class</jk>);
<jc>// URL pattern post-match</jc>
String remainder = req.getPathRemainder();
@@ -2171,8 +2255,8 @@
<li class='m'><l>doGetExample2()</l>
<br>Identical to <l>doGetExample1()</l> but shows how to use the {@link org.apache.juneau.server.RestRequest} and {@link org.apache.juneau.server.RestResponse} objects:
<ul>
- <li class='m'>{@link org.apache.juneau.server.RestRequest#getAttribute(String,Class)}
- <li class='m'>{@link org.apache.juneau.server.RestRequest#getParameter(String,Class)}
+ <li class='m'>{@link org.apache.juneau.server.RestRequest#getPathParameter(String,Class)}
+ <li class='m'>{@link org.apache.juneau.server.RestRequest#getQueryParameter(String,Class)}
<li class='m'>{@link org.apache.juneau.server.RestRequest#getHeader(String,Class)}
<li class='m'>{@link org.apache.juneau.server.RestRequest#getMethod()}
<li class='m'>{@link org.apache.juneau.server.RestRequest#getPathRemainder()}
@@ -2194,15 +2278,24 @@
<p>
Notice how the conversion to POJOs is automatically done for us, even for non-standard POJOs such as UUID.
</p>
- <h6 class='topic'>Self-documenting design through OPTIONS pages</h6>
+ <h6 class='topic'>Self-documenting design through Swagger OPTIONS pages</h6>
<p>
- One of the main features of Juneau is that it produces OPTIONS pages for self-documenting designs (i.e. REST interfaces that document themselves).
+ One of the main features of Juneau is that it produces OPTIONS pages for self-documenting design (i.e. REST interfaces that document themselves).
</p>
<p>
- To facilitate this, the <del><code>ResourceOptions</code></del> class is provided.
- It inspects a <l>RestServlet</l> and its methods, and returns a serializable POJO data structure
- that describes the options for that resource and pulls localized strings from the resource
- bundle associated with the servlet.
+ Much of the information populated on the OPTIONS page is determined through reflection.
+ This basic information can be augmented with information defined through:
+ </p>
+ <ul>
+ <li>Annotations - An example of this was shown in the <code>SystemPropertiesResource</code> example above.<br>
+ Localized strings can be pulled from resource bundles using the <code>$L</code> localization variable.
+ <li>Resource bundle properties - Described in detail in this section.
+ <li>Swagger JSON files with the same name and location as the resource class (e.g. <code>MethodExampleResource.json</code>).<br>
+ Localized versions are defined by appending the locale to the file name (e.g. <code>MethodExampleResource_ja_JP.json</code>);
+ </ul>
+ <p>
+ OPTIONS pages are simply serialized {@link org.apache.juneau.dto.swagger.Swagger} DTO beans.
+ Localized versions of these beans are retrieved using the {@link org.apache.juneau.server.RestRequest#getSwagger()} method.
</p>
<p>
To define an OPTIONS request handler, the {@link org.apache.juneau.server.RestServletDefault} class defines the following Java method:
@@ -2243,28 +2336,28 @@
<cc>#--------------------------------------------------------------------------------
# MethodExampleResource labels
#--------------------------------------------------------------------------------</cc>
- <ck>label = <cv>A simple REST method example resource</cv>
+ <ck>title = <cv>A simple REST method example resource</cv>
- <ck>doGetExample</ck> = <cv>Sample GET method</cv>
- <ck>doGetExample1</ck> = <cv>Sample GET using annotations</cv>
- <ck>doGetExample1.req.attr.a1</ck> = <cv>Sample variable</cv>
- <ck>doGetExample1.req.attr.a2</ck> = <cv>Sample variable</cv>
- <ck>doGetExample1.req.attr.a3</ck> = <cv>Sample variable</cv>
- <ck>doGetExample1.req.param.p1</ck> = <cv>Sample parameter</cv>
- <ck>doGetExample1.req.param.p2</ck> = <cv>Sample parameter</cv>
- <ck>doGetExample1.req.param.p3</ck> = <cv>Sample parameter</cv>
- <ck>doGetExample1.req.header.Accept-Language</ck> = <cv>Sample header</cv>
- <ck>doGetExample1.req.header.DNT</ck> = <cv>Sample header</cv>
- <ck>doGetExample2</ck> = <cv>Sample GET using Java APIs</cv>
- <ck>doGetExample2.req.attr.a1</ck> = <cv>Sample variable</cv>
- <ck>doGetExample2.req.attr.a2</ck> = <cv>Sample variable</cv>
- <ck>doGetExample2.req.attr.a3</ck> = <cv>Sample variable</cv>
- <ck>doGetExample2.req.param.p1</ck> = <cv>Sample parameter</cv>
- <ck>doGetExample2.req.param.p2</ck> = <cv>Sample parameter</cv>
- <ck>doGetExample2.req.param.p3</ck> = <cv>Sample parameter</cv>
- <ck>doGetExample2.req.header.Accept-Language</ck> = <cv>Sample header</cv>
- <ck>doGetExample2.req.header.DNT</ck> = <cv>Sample header</cv>
- <ck>getOptions</ck> = <cv>View these options</cv>
+ <ck>doGetExample.summary</ck> = <cv>Sample GET method</cv>
+ <ck>doGetExample1.summary</ck> = <cv>Sample GET using annotations</cv>
+ <ck>doGetExample1.req.path.a1.description</ck> = <cv>Sample variable</cv>
+ <ck>doGetExample1.req.path.a2.description</ck> = <cv>Sample variable</cv>
+ <ck>doGetExample1.req.path.a3.description</ck> = <cv>Sample variable</cv>
+ <ck>doGetExample1.req.query.p1.description</ck> = <cv>Sample parameter</cv>
+ <ck>doGetExample1.req.query.p2.description</ck> = <cv>Sample parameter</cv>
+ <ck>doGetExample1.req.query.p3.description</ck> = <cv>Sample parameter</cv>
+ <ck>doGetExample1.req.header.Accept-Language.description</ck> = <cv>Sample header</cv>
+ <ck>doGetExample1.req.header.DNT.description</ck> = <cv>Sample header</cv>
+ <ck>doGetExample2.summary</ck> = <cv>Sample GET using Java APIs</cv>
+ <ck>doGetExample2.req.path.a1.description</ck> = <cv>Sample variable</cv>
+ <ck>doGetExample2.req.path.a2.description</ck> = <cv>Sample variable</cv>
+ <ck>doGetExample2.req.path.a3.description</ck> = <cv>Sample variable</cv>
+ <ck>doGetExample2.req.query.p1.description</ck> = <cv>Sample parameter</cv>
+ <ck>doGetExample2.req.query.p2.description</ck> = <cv>Sample parameter</cv>
+ <ck>doGetExample2.req.query.p3.description</ck> = <cv>Sample parameter</cv>
+ <ck>doGetExample2.req.header.Accept-Language.description</ck> = <cv>Sample header</cv>
+ <ck>doGetExample2.req.header.DNT.description</ck> = <cv>Sample header</cv>
+ <ck>getOptions.summary</ck> = <cv>View these options</cv>
</p>
<p>
Clicking the <l>options</l> link on the page presents you with information about how to use this resource:
@@ -2383,7 +2476,7 @@
<cc>#--------------------------------------------------------------------------------
# UrlEncodedFormResource labels
#--------------------------------------------------------------------------------</cc>
- <ck>label</ck> = <cv>URL-Encoded Form Post Example</cv>
+ <ck>title</ck> = <cv>URL-Encoded Form Post Example</cv>
<ck>description</ck> = <cv>Shows how URL-Encoded form input can be loaded into POJOs. POJO is simply echoed back.</cv>
<ck>aString</ck> = <cv>A String:</cv>
<ck>aNumber</ck> = <cv>A Number:</cv>
@@ -2556,10 +2649,6 @@
Pointing a browser to the resource shows the following:
</p>
<img class='bordered' src='doc-files/Samples.AddressBookResource.1.png'>
- <p>
- If you click the <l>options</l> link, you can see the following self-documenting OPTIONS page:
- </p>
- <img class='bordered' src='doc-files/Samples.AddressBookResource.2.png'>
<!-- ======================================================================================================== -->
<a id="Samples.AddressBookResource.Classes"></a>
@@ -2916,7 +3005,13 @@
<ja>@Property</ja>(name=<jsf>SERIALIZER_relativeUriBase</jsf>, value=<js>"$R{servletURI}"</js>),
},
stylesheet=<js>"styles/devops.css"</js>,
- encoders=GzipEncoder.<jk>class</jk>
+ encoders=GzipEncoder.<jk>class</jk>,
+ contact=<js>"{name:'John Smith',email:'john@smith.com'}"</js>,
+ license=<js>"{name:'Apache 2.0',url:'http://www.apache.org/licenses/LICENSE-2.0.html'}"</js>,
+ version=<js>"2.0"</js>,
+ termsOfService=<js>"You're on your own."</js>,
+ tags=<js>"[{name:'Java',description:'Java utility',externalDocs:{description:'Home page',url:'http://juneau.apache.org'}}]"</js>,
+ externalDocs=<js>"{description:'Home page',url:'http://juneau.apache.org'}"</js>
)
<jk>public class</jk> AddressBookResource <jk>extends</jk> ResourceJena {
<jk>private static final long</jk> <jsf>serialVersionUID</jsf> = 1L;
@@ -3197,65 +3292,80 @@
</p>
<h6 class='figure'>AddressBookResource.properties</h6>
<p class='bcode'>
- <ck>label</ck> = <cv>AddressBook sample resource</cv>
+ <ck>title</ck> = <cv>AddressBook sample resource</cv>
<ck>description</ck> = <cv>Proof-of-concept resource that shows off the capabilities of working with POJO resources</cv>
- <ck>getRoot</ck> = <cv>Get root page</cv>
+ <ck>getRoot.summary</ck> = <cv>Get root page</cv>
+ <ck>getRoot.description</ck> = <cv>Jumping off page for top-level Person and Address beans.</cv>
- <ck>getAllPeople</ck> = <cv>Get all people in the address book</cv>
- <ck>getAllPeople.res.200.content</ck> = <cv>List<Person></cv>
+ <ck>doInit.summary</ck> = <cv>Reinitialize this resource</cv>
+ <ck>doInit.description</ck> = <cv>Resets the address book to the original contents.</cv>
+ <ck>doInit.res.200.description</ck> = <cv>Returns the string "OK"</cv>
- <ck>getPerson</ck> = <cv>Get a single person by ID</cv>
- <ck>getPerson.req.attr.id</ck> = <cv>Person UUID</cv>
- <ck>getPerson.res.200.content</ck> = <cv>Person bean</cv>
- <ck>getPerson.res.404</ck> = <cv>Person ID not found</cv>
+ <ck>getAllPeople.summary</ck> = <cv>Get all people in the address book</cv>
+ <ck>getAllPeople.res.200.description</ck> = <cv>Returns a serialized List<Person></cv>
+ <ck>getAllPeople.res.200.examples</ck> = <cv>{'text/json':"[\n\t{\n\t\turi:'http://hostname/addressBook/person/1',\n\t\taddressBookUri:'http://localhost/addressBook',\n\t\tid:1,\n\t\tname:'John Smith',\n\t\tbirthDate:'Jan 1, 2000',\n\t\taddresses:[\n\t\t\t{\n\t\t\t\turi:'http://localhost/addressBook/addresses/1',\n\t\t\t\tpersonUri:'http://localhost/addressBook/people/1',\n\t\t\t\tid:1,\n\t\t\t\tstreet:'101 Main St',\n\t\t\t\tcity:'Anywhere',\n\t\t\t\tstate:'NY',\n\t\t\t\tzip:12345,\n\t\t\t\tisCurrent:true\n\t\t\t}\n\t\t]\n\t}\n]"}</cv>
- <ck>getAllAddresses</ck> = <cv>Get all addresses in the address book</cv>
- <ck>getAllAddresses.res.200.content</ck> = <cv>List<Address></cv>
+ <ck>getPerson.summary</ck> = <cv>Get a single person by ID</cv>
+ <ck>getPerson.req.path.id.description</ck> = <cv>Person ID</cv>
+ <ck>getPerson.req.path.id.type</ck> = <cv>integer</cv>
+ <ck>getPerson.res.200.description</ck> = <cv>Returns a serialized Person bean</cv>
+ <ck>getPerson.res.200.examples</ck> = <cv>{'text/json':"{\n\turi:'http://hostname/addressBook/person/1',\n\taddressBookUri:'http://localhost/addressBook',\n\tid:1,\n\tname:'John Smith',\n\tbirthDate:'Jan 1, 2000',\n\taddresses:[\n\t\t{\n\t\t\turi:'http://localhost/addressBook/addresses/1',\n\t\t\tpersonUri:'http://localhost/addressBook/people/1',\n\t\t\tid:1,\n\t\t\tstreet:'101 Main St',\n\t\t\tcity:'Anywhere',\n\t\t\tstate:'NY',\n\t\t\tzip:12345,\n\t\t\tisCurrent:true\n\t\t}\n\t]\n\}"}</cv>
+ <ck>getPerson.res.404.description</ck> = <cv>Person ID not found</cv>
- <ck>getAddress</ck> = <cv>Get a single address by ID</cv>
- <ck>getAddress.req.attr.id</ck> = <cv>Address UUID</cv>
- <ck>getAddress.res.200.content</ck> = <cv>Address bean</cv>
- <ck>getAddress.res.404</ck> = <cv>Address ID not found</cv>
+ <ck>getAllAddresses.summary</ck> = <cv>Get all addresses in the address book</cv>
+ <ck>getAllAddresses.res.200.description</ck> = <cv>Returns a serialized List<Address></cv>
+ <ck>getAllAddresses.res.200.examples</ck> = <cv>{'text/json':"[\n\t{\n\t\turi:'http://localhost/addressBook/addresses/1',\n\t\tpersonUri:'http://localhost/addressBook/people/1',\n\t\tid:1,\n\t\tstreet:'101 Main St',\n\t\tcity:'Anywhere',\n\t\tstate:'NY',\n\t\tzip:12345,\n\t\tisCurrent:true\n\t}\n]"}</cv>
- <ck>createPerson</ck> = <cv>Create a new Person bean </cv>
- <ck>createPerson.res.307.header.Location</ck> = <cv>URL of new person</cv>
+ <ck>getAddress.summary</ck> = <cv>Get a single address by ID</cv>
+ <ck>getAddress.req.path.id.description</ck> = <cv>Address ID</cv>
+ <ck>getAddress.req.path.id.type</ck> = <cv>integer</cv>
+ <ck>getAddress.res.200.description</ck> = <cv>Returns a serialized Address bean</cv>
+ <ck>getAddress.res.200.examples</ck> = <cv>{'text/json':"{\n\turi:'http://localhost/addressBook/addresses/1',\n\tpersonUri:'http://localhost/addressBook/people/1',\n\tid:1,\n\tstreet:'101 Main St',\n\tcity:'Anywhere',\n\tstate:'NY',\n\tzip:12345,\n\tisCurrent:true\n}"}</cv>
+ <ck>getAddress.res.404.description</ck> = <cv>Address ID not found</cv>
- <ck>createAddress</ck> = <cv>Create a new Address bean</cv>
- <ck>createAddress.req.attr.id</ck> = <cv>Person UUID</cv>
- <ck>createAddress.res.307.header.Location</ck> = <cv>URL of new address</cv>
+ <ck>createPerson.summary</ck> = <cv>Create a new Person bean </cv>
+ <ck>createPerson.req.body.description</ck> = <cv>Serialized CreatePerson bean</cv>
+ <ck>createPerson.req.body.schema</ck> = <cv>{example:"{\n\tname:'John Smith',\n\tbirthDate:'Jan 1, 2000',\n\taddresses:[\n\t\t{\n\t\t\tstreet:'101 Main St',\n\t\t\tcity:'Anywhere',\n\t\t\tstate:'NY',\n\t\t\tzip:12345,\n\t\t\tisCurrent:true\n\t\t}\n\t]\n\}"}</cv>
+ <ck>createPerson.res.307.header.Location.description</ck> = <cv>URL of new person</cv>
- <ck>deletePerson</ck> = <cv>Delete a Person bean</cv>
- <ck>deletePerson.req.attr.id</ck> = <cv>Person UUID</cv>
- <ck>deletePerson.res.200.content</ck> = <cv>"DELETE successful"</cv>
- <ck>deletePerson.res.404</ck> = <cv>Person ID not found</cv>
+ <ck>createAddress.summary</ck> = <cv>Create a new Address bean</cv>
+ <ck>createAddress.req.path.id.description</ck> = <cv>Person ID</cv>
+ <ck>createAddress.req.path.id.type</ck> = <cv>integer</cv>
+ <ck>createAddress.req.body.schema</ck> = <cv>{example:"{\n\tstreet:'101 Main St',\n\tcity:'Anywhere',\n\tstate:'NY',\n\tzip:12345,\n\tisCurrent:true\n}"}</cv>
+ <ck>createAddress.res.307.header.Location.description</ck> = <cv>URL of new address</cv>
- <ck>deleteAddress</ck> = <cv>Delete an Address bean</cv>
- <ck>deleteAddress.req.attr.id</ck> = <cv>Address UUID</cv>
- <ck>deleteAddress.res.200.content</ck> = <cv>"DELETE successful"</cv>
- <ck>deleteAddress.res.404</ck> = <cv>Address ID not found</cv>
+ <ck>deletePerson.summary</ck> = <cv>Delete a Person bean</cv>
+ <ck>deletePerson.req.path.id.description</ck> = <cv>Person ID</cv>
+ <ck>deletePerson.req.path.id.type</ck> = <cv>integer</cv>
+ <ck>deletePerson.res.200.description</ck> = <cv>Returns the string "DELETE successful"</cv>
+ <ck>deletePerson.res.404.description</ck> = <cv>Person ID not found</cv>
- <ck>updatePerson</ck> = <cv>Change property on Person bean</cv>
- <ck>updatePerson.req.attr.id</ck> = <cv>Person UUID</cv>
- <ck>updatePerson.req.content</ck> = <cv>Anything</cv>
- <ck>updatePerson.res.200.content</ck> = <cv>"PUT successful"</cv>
- <ck>updatePerson.res.400</ck> = <cv>Invalid object type used</cv>
- <ck>updatePerson.res.404</ck> = <cv>Person ID not found</cv>
+ <ck>deleteAddress.summary</ck> = <cv>Delete an Address bean</cv>
+ <ck>deleteAddress.req.path.id.description</ck> = <cv>Address ID</cv>
+ <ck>deleteAddress.res.200.description</ck> = <cv>Returns the string "DELETE successful"</cv>
+ <ck>deleteAddress.res.404.description</ck> = <cv>Address ID not found</cv>
- <ck>updateAddress</ck> = <cv>Change property on Address bean</cv>
- <ck>updateAddress.req.attr.id</ck> = <cv>Address UUID</cv>
- <ck>updateAddress.req.content</ck> = <cv>Anything</cv>
- <ck>updateAddress.res.200.content</ck> = <cv>"PUT successful"</cv>
- <ck>updateAddress.res.400</ck> = <cv>Invalid object type used</cv>
- <ck>updateAddress.res.404</ck> = <cv>Address ID not found</cv>
+ <ck>updatePerson.summary</ck> = <cv>Change property on Person bean</cv>
+ <ck>updatePerson.req.path.id.description</ck> = <cv>Person ID</cv>
+ <ck>updatePerson.req.path.id.type</ck> = <cv>integer</cv>
+ <ck>updatePerson.req.body.description</ck> = <cv>Any object matching the field</cv>
+ <ck>updatePerson.res.200.description</ck> = <cv>Returns the string "PUT successful"</cv>
+ <ck>updatePerson.res.400.description</ck> = <cv>Invalid object type used</cv>
+ <ck>updatePerson.res.404.description</ck> = <cv>Person ID not found</cv>
- <ck>doInit</ck> = <cv>Reinitialize this resource</cv>
- <ck>doInit.res.200.content</ck> = <cv>"OK"</cv>
+ <ck>updateAddress.summary</ck> = <cv>Change property on Address bean</cv>
+ <ck>updateAddress.req.path.id.description</ck> = <cv>Address ID</cv>
+ <ck>updateAddress.req.path.id.type</ck> = <cv>integer</cv>
+ <ck>updateAddress.req.body.description</ck> = <cv>Any object matching the field</cv>
+ <ck>updateAddress.res.200.description</ck> = <cv>Returns the string "PUT successful"</cv>
+ <ck>updateAddress.res.400.description</ck> = <cv>Invalid object type used</cv>
+ <ck>updateAddress.res.404.description</ck> = <cv>Address ID not foundv
- <ck>getOptions</ck> = <cv>View resource options</cv>
+ <ck>getOptions.summary</ck> = <cv>View resource options</cv>
- <ck>getCognosData</ck> = <cv>Get data in Cognos/XML format</cv>
- <ck>getCognosData.res.200.content</ck> = <cv>DataSet</cv>
+ <ck>getCognosData.summary</ck> = <cv>Get data in Cognos/XML format</cv>
+ <ck>getCognosData.res.200.description</ck> = <cv>Returns a serialized DataSet</cv>
<ck>otherNotes</ck> = <cv>GZip support enabled. Public methods can be invoked by using the &Method URL parameter. 'text/cognos+xml' support available under root resource only</cv>
</p>
@@ -3322,6 +3432,10 @@
Clicking on the first <l>personUri</l> link executes the <l>getPerson()</l> method, which renders a serialized <l>Person</l> object:
</p>
<img class='bordered' src="doc-files/Samples.AddressBookResource.Demo.10.png">
+ <p>
+ Clicking on the OPTIONS link on the page shows you the Swagger doc generated from our annotations and resource bundle properties:
+ </p>
+ <img class='bordered' src="doc-files/Samples.AddressBookResource.Options.png">
</div>
<!-- ======================================================================================================== -->
@@ -3688,7 +3802,7 @@
<cc>#--------------------------------------------------------------------------------
# TempDirResource labels
#--------------------------------------------------------------------------------</cc>
- <ck>label</ck> = <cv>Temp Directory View Service</cv>
+ <ck>title</ck> = <cv>Temp Directory View Service</cv>
<ck>description</ck> = <cv>View and download files in the '$S{java.io.tmpdir}' directory.</cv>
</p>
<p>
@@ -3860,7 +3974,7 @@
*/</jd>
<ja>@RestResource</ja>(
path=<js>"/docker"</js>,
- label=<js>"Sample Docker resource"</js>,
+ title=<js>"Sample Docker resource"</js>,
properties={
<ja>@Property</ja>(name=<jsf>HTMLDOC_links</jsf>, value=<js>"{up:'$R{requestParentURI}',options:'?method=OPTIONS',source:'$R{servletParentURI}/source?classes=(org.apache.juneau.server.samples.AtomFeedResource)'}"</js>)
}
@@ -4425,10 +4539,6 @@
</p>
<img class='bordered' src='doc-files/Samples.ConfigResource.1.png'>
<p>
- The OPTIONS page shows the REST methods available to alter the config files:
- </p>
- <img class='bordered' src='doc-files/Samples.ConfigResource.2.png'>
- <p>
An edit page is provided for altering the raw config file:
</p>
<img class='bordered' src='doc-files/Samples.ConfigResource.3.png'>
@@ -4443,7 +4553,7 @@
*/</jd>
<ja>@RestResource</ja>(
path=<js>"/config"</js>,
- label=<js>"Configuration"</js>,
+ title=<js>"Configuration"</js>,
description=<js>"Contents of configuration file."</js>,
properties={
<ja>@Property</ja>(name=<jsf>HTMLDOC_links</jsf>, value=<js>"{up:'$R{requestParentURI}',options:'$R{servletURI}?method=OPTIONS',edit:'$R{servletURI}/edit'}"</js>),
@@ -4487,8 +4597,8 @@
*/</jd>
<ja>@RestMethod</ja>(name=<js>"GET"</js>, path=<js>"/{section}"</js>,
description=<js>"Show config file section."</js>,
- input={
- <ja>@Var</ja>(in=<js>"path"</js>, name=<js>"section"</js>, description=<js>"Section name."</js>)
+ parameters={
+ <ja>@Parameter</ja>(in=<js>"path"</js>, name=<js>"section"</js>, description=<js>"Section name."</js>)
}
)
<jk>public</jk> ObjectMap getConfigSection(<ja>@Path</ja>(<js>"section"</js>) String section) <jk>throws</jk> Exception {
@@ -4505,9 +4615,9 @@
*/</jd>
<ja>@RestMethod</ja>(name=<js>"GET"</js>, path=<js>"/{section}/{key}"</js>,
description=<js>"Show config file entry."</js>,
- input={
- <ja>@Var</ja>(in=<js>"path"</js>, name=<js>"section"</js>, description=<js>"Section name."</js>),
- <ja>@Var</ja>(in=<js>"path"</js>, name=<js>"key"</js>, description=<js>"Entry name."</js>)
+ parameters={
+ <ja>@Parameter</ja>(in=<js>"path"</js>, name=<js>"section"</js>, description=<js>"Section name."</js>),
+ <ja>@Parameter</ja>(in=<js>"path"</js>, name=<js>"key"</js>, description=<js>"Entry name."</js>)
}
)
<jk>public</jk> String getConfigEntry(<ja>@Path</ja>(<js>"section"</js>) String section, <ja>@Path</ja>(<js>"key"</js>) String key) <jk>throws</jk> Exception {
@@ -4523,8 +4633,8 @@
*/</jd>
<ja>@RestMethod</ja>(name=<js>"POST"</js>, path=<js>"/"</js>,
description=<js>"Sets contents of config file from a FORM post."</js>,
- input={
- <ja>@Var</ja>(in=<js>"formData"</js>, name=<js>"contents"</js>, description=<js>"New contents in INI file format."</js>)
+ parameters={
+ <ja>@Parameter</ja>(in=<js>"formData"</js>, name=<js>"contents"</js>, description=<js>"New contents in INI file format."</js>)
}
)
<jk>public</jk> ConfigFile setConfigContentsFormPost(<ja>@FormData</ja>(<js>"contents"</js>) String contents) <jk>throws</jk> Exception {
@@ -4540,8 +4650,8 @@
*/</jd>
<ja>@RestMethod</ja>(name=<js>"PUT"</js>, path=<js>"/"</js>,
description=<js>"Sets contents of config file."</js>,
- input={
- <ja>@Var</ja>(in=<js>"body"</js>, description=<js>"New contents in INI file format."</js>)
+ parameters={
+ <ja>@Parameter</ja>(in=<js>"body"</js>, description=<js>"New contents in INI file format."</js>)
}
)
<jk>public</jk> ConfigFile setConfigContents(<ja>@Body</ja> Reader contents) <jk>throws</jk> Exception {
@@ -4559,9 +4669,9 @@
*/</jd>
<ja>@RestMethod</ja>(name=<js>"PUT"</js>, path=<js>"/{section}"</js>,
description=<js>"Add or overwrite a config file section."</js>,
- input={
- <ja>@Var</ja>(in=<js>"path"</js>, name=<js>"section"</js>, description=<js>"Section name."</js>),
- <ja>@Var</ja>(in=<js>"body"</js>, description=<js>"New contents for section as a simple map with string keys and values."</js>)
+ parameters={
+ <ja>@Parameter</ja>(in=<js>"path"</js>, name=<js>"section"</js>, description=<js>"Section name."</js>),
+ <ja>@Parameter</ja>(in=<js>"body"</js>, description=<js>"New contents for section as a simple map with string keys and values."</js>)
}
)
<jk>public</jk> ObjectMap setConfigSection(<ja>@Path</ja>(<js>"section"</js>) String section, <ja>@Body</ja> Map<String,String> contents) <jk>throws</jk> Exception {
@@ -4580,10 +4690,10 @@
*/</jd>
<ja>@RestMethod</ja>(name=<js>"PUT"</js>, path=<js>"/{section}/{key}"</js>,
description=<js>"Add or overwrite a config file entry."</js>,
- input={
- <ja>@Var</ja>(in=<js>"path"</js>, name=<js>"section"</js>, description=<js>"Section name."</js>),
- <ja>@Var</ja>(in=<js>"path"</js>, name=<js>"key"</js>, description=<js>"Entry name."</js>),
- <ja>@Var</ja>(in=<js>"body"</js>, description=<js>"New value as a string."</js>)
+ parameters={
+ <ja>@Parameter</ja>(in=<js>"path"</js>, name=<js>"section"</js>, description=<js>"Section name."</js>),
+ <ja>@Parameter</ja>(in=<js>"path"</js>, name=<js>"key"</js>, description=<js>"Entry name."</js>),
+ <ja>@Parameter</ja>(in=<js>"body"</js>, description=<js>"New value as a string."</js>)
}
)
<jk>public</jk> String setConfigSection(<ja>@Path</ja>(<js>"section"</js>) String section, <ja>@Path</ja>(<js>"key"</js>) String key, <ja>@Body</ja> String value) <jk>throws</jk> Exception {
@@ -4617,7 +4727,7 @@
<xt><table></xt>
<xt><tr></xt><xt><td</xt> <xa>colspan</xa>=<xs>'2'</xs> <xa>align</xa>=<xs>'right'</xs><xt>></xt><xt><button</xt> <xa>type</xa>=<xs>'submit'</xs><xt>></xt>Submit<xt></button></xt><xt><button</xt> <xa>type</xa>=<xs>'reset'</xs><xt>></xt>Reset<xt></button></xt><xt></td></xt><xt></tr></xt>
<xt><tr></xt><xt><th</xt> <xa>colspan</xa>=<xs>'2'</xs><xt>></xt>Contents<xt></th></xt><xt></tr></xt>
- <xt><tr></xt><xt><td</xt> <xa>colspan</xa>=<xs>'2'</xs><xt>></xt><xt><textarea</xt> <xa>name</xa>=<xs>'contents'</xs> <xa>rows</xa>=<xs>'40'</xs> <xa>cols</xa>=<xs>'120'</xs> <xa>style</xa>=<xs>'white-space: pre; word-wrap: normal; overflow-x: scroll;'</xs><xt>></xt>$A{contents}<xt></textarea></xt><xt></td></xt><xt></tr></xt>
+ <xt><tr></xt><xt><td</xt> <xa>colspan</xa>=<xs>'2'</xs><xt>></xt><xt><textarea</xt> <xa>name</xa>=<xs>'contents'</xs> <xa>rows</xa>=<xs>'40'</xs> <xa>cols</xa>=<xs>'120'</xs> <xa>style</xa>=<xs>'white-space: pre; word-wrap: normal; overflow-x: scroll;'</xs><xt>></xt>$SA{contents}<xt></textarea></xt><xt></td></xt><xt></tr></xt>
<xt></table></xt>
<xt></div></xt>
<xt></form></xt>
@@ -6092,7 +6202,7 @@
<li>Performance improvements around query parameters.
<li>New methods on {@link org.apache.juneau.server.RestRequest} for handling multi-part parameters:
<ul>
- <li>{@link org.apache.juneau.server.RestRequest#getParameters(String,Class)}
+ <li><del><code>RestRequest.getParameters(String,Class)</code></del>
<li>{@link org.apache.juneau.server.RestRequest#getQueryParameters(String,Class)}
</ul>
</li>
@@ -6151,7 +6261,7 @@
<h6 class='topic'>com.ibm.team.juno.server</h6>
<ul class='spaced-list'>
<li>Fixed major issue that prevented parsing URL-Encoded form posts into POJOs.
- Calling <code>HttpServlet.getParameter(String)</code> was forcing the underlying servlet code to process the HTTP body itself, preventing the <code>UrlEncodingSerializer</code>
+ Calling <del><code>HttpServlet.getParameter(String)</code></del> was forcing the underlying servlet code to process the HTTP body itself, preventing the <code>UrlEncodingSerializer</code>
class from being able to parse the content. Updated code no longer inadvertantly calls this method.
<li>New {@link org.apache.juneau.server.RestRequest#getQueryParameter(String)}, {@link org.apache.juneau.server.RestRequest#hasQueryParameter(String)}, and {@link org.apache.juneau.server.RestRequest#hasAnyQueryParameters(String[])}
methods that only look for parameters in the URL query string to prevent loading and parsing of URL-Encoded form posts.
@@ -6399,7 +6509,7 @@
<li>New {@link org.apache.juneau.server.RestRequest#getJavaMethod()} method for getting access to the method used to handle a request.
Useful for accessing the method name or annotations during requests, such as in calls to {@link org.apache.juneau.server.RestGuard#guard(RestRequest,RestResponse)}.
<li>Fixed bug when using Jetty where you tried to read text input after a header was written.
- <li>Added new string variables <code>$A{...}</code> (request attributes) and <code>$P{...}</code> (request parameters) to <code>RestServlet.createRequestVarResolver(RestRequest)</code>.
+ <li>Added new string variables <del><code>$A{...}</code></del> (request attributes) and <del><code>$P{...}</code></del> (request parameters) to <code>RestServlet.createRequestVarResolver(RestRequest)</code>.
</ul>
</div>
@@ -6489,7 +6599,7 @@
<li>More consistent handling of exceptions across all parsers.
<li>Minor changes to {@link org.apache.juneau.server.RestRequest} class.
<ul>
- <li>Changed the order of parameters on {@link org.apache.juneau.server.RestRequest#getParameter(String,Class)}.
+ <li>Changed the order of parameters on <del><code>RestRequest#getParameter(String,Class)</code></del>.
<li>Added <code>RestRequest.getMapParameter(String,Class,Class,Class)</code> and
<code>RestRequest.getCollectionParameter(String,Class,Class)}</code> methods.
</ul>
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/cc399df5/juneau-microservice/src/main/java/org/apache/juneau/microservice/Microservice.java
----------------------------------------------------------------------
diff --git a/juneau-microservice/src/main/java/org/apache/juneau/microservice/Microservice.java b/juneau-microservice/src/main/java/org/apache/juneau/microservice/Microservice.java
index e7c3688..32dea9b 100755
--- a/juneau-microservice/src/main/java/org/apache/juneau/microservice/Microservice.java
+++ b/juneau-microservice/src/main/java/org/apache/juneau/microservice/Microservice.java
@@ -221,10 +221,9 @@ public abstract class Microservice {
* </ul>
* <p>
* Subclasses can override this method to provide their own variables.
- * <dl>
- * <dt>Examples:</dt>
- * <dd>
- * <p class='bcode'>
+ *
+ * <h6 class='topic'>Example:</h6>
+ * <p class='bcode'>
* <jd>/**
* * Augment default var resolver with a custom $B{...} variable that simply wraps strings inside square brackets.
* * /</jd>
@@ -240,8 +239,8 @@ public abstract class Microservice {
* }
* );
* }
- * </p>
- * <p class='bcode'>
+ * </p>
+ * <p class='bcode'>
* <cc># Example config file</cc>
* <cs>[MySection]</cs>
* <ck>myEntry</ck> = $B{foo}
@@ -249,9 +248,7 @@ public abstract class Microservice {
* <p class='bcode'>
* <jc>// Example java code</jc>
* String myentry = getConfig().getString(<js>"MySection/myEntry"</js>); <jc>// == "[foo]"</js>
- * </p>
- * </dd>
- * </dl>
+ * </p>
*
* @return A new {@link VarResolver}.
*/
@@ -293,10 +290,9 @@ public abstract class Microservice {
* String variables defined by {@link #createVarResolver()} are automatically resolved when using this method.
* <p>
* This method can be called from the class constructor.
- * <dl>
- * <dt>Examples:</dt>
- * <dd>
- * <p class='bcode'>
+ *
+ * <h6 class='topic'>Example:</h6>
+ * <p class='bcode'>
* <cc>#--------------------------</cc>
* <cc># My section</cc>
* <cc>#--------------------------</cc>
@@ -357,9 +353,7 @@ public abstract class Microservice {
* <jk>int</jk> sameAsAnInt = cf.getInt(<js>"MySection/sameAsAnInt"</js>);
* String myArg = cf.getString(<js>"MySection/myArg"</js>);
* String firstArg = cf.getString(<js>"MySection/firstArg"</js>);
- * </p>
- * </dd>
- * </dl>
+ * </p>
*
* @return The config file for this application, or <jk>null</jk> if no config file is configured.
*/
@@ -374,18 +368,15 @@ public abstract class Microservice {
* and entries converted to simple strings.
* <p>
* This method can be called from the class constructor.
- * <dl>
- * <dt>Examples:</dt>
- * <dd>
- * <p class='bcode'>
+ *
+ * <h6 class='topic'>Example:</h6>
+ * <p class='bcode'>
* <jc>// Get Main-Class from manifest file.</jc>
* String mainClass = Microservice.<jsm>getManifest</jsm>().getString(<js>"Main-Class"</js>, <js>"unknown"</js>);
*
* <jc>// Get Rest-Resources from manifest file.</jc>
* String[] restResources = Microservice.<jsm>getManifest</jsm>().getStringArray(<js>"Rest-Resources"</js>);
- * </p>
- * </dd>
- * </dl>
+ * </p>
*
* @return The manifest file from the main jar, or <jk>null</jk> if the manifest file could not be retrieved.
*/
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/cc399df5/juneau-microservice/src/main/java/org/apache/juneau/microservice/package.html
----------------------------------------------------------------------
diff --git a/juneau-microservice/src/main/java/org/apache/juneau/microservice/package.html b/juneau-microservice/src/main/java/org/apache/juneau/microservice/package.html
index a80812d..6ab0126 100755
--- a/juneau-microservice/src/main/java/org/apache/juneau/microservice/package.html
+++ b/juneau-microservice/src/main/java/org/apache/juneau/microservice/package.html
@@ -163,7 +163,7 @@
*/</jd>
<ja>@RestResource</ja>(
path=<js>"/"</js>,
- label=<js>"Juneau Microservice Template"</js>,
+ title=<js>"Juneau Microservice Template"</js>,
description=<js>"Template for creating REST microservices"</js>,
properties={
<ja>@Property</ja>(name=<jsf>HTMLDOC_links</jsf>, value=<js>"{options:'$R{servletURI}?method=OPTIONS'}"</js>)
@@ -644,14 +644,18 @@
The following variables are available in addition to the variables defined above:
<ul>
<li><l>$L{key}, $L{key,args}</l> - Localized variables pulled from {@link org.apache.juneau.server.RestRequest#getMessage(String, Object...)}.
- <li><l>$A{key}, $A{key,default}</l> - Request attributes pulled from {@link org.apache.juneau.server.RestRequest#getAttribute(String)}.
- <li><l>$P{key}, $P{key,default}</l> - Request parameters pulled from {@link org.apache.juneau.server.RestRequest#getParameter(String)}.
<li><l>$R{key}</l> - Request variables.
<ul>
+ <li><l>$R{attribute.X}</l> - Value returned by {@link org.apache.juneau.server.RestRequest#getAttribute(String)} converted to a string.
<li><l>$R{contextPath}</l> - Value returned by {@link org.apache.juneau.server.RestRequest#getContextPath()}.
+ <li><l>$R{formData.X}</l> - Value returned by {@link org.apache.juneau.server.RestRequest#getFormDataParameter(String)}.
+ <li><l>$R{header.X}</l> - Value returned by {@link org.apache.juneau.server.RestRequest#getHeader(String)}.
<li><l>$R{method}</l> - Value returned by {@link org.apache.juneau.server.RestRequest#getMethod()}.
+ <li><l>$R{methodSummary}</l> - Value returned by {@link org.apache.juneau.server.RestRequest#getMethodSummary()}.
<li><l>$R{methodDescription}</l> - Value returned by {@link org.apache.juneau.server.RestRequest#getMethodDescription()}.
+ <li><l>$R{path.X}</l> - Value returned by {@link org.apache.juneau.server.RestRequest#getPathParameter(String)}.
<li><l>$R{pathInfo}</l> - Value returned by {@link org.apache.juneau.server.RestRequest#getPathInfo()}.
+ <li><l>$R{query.X}</l> - Value returned by {@link org.apache.juneau.server.RestRequest#getQueryParameter(String)}.
<li><l>$R{requestParentURI}</l> - Value returned by {@link org.apache.juneau.server.RestRequest#getRequestParentURI()}.
<li><l>$R{requestURI}</l> - Value returned by {@link org.apache.juneau.server.RestRequest#getRequestURI()}.
<li><l>$R{servletDescription}</l> - Value returned by {@link org.apache.juneau.server.RestRequest#getServletDescription()}.
@@ -661,6 +665,7 @@
<li><l>$R{servletURI}</l> - Value returned by {@link org.apache.juneau.server.RestRequest#getServletURI()}.
<li><l>$R{trimmedRequestURI}</l> - Value returned by {@link org.apache.juneau.server.RestRequest#getTrimmedRequestURI()}.
</ul>
+ <li><l>$SA{key,mediaType}</l> - Object returned by {@link org.apache.juneau.server.RestRequest#getAttribute(String)} converted to a string using the serializer registered to handle the specified media type.
<li><l>$UE{...}</l> - URL-Encode the specified value by calling {@link org.apache.juneau.server.RestUtils#encode(String)}.
</ul>
<h6 class='figure'>Example usage:</h6>
@@ -669,8 +674,8 @@
<cc># Contents of microservice.cfg </cc>
<cc>#-----------------------------</cc>
<cs>[MyHelloResource]</cs>
- <ck>greeting</ck> = <cv>Hello $A{person}!</cv>
- <ck>localizedGreeting</ck> = <cv>$L{HelloMessage,$A{person}}</cv>
+ <ck>greeting</ck> = <cv>Hello $R{path.person}!</cv>
+ <ck>localizedGreeting</ck> = <cv>$L{HelloMessage,$R{path.person}}</cv>
</p>
<p class='bcode'>
<cc>#---------------------------------</cc>
@@ -714,7 +719,7 @@
<li>The HTTP call matches the <l>/localized/{person}</l> path on the <l>sayLocalizedHello()</l> method.
<li>The request attribute <l>person</l> gets assigned the value <l>"Bob"</l>.
<li>The call to <l>req.getConfig().getString("MyHelloResource/localizedGreeting")</l>
- finds the value <l>"$L{HelloMessage,$A{person}}"</l>.
+ finds the value <l>"$L{HelloMessage,$R{path.person}}"</l>.
<li>The arguments in the <l>$L{}</l> variable get resolved, resulting in <l>"$L{HelloMessage,Bob}"</l>.
<li>The <l>$L{}</l> variable gets resolved to the message <l>"Hello {0}!"</l> in the localized properties file of the servlet based on the <l>Accept-Language</l> header on the request.
<li>The arguments get replaced in the message resulting in <l>"Hello Bob!"</l>.
@@ -743,7 +748,7 @@
*/</jd>
<ja>@RestResource</ja>(
path=<js>"/"</js>,
- label=<js>"Juneau Microservice Template"</js>,
+ title=<js>"Juneau Microservice Template"</js>,
description=<js>"Template for creating REST microservices"</js>,
properties={
<ja>@Property</ja>(name=<jsf>HTMLDOC_links</jsf>, value=<js>"{options:'$R{servletURI}?method=OPTIONS'}"</js>)
@@ -782,7 +787,7 @@
*/</jd>
<ja>@RestResource</ja>(
path=<js>"/helloWorld"</js>,
- label=<js>"Hello World example"</js>,
+ title=<js>"Hello World example"</js>,
description=<js>"Simplest possible REST resource"</js>
)
<jk>public class</jk> HelloWorldResource <jk>extends</jk> Resource {
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/cc399df5/juneau-microservice/src/main/java/org/apache/juneau/microservice/resources/ConfigResource.java
----------------------------------------------------------------------
diff --git a/juneau-microservice/src/main/java/org/apache/juneau/microservice/resources/ConfigResource.java b/juneau-microservice/src/main/java/org/apache/juneau/microservice/resources/ConfigResource.java
index 2e3cc4f..f09e860 100755
--- a/juneau-microservice/src/main/java/org/apache/juneau/microservice/resources/ConfigResource.java
+++ b/juneau-microservice/src/main/java/org/apache/juneau/microservice/resources/ConfigResource.java
@@ -74,7 +74,7 @@ public class ConfigResource extends Resource {
@RestMethod(name="GET", path="/{section}",
description="Show config file section.",
parameters={
- @Var(in="path", name="section", description="Section name.")
+ @Parameter(in="path", name="section", description="Section name.")
}
)
public ObjectMap getConfigSection(@Path("section") String section) throws Exception {
@@ -92,8 +92,8 @@ public class ConfigResource extends Resource {
@RestMethod(name="GET", path="/{section}/{key}",
description="Show config file entry.",
parameters={
- @Var(in="path", name="section", description="Section name."),
- @Var(in="path", name="key", description="Entry name.")
+ @Parameter(in="path", name="section", description="Section name."),
+ @Parameter(in="path", name="key", description="Entry name.")
}
)
public String getConfigEntry(@Path("section") String section, @Path("key") String key) throws Exception {
@@ -110,7 +110,7 @@ public class ConfigResource extends Resource {
@RestMethod(name="POST", path="/",
description="Sets contents of config file from a FORM post.",
parameters={
- @Var(in="formData", name="contents", description="New contents in INI file format.")
+ @Parameter(in="formData", name="contents", description="New contents in INI file format.")
}
)
public ConfigFile setConfigContentsFormPost(@FormData("contents") String contents) throws Exception {
@@ -127,7 +127,7 @@ public class ConfigResource extends Resource {
@RestMethod(name="PUT", path="/",
description="Sets contents of config file.",
parameters={
- @Var(in="body", description="New contents in INI file format.")
+ @Parameter(in="body", description="New contents in INI file format.")
}
)
public ConfigFile setConfigContents(@Body Reader contents) throws Exception {
@@ -146,8 +146,8 @@ public class ConfigResource extends Resource {
@RestMethod(name="PUT", path="/{section}",
description="Add or overwrite a config file section.",
parameters={
- @Var(in="path", name="section", description="Section name."),
- @Var(in="body", description="New contents for section as a simple map with string keys and values.")
+ @Parameter(in="path", name="section", description="Section name."),
+ @Parameter(in="body", description="New contents for section as a simple map with string keys and values.")
}
)
public ObjectMap setConfigSection(@Path("section") String section, @Body Map<String,String> contents) throws Exception {
@@ -167,9 +167,9 @@ public class ConfigResource extends Resource {
@RestMethod(name="PUT", path="/{section}/{key}",
description="Add or overwrite a config file entry.",
parameters={
- @Var(in="path", name="section", description="Section name."),
- @Var(in="path", name="key", description="Entry name."),
- @Var(in="body", description="New value as a string.")
+ @Parameter(in="path", name="section", description="Section name."),
+ @Parameter(in="path", name="key", description="Entry name."),
+ @Parameter(in="body", description="New value as a string.")
}
)
public String setConfigSection(@Path("section") String section, @Path("key") String key, @Body String value) throws Exception {
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/cc399df5/juneau-microservice/src/main/java/org/apache/juneau/microservice/resources/DirectoryResource.java
----------------------------------------------------------------------
diff --git a/juneau-microservice/src/main/java/org/apache/juneau/microservice/resources/DirectoryResource.java b/juneau-microservice/src/main/java/org/apache/juneau/microservice/resources/DirectoryResource.java
index e18a9ad..d8cda6a 100755
--- a/juneau-microservice/src/main/java/org/apache/juneau/microservice/resources/DirectoryResource.java
+++ b/juneau-microservice/src/main/java/org/apache/juneau/microservice/resources/DirectoryResource.java
@@ -56,7 +56,7 @@ import org.apache.juneau.utils.*;
*/
@RestResource(
title="File System Explorer",
- description="Contents of $A{path}",
+ description="Contents of $R{attribute.path}",
messages="nls/DirectoryResource",
properties={
@Property(name=HTML_uriAnchorText, value=PROPERTY_NAME),
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/cc399df5/juneau-samples/src/main/java/org/apache/juneau/server/samples/MethodExampleResource.java
----------------------------------------------------------------------
diff --git a/juneau-samples/src/main/java/org/apache/juneau/server/samples/MethodExampleResource.java b/juneau-samples/src/main/java/org/apache/juneau/server/samples/MethodExampleResource.java
index c9a1765..5c83aaf 100755
--- a/juneau-samples/src/main/java/org/apache/juneau/server/samples/MethodExampleResource.java
+++ b/juneau-samples/src/main/java/org/apache/juneau/server/samples/MethodExampleResource.java
@@ -66,14 +66,14 @@ public class MethodExampleResource extends Resource {
String method = req.getMethod();
// Attributes (from URL pattern variables)
- String a1 = req.getAttribute("a1", String.class);
- int a2 = req.getAttribute("a2", int.class);
- UUID a3 = req.getAttribute("a3", UUID.class);
+ String a1 = req.getPathParameter("a1", String.class);
+ int a2 = req.getPathParameter("a2", int.class);
+ UUID a3 = req.getPathParameter("a3", UUID.class);
// Optional GET parameters
- int p1 = req.getParameter("p1", int.class, 0);
- String p2 = req.getParameter("p2", String.class);
- UUID p3 = req.getParameter("p3", UUID.class);
+ int p1 = req.getQueryParameter("p1", int.class, 0);
+ String p2 = req.getQueryParameter("p2", String.class);
+ UUID p3 = req.getQueryParameter("p3", UUID.class);
// URL pattern post-match
String remainder = req.getPathRemainder();
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/cc399df5/juneau-samples/src/main/java/org/apache/juneau/server/samples/RootResources.java
----------------------------------------------------------------------
diff --git a/juneau-samples/src/main/java/org/apache/juneau/server/samples/RootResources.java b/juneau-samples/src/main/java/org/apache/juneau/server/samples/RootResources.java
index bbabc14..206f99c 100755
--- a/juneau-samples/src/main/java/org/apache/juneau/server/samples/RootResources.java
+++ b/juneau-samples/src/main/java/org/apache/juneau/server/samples/RootResources.java
@@ -30,6 +30,7 @@ import org.apache.juneau.server.samples.addressbook.*;
},
children={
HelloWorldResource.class,
+ SystemPropertiesResource.class,
MethodExampleResource.class,
RequestEchoResource.class,
TempDirResource.class,
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/cc399df5/juneau-samples/src/main/java/org/apache/juneau/server/samples/SystemPropertiesResource.java
----------------------------------------------------------------------
diff --git a/juneau-samples/src/main/java/org/apache/juneau/server/samples/SystemPropertiesResource.java b/juneau-samples/src/main/java/org/apache/juneau/server/samples/SystemPropertiesResource.java
new file mode 100644
index 0000000..e9cee37
--- /dev/null
+++ b/juneau-samples/src/main/java/org/apache/juneau/server/samples/SystemPropertiesResource.java
@@ -0,0 +1,153 @@
+// ***************************************************************************************************************************
+// * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file *
+// * distributed with this work for additional information regarding copyright ownership. The ASF licenses this file *
+// * to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance *
+// * with the License. You may obtain a copy of the License at *
+// * *
+// * http://www.apache.org/licenses/LICENSE-2.0 *
+// * *
+// * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an *
+// * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the *
+// * specific language governing permissions and limitations under the License. *
+// ***************************************************************************************************************************
+package org.apache.juneau.server.samples;
+
+import static org.apache.juneau.html.HtmlDocSerializerContext.*;
+
+import java.util.*;
+
+import org.apache.juneau.dto.swagger.*;
+import org.apache.juneau.encoders.*;
+import org.apache.juneau.server.*;
+import org.apache.juneau.server.annotation.*;
+
+@RestResource(
+ path="/systemProperties",
+ title="System properties resource",
+ description="REST interface for performing CRUD operations on system properties.",
+ properties={
+ @Property(name=SERIALIZER_quoteChar, value="'"),
+ @Property(name=HTMLDOC_links, value="{up:'$R{requestParentURI}',options:'$R{servletURI}?method=OPTIONS'}"),
+ },
+ stylesheet="styles/devops.css",
+ encoders=GzipEncoder.class,
+ contact="{name:'John Smith',email:'john@smith.com'}",
+ 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 SystemPropertiesResource extends RestServletDefault {
+ private static final long serialVersionUID = 1L;
+
+ @RestMethod(
+ name="GET", path="/",
+ summary="Show all system properties",
+ description="Returns all system properties defined in the JVM.",
+ parameters={
+ @Parameter(in="query", name="sort", description="Sort results alphabetically.", _default="false")
+ },
+ responses={
+ @Response(value=200, description="Returns a map of key/value pairs.")
+ }
+ )
+ @SuppressWarnings({"rawtypes", "unchecked"})
+ public Map getSystemProperties(@Query("sort") boolean sort) throws Throwable {
+ if (sort)
+ return new TreeMap(System.getProperties());
+ return System.getProperties();
+ }
+
+ @RestMethod(
+ name="GET", path="/{propertyName}",
+ summary="Get system property",
+ description="Returns the value of the specified system property.",
+ parameters={
+ @Parameter(in="path", name="propertyName", description="The system property name.")
+ },
+ responses={
+ @Response(value=200, description="The system property value, or null if not found.")
+ }
+ )
+ public String getSystemProperty(@Path String propertyName) throws Throwable {
+ return System.getProperty(propertyName);
+ }
+
+ @RestMethod(
+ name="PUT", path="/{propertyName}",
+ summary="Replace system property",
+ description="Sets a new value for the specified system property.",
+ guards=AdminGuard.class,
+ parameters={
+ @Parameter(in="path", name="propertyName", description="The system property name."),
+ @Parameter(in="body", description="The new system property value."),
+ },
+ responses={
+ @Response(value=302,
+ headers={
+ @Parameter(name="Location", description="The root URL of this resource.")
+ }
+ ),
+ @Response(value=403, description="User is not an admin.")
+ }
+ )
+ public Redirect setSystemProperty(@Path String propertyName, @Body String value) {
+ System.setProperty(propertyName, value);
+ return new Redirect();
+ }
+
+ @RestMethod(
+ name="POST", path="/",
+ summary="Add an entire set of system properties",
+ description="Takes in a map of key/value pairs and creates a set of new system properties.",
+ guards=AdminGuard.class,
+ parameters={
+ @Parameter(in="path", name="propertyName", description="The system property key."),
+ @Parameter(in="body", description="The new system property values.", schema="{example:{key1:'val1',key2:123}}"),
+ },
+ responses={
+ @Response(value=302,
+ headers={
+ @Parameter(name="Location", description="The root URL of this resource.")
+ }
+ ),
+ @Response(value=403, description="Unauthorized: User is not an admin.")
+ }
+ )
+ public Redirect setSystemProperties(@Body java.util.Properties newProperties) {
+ System.setProperties(newProperties);
+ return new Redirect();
+ }
+
+ @RestMethod(
+ name="DELETE", path="/{propertyName}",
+ summary="Delete system property",
+ description="Deletes the specified system property.",
+ guards=AdminGuard.class,
+ parameters={
+ @Parameter(in="path", name="propertyName", description="The system property name."),
+ },
+ responses={
+ @Response(value=302,
+ headers={
+ @Parameter(name="Location", description="The root URL of this resource.")
+ }
+ ),
+ @Response(value=403, description="Unauthorized: User is not an admin")
+ }
+ )
+ public Redirect deleteSystemProperty(@Path String propertyName) {
+ System.clearProperty(propertyName);
+ return new Redirect();
+ }
+
+ @RestMethod(
+ name="OPTIONS", path="/*",
+ summary="Show resource options",
+ description="Show resource options as a Swagger doc"
+ )
+ public Swagger getOptions(RestRequest req) {
+ return req.getSwagger();
+ }
+}
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/cc399df5/juneau-samples/src/main/resources/org/apache/juneau/server/samples/addressbook/nls/AddressBookResource.properties
----------------------------------------------------------------------
diff --git a/juneau-samples/src/main/resources/org/apache/juneau/server/samples/addressbook/nls/AddressBookResource.properties b/juneau-samples/src/main/resources/org/apache/juneau/server/samples/addressbook/nls/AddressBookResource.properties
index fcb3f67..61aec3e 100755
--- a/juneau-samples/src/main/resources/org/apache/juneau/server/samples/addressbook/nls/AddressBookResource.properties
+++ b/juneau-samples/src/main/resources/org/apache/juneau/server/samples/addressbook/nls/AddressBookResource.properties
@@ -29,7 +29,7 @@ getPerson.summary = Get a single person by ID
getPerson.req.path.id.description = Person ID
getPerson.req.path.id.type = integer
getPerson.res.200.description = Returns a serialized Person bean
-getAllPeople.res.200.examples = {'text/json':"{\n\turi:'http://hostname/addressBook/person/1',\n\taddressBookUri:'http://localhost/addressBook',\n\tid:1,\n\tname:'John Smith',\n\tbirthDate:'Jan 1, 2000',\n\taddresses:[\n\t\t{\n\t\t\turi:'http://localhost/addressBook/addresses/1',\n\t\t\tpersonUri:'http://localhost/addressBook/people/1',\n\t\t\tid:1,\n\t\t\tstreet:'101 Main St',\n\t\t\tcity:'Anywhere',\n\t\t\tstate:'NY',\n\t\t\tzip:12345,\n\t\t\tisCurrent:true\n\t\t}\n\t]\n\}"}
+getPerson.res.200.examples = {'text/json':"{\n\turi:'http://hostname/addressBook/person/1',\n\taddressBookUri:'http://localhost/addressBook',\n\tid:1,\n\tname:'John Smith',\n\tbirthDate:'Jan 1, 2000',\n\taddresses:[\n\t\t{\n\t\t\turi:'http://localhost/addressBook/addresses/1',\n\t\t\tpersonUri:'http://localhost/addressBook/people/1',\n\t\t\tid:1,\n\t\t\tstreet:'101 Main St',\n\t\t\tcity:'Anywhere',\n\t\t\tstate:'NY',\n\t\t\tzip:12345,\n\t\t\tisCurrent:true\n\t\t}\n\t]\n\}"}
getPerson.res.404.description = Person ID not found
getAllAddresses.summary = Get all addresses in the address book
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/cc399df5/juneau-server-test/src/main/java/org/apache/juneau/server/test/NlsResource.java
----------------------------------------------------------------------
diff --git a/juneau-server-test/src/main/java/org/apache/juneau/server/test/NlsResource.java b/juneau-server-test/src/main/java/org/apache/juneau/server/test/NlsResource.java
index 074a410..63f46ad 100755
--- a/juneau-server-test/src/main/java/org/apache/juneau/server/test/NlsResource.java
+++ b/juneau-server-test/src/main/java/org/apache/juneau/server/test/NlsResource.java
@@ -49,20 +49,20 @@ public class NlsResource extends RestServletGroupDefault {
name="POST", path="/{a}",
description="Test1.c",
parameters={
- @Var(in="path", name="a", description="Test1.d"),
- @Var(in="query", name="b", description="Test1.e"),
- @Var(in="body", description="Test1.f"),
- @Var(in="header", name="D", description="Test1.g"),
- @Var(in="path", name="a2", description="Test1.h"),
- @Var(in="query", name="b2", description="Test1.i"),
- @Var(in="header", name="D2", description="Test1.j"),
+ @Parameter(in="path", name="a", description="Test1.d"),
+ @Parameter(in="query", name="b", description="Test1.e"),
+ @Parameter(in="body", description="Test1.f"),
+ @Parameter(in="header", name="D", description="Test1.g"),
+ @Parameter(in="path", name="a2", description="Test1.h"),
+ @Parameter(in="query", name="b2", description="Test1.i"),
+ @Parameter(in="header", name="D2", description="Test1.j"),
},
responses={
@Response(200),
@Response(value=201,
description="Test1.l",
headers={
- @Var(in="foo", name="bar", description="Test1.m"),
+ @Parameter(in="foo", name="bar", description="Test1.m"),
}
)
}
@@ -167,20 +167,20 @@ public class NlsResource extends RestServletGroupDefault {
name="POST", path="/{a}",
description="$L{foo}",
parameters={
- @Var(in="path", name="a", description="$L{foo}"),
- @Var(in="query", name="b", description="$L{foo}"),
- @Var(in="body", description="$L{foo}"),
- @Var(in="header", name="D", description="$L{foo}"),
- @Var(in="path", name="a2", description="$L{foo}"),
- @Var(in="query", name="b2", description="$L{foo}"),
- @Var(in="header", name="D2", description="$L{foo}")
+ @Parameter(in="path", name="a", description="$L{foo}"),
+ @Parameter(in="query", name="b", description="$L{foo}"),
+ @Parameter(in="body", description="$L{foo}"),
+ @Parameter(in="header", name="D", description="$L{foo}"),
+ @Parameter(in="path", name="a2", description="$L{foo}"),
+ @Parameter(in="query", name="b2", description="$L{foo}"),
+ @Parameter(in="header", name="D2", description="$L{foo}")
},
responses={
@Response(200),
@Response(value=201,
description="$L{foo}",
headers={
- @Var(in="foo", name="bar", description="$L{foo}"),
+ @Parameter(in="foo", name="bar", description="$L{foo}"),
}
)
}
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/cc399df5/juneau-server-test/src/main/java/org/apache/juneau/server/test/OverlappingMethodsResource.java
----------------------------------------------------------------------
diff --git a/juneau-server-test/src/main/java/org/apache/juneau/server/test/OverlappingMethodsResource.java b/juneau-server-test/src/main/java/org/apache/juneau/server/test/OverlappingMethodsResource.java
index f3dc673..9c5d3ff 100755
--- a/juneau-server-test/src/main/java/org/apache/juneau/server/test/OverlappingMethodsResource.java
+++ b/juneau-server-test/src/main/java/org/apache/juneau/server/test/OverlappingMethodsResource.java
@@ -45,14 +45,14 @@ public class OverlappingMethodsResource extends RestServletDefault {
public static class Test1Guard extends RestGuard {
@Override /* RestGuard */
public boolean isRequestAllowed(RestRequest req) {
- return req.getParameter("t1","").equals("1");
+ return req.getQueryParameter("t1","").equals("1");
}
}
public static class Test2Guard extends RestGuard {
@Override /* RestGuard */
public boolean isRequestAllowed(RestRequest req) {
- return req.getParameter("t2","").equals("2");
+ return req.getQueryParameter("t2","").equals("2");
}
}
@@ -77,14 +77,14 @@ public class OverlappingMethodsResource extends RestServletDefault {
public static class Test3aMatcher extends RestMatcher {
@Override /* RestMatcher */
public boolean matches(RestRequest req) {
- return req.getParameter("t1","").equals("1");
+ return req.getQueryParameter("t1","").equals("1");
}
}
public static class Test3bMatcher extends RestMatcher {
@Override /* RestMatcher */
public boolean matches(RestRequest req) {
- return req.getParameter("t2","").equals("2");
+ return req.getQueryParameter("t2","").equals("2");
}
}
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/cc399df5/juneau-server-test/src/main/java/org/apache/juneau/server/test/ParamsResource.java
----------------------------------------------------------------------
diff --git a/juneau-server-test/src/main/java/org/apache/juneau/server/test/ParamsResource.java b/juneau-server-test/src/main/java/org/apache/juneau/server/test/ParamsResource.java
index b2cc2d1..a7e0237 100755
--- a/juneau-server-test/src/main/java/org/apache/juneau/server/test/ParamsResource.java
+++ b/juneau-server-test/src/main/java/org/apache/juneau/server/test/ParamsResource.java
@@ -117,7 +117,7 @@ public class ParamsResource extends RestServletDefault {
//====================================================================================================
@RestMethod(name="GET", path="/testParamGet/*")
public String testParamGet(RestRequest req, @Query("p1") String p1, @Query("p2") int p2) throws Exception {
- return "p1=["+p1+","+req.getParameter("p1")+","+req.getParameter("p1", String.class)+"],p2=["+p2+","+req.getParameter("p2")+","+req.getParameter("p2", int.class)+"]";
+ return "p1=["+p1+","+req.getQueryParameter("p1")+","+req.getQueryParameter("p1", String.class)+"],p2=["+p2+","+req.getQueryParameter("p2")+","+req.getQueryParameter("p2", int.class)+"]";
}
//====================================================================================================
@@ -125,7 +125,7 @@ public class ParamsResource extends RestServletDefault {
//====================================================================================================
@RestMethod(name="POST", path="/testParamPost/*")
public String testParamPost(RestRequest req, @FormData("p1") String p1, @FormData("p2") int p2) throws Exception {
- return "p1=["+p1+","+req.getParameter("p1")+","+req.getParameter("p1", String.class)+"],p2=["+p2+","+req.getParameter("p2")+","+req.getParameter("p2", int.class)+"]";
+ return "p1=["+p1+","+req.getFormDataParameter("p1")+","+req.getFormDataParameter("p1", String.class)+"],p2=["+p2+","+req.getFormDataParameter("p2")+","+req.getFormDataParameter("p2", int.class)+"]";
}
//====================================================================================================
@@ -149,7 +149,7 @@ public class ParamsResource extends RestServletDefault {
//====================================================================================================
@RestMethod(name="GET", path="/testPlainParamGet/*")
public String testPlainParamGet(RestRequest req, @Query(value="p1",format="PLAIN") String p1) throws Exception {
- return "p1=["+p1+","+req.getParameter("p1")+","+req.getParameter("p1", String.class)+"]";
+ return "p1=["+p1+","+req.getQueryParameter("p1")+","+req.getQueryParameter("p1", String.class)+"]";
}
//====================================================================================================
@@ -157,7 +157,7 @@ public class ParamsResource extends RestServletDefault {
//====================================================================================================
@RestMethod(name="POST", path="/testPlainParamPost/*")
public String testPlainParamPost(RestRequest req, @FormData(value="p1",format="PLAIN") String p1) throws Exception {
- return "p1=["+p1+","+req.getParameter("p1")+","+req.getParameter("p1", String.class)+"]";
+ return "p1=["+p1+","+req.getFormDataParameter("p1")+","+req.getFormDataParameter("p1", String.class)+"]";
}
//====================================================================================================
@@ -181,7 +181,7 @@ public class ParamsResource extends RestServletDefault {
//====================================================================================================
@RestMethod(name="GET", path="/testHasParamGet/*")
public String testHasParamGet(RestRequest req, @HasQuery("p1") boolean p1, @HasQuery("p2") Boolean p2) throws Exception {
- return "p1=["+p1+","+req.hasParameter("p1")+"],p2=["+p2+","+req.hasParameter("p2")+"]";
+ return "p1=["+p1+","+req.hasQueryParameter("p1")+"],p2=["+p2+","+req.hasQueryParameter("p2")+"]";
}
//====================================================================================================
@@ -189,7 +189,7 @@ public class ParamsResource extends RestServletDefault {
//====================================================================================================
@RestMethod(name="POST", path="/testHasParamPost/*")
public String testHasParamPost(RestRequest req, @HasFormData("p1") boolean p1, @HasFormData("p2") Boolean p2) throws Exception {
- return "p1=["+p1+","+req.hasParameter("p1")+"],p2=["+p2+","+req.hasParameter("p2")+"]";
+ return "p1=["+p1+","+req.hasFormDataParameter("p1")+"],p2=["+p2+","+req.hasFormDataParameter("p2")+"]";
}
//====================================================================================================
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/cc399df5/juneau-server/src/main/java/org/apache/juneau/server/ReaderResource.java
----------------------------------------------------------------------
diff --git a/juneau-server/src/main/java/org/apache/juneau/server/ReaderResource.java b/juneau-server/src/main/java/org/apache/juneau/server/ReaderResource.java
index 1a2805c..7367678 100755
--- a/juneau-server/src/main/java/org/apache/juneau/server/ReaderResource.java
+++ b/juneau-server/src/main/java/org/apache/juneau/server/ReaderResource.java
@@ -16,12 +16,13 @@ import java.io.*;
import java.util.*;
import org.apache.juneau.*;
+import org.apache.juneau.server.annotation.*;
import org.apache.juneau.server.response.*;
import org.apache.juneau.svl.*;
/**
* Represents the contents of a text file with convenience methods for resolving
- * {@link Var} variables and adding HTTP response headers.
+ * {@link Parameter} variables and adding HTTP response headers.
* <p>
* This class is handled special by the {@link WritableHandler} class.
*
@@ -58,7 +59,7 @@ public class ReaderResource implements Writable {
}
/**
- * Use the specified {@link VarResolver} to resolve any {@link Var StringVars} in the
+ * Use the specified {@link VarResolver} to resolve any {@link Parameter StringVars} in the
* contents of this file when the {@link #writeTo(Writer)} or {@link #toString()} methods are called.
*
* @param varSession The string variable resolver to use to resolve string variables.
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/cc399df5/juneau-server/src/main/java/org/apache/juneau/server/RestConverter.java
----------------------------------------------------------------------
diff --git a/juneau-server/src/main/java/org/apache/juneau/server/RestConverter.java b/juneau-server/src/main/java/org/apache/juneau/server/RestConverter.java
index b218936..ee81f58 100755
--- a/juneau-server/src/main/java/org/apache/juneau/server/RestConverter.java
+++ b/juneau-server/src/main/java/org/apache/juneau/server/RestConverter.java
@@ -24,7 +24,7 @@ import org.apache.juneau.server.converters.*;
* converted to some other POJO after invocation of the REST method.
* <p>
* Converters are associated with REST methods through the {@link RestMethod#converters()} annotation.
- * <h6 class='topic'>Example</h6>
+ * <h6 class='topic'>Example:</h6>
* <p class='bcode'>
* <jk>public class</jk> RequestEchoResource <jk>extends</jk> RestServlet {
*